Développement de modules et de gestionnaires IIS 7.0 avec .NET Framework

Auteur : Mike Volodarsky

Vue d’ensemble

Le présent article porte sur le développement des fonctionnalités du serveur Web IIS 7.0 et versions ultérieures basées sur .NET Framework. Le présent article porte sur les éléments suivants :

1. Comment décider s'il faut développer un module IIS ou un gestionnaire IIS
2. Comment configurer votre environnement de développement, avec Visual Studio, Visual C# Express ou des outils en ligne de commande fournis avec .NET Framework
3. Comment créer votre premier projet
4. Comment développer un module et un gestionnaire simples
5. Comment déployer un module et un gestionnaire simples sur un serveur IIS

Pour voir certains modules et gestionnaires IIS managés réels et les télécharger pour votre application, visitez les demandes de redirection vers votre application avec le moduleHttpRedirection, obtenez de belles descriptions de répertoires pour votre site Web IIS avec DirectoryListingModuleet affichez de jolies icônes de fichier dans vos applications ASP.NET avec IconHandler.

Introduction : développement de fonctionnalités IIS avec ASP.NET

Les versions IIS antérieures à IIS 7.0 ont présenté une API C, appelée ISAPI, comme API d'extensibilité principale pour la création de fonctionnalités de serveur Web. IIS 7.0 et les versions ultérieures ont été entièrement repensées pour fournir une toute nouvelle API C++, sur laquelle sont basées toutes les fonctionnalités de la boîte, afin de permettre une extensibilité complète du serveur Web au niveau de l'exécution.

Par ailleurs, IIS pour la première fois fournit également une API .NET haute fidélité pour étendre le serveur Web, en tirant parti d'une intégration étroite avec ASP.NET 2.0. Pour vous, cette intégration signifie que vous êtes désormais en mesure d'étendre IIS avec de nouvelles fonctionnalités de serveur Web construites à l'aide des API ASP.NET 2.0 qui vous sont familières. De même, vous pouvez utiliser des modules et des gestionnaires ASP.NET 2.0 existants sur IIS, en tirant parti de ASP.NET intégration pour améliorer la puissance de votre application sans écrire de nouveau code. Pour en savoir plus sur l'intégration ASP.NET dans IIS, consultez ASP.NET Intégration à IIS 7.

Outils du commerce : choix de votre environnement de développement

Pour générer des modules et des gestionnaires IIS, utilisez n'importe quel environnement qui vous permet de développer et de compiler des assemblys .NET. Voici quelques-unes des options courantes :

1. Visual Studio 2005 Vous pouvez également télécharger la dernière version bêta de Visual Studio 2008.
2. Visual C# 2005 Express Edition, téléchargement gratuit (ou d'autres outils Express, y compris Visual Basic 2005 Express).
3. Le compilateur en ligne de commande C# (csc.exe) inclus dans le runtime .NET Framework (pour d'autres langages, vous devez télécharger le kit SDK), ainsi que votre éditeur source favori.

Les exemples de cet article utilisent C#, bien que vous puissiez développer des composants IIS dans n'importe quel autre langage .NET pris en charge (à l'exception de C++managé). L'article montre comment développer des composants d'extensibilité IIS avec les trois environnements ci-dessus.

Deux façons d'étendre IIS : module et Gestionnaire

Toutes les fonctionnalités du serveur Web IIS s'adaptent à deux catégories : les modules et les gestionnaires.

Un module, similaire au filtre ISAPI dans les versions précédentes d'IIS, participe au traitement des demandes de chaque requête afin de modifier ou d'y ajouter d'une certaine manière. Les modules d'authentification qui manipulent l'état d'authentification de la demande, les modules de compression qui compriment la réponse sortante et les modules de journalisation qui enregistrent les informations relatives à la demande dans le journal des demandes sont autant d'exemples de modules intégrés dans IIS.

Le module est une classe .NET qui implémente l'interface System.Web.IHttpModule ASP.NET et utilise les API de l'espace de noms System.Web pour participer à un ou plusieurs d'ASP. Étapes de traitement des demandes de NET.

Un gestionnaire similaire à l'extension ISAPI dans les versions précédentes d'IIS, est responsable de la gestion de la demande et de la production de la réponse pour des types de contenu spécifiques. La principale différence entre le module et le gestionnaire est que le gestionnaire est généralement mappé à un chemin ou une extension de requête particulier, et prend en charge le traitement d'une ressource de serveur spécifique à laquelle ce chemin ou cette extension correspond. Parmi les exemples de gestionnaires fournis avec IIS, citons ASP, qui traite les scripts ASP, le gestionnaire de fichiers statiques, qui sert des fichiers statiques et ASP. Gestionnaire de pages NET qui traite les pages ASPX.

Le gestionnaire est une classe .NET qui implémente ASP.NET l'interface system.Web.IHttpHandler ou System.Web.IHttpAsyncHandler et utilise les API de l'espace de noms System.Web pour produire une réponse http pour un contenu spécifique qu'il prend en charge.

Lorsque vous prévoyez de développer une fonctionnalité IIS, la première question que vous devez vous poser est de savoir si cette fonctionnalité est responsable de l'acheminement des requêtes vers une url/extension spécifique, ou si elle s'applique à toutes les requêtes ou à certaines d'entre elles sur la base de règles arbitraires. Dans le cas précédent, il doit s'agir d'un gestionnaire, et dans ce dernier, d'un module.

Le présent article illustre la création d'un module simple et d'un gestionnaire simple, les étapes courantes de création du projet et sa compilation, ainsi que les étapes spécifiques pour les déployer sur le serveur.

Prise en main : création du projet Visual Studio

Pour générer un module ou un gestionnaire, vous devez produire un assembly .NET (DLL) contenant les classes de module/gestionnaire. Si vous utilisez Visual Studio ou Visual Studio Express Tools, la première étape consiste à créer un projet de bibliothèque de classes :

1. Dans le menu « Fichier », sélectionnez « Nouveau », puis « Projet ». Dans la boîte de dialogue Nouveau projet (ci-dessous), sélectionnez le type de projet « Visual C# », puis sélectionnez la « bibliothèque de classes » dans la liste de droite des modèles installés par Visual Studio.

   

2. Nous devons ajouter une référence à l'assembly « System.Web.dll » qui contient les API utilisées pour développer des modules et des gestionnaires ASP.NET et IIS. Cliquez avec le bouton droit sur le nœud « Références » sous le nœud Projet dans l'arborescence de l'Explorateur de solutions de droite, choisissez « Ajouter une référence ... », et dans l'onglet .NET, sélectionnez l'assembly System.Web, version 2.0 (ci-dessous).

   

Écriture de code : création d'un module simple

La première tâche consiste à créer un module simple. Plus loin dans l'article, nous créons également un exemple de gestionnaire.

Pour créer un module, définissez une classe qui implémente l'interface System.Web.IHttpModule.

1. Supprimez le fichier « class1.cs » généré par le système de projet et ajoutez une nouvelle classe C# appelée MyModule en cliquant avec le bouton droit sur le projet MyIIS7Project dans l'arborescence de droite, en sélectionnant « Ajouter », « Nouvel élément », en choisissant « Classe », puis en tapant « MyModule.cs » dans le champ Nom.

2. Importez l'espace de noms System.Web afin que nous puissions facilement y accéder.

3. Rendre notre classe MyModule implémenter l'interface IHttpModule et définir les membres de l'interfaceDispose() et Init(). Pour ce faire, cliquez avec le bouton droit sur l'interface IHttpModule et choisissez l'option « Implémenter l'interface » :

   

   La méthode Dispose() est destinée à nettoyer les ressources non managées de manière déterministe lorsque le module est déchargé, de sorte que les ressources peuvent être libérées avant la finalisation de l'instance du module par le garbage collector. Vous pouvez laisser cette méthode vide la plupart du temps.

   La méthode Init (Contexte HttpApplication) est la méthode principale d'intérêt. Son rôle consiste à effectuer l'initialisation de votre module et à connecter votre module à un ou plusieurs événements de traitement des demandes disponibles sur la classe HttpApplication. Pendant le traitement de la demande, votre module est appelé pour chacun des événements auxquels il s'est abonné, ce qui lui permet d'exécuter et d'effectuer son service. Pour ce faire :

4. Abonnez-vous à un ou plusieurs des événements de traitement des demandes en connectant une méthode sur votre classe de module à l'un des événements de l'instance HttpApplication fournie. La méthode doit suivre la signature de délégué System.EventHandler. Nous définissons une nouvelle méthode, appelée OnPreExecuteRequestHandler, et la connectons à HttpApplication. Événement PreRequestRequestHandlerExecute, qui se produit juste avant que le serveur ne soit sur le point d'appeler le gestionnaire de requêtes pour la requête :

   public void Init(HttpApplication context) 
   { 
       context.PreRequestHandlerExecute += 
           newEventHandler(OnPreRequestHandlerExecute) 
   }
   

   

   À ce stade, notre module est configuré pour recevoir l'événement PreRequestHandlerExecute sur chaque requête. Vous pouvez répéter cette opération pour tous les autres événements que vous souhaitez recevoir.

5. Nous allons à présent effectuer des tâches utiles avec nos modules, afin d'illustrer l'utilisation de certaines des API ASP.NET qu'un module peut utiliser. Vérifiez si la demande spécifie un en-tête de référence, et si c'est le cas, refusez-la, comme une mauvaise façon d'empêcher les connexions à votre site Web à partir d'autres sites Web. Nous allons le faire dans notre méthode OnPreRequestHandlerExecute qui est appelée juste avant que le gestionnaire ne s'exécute sur chaque requête :

   public void OnPreRequestHandlerExecute (
      Object source, EventArgs e) 
   { 
      HttpApplication app = (HttpApplication)source; 
      HttpRequest    request = app.Context.Request; 
   
      if (!String.IsNullOrEmpty( request.Headers["Referer"] )) 
      { 
          throw new HttpException(403, 
                                                  "Uh-uh!"); 
      } 
   }
   

   

   Remarque

   L'instance HttpApplication est fournie à votre module par le biais de l'argument source et nécessite une conversion. Vous pouvez accéder au reste du modèle objet de requête à partir de l'instance HttpApplication, telle que l'objet HttpContext et l'objet HttpRequest contenu qui représente la requête.

Le code ci-dessus vérifie si l'en-tête de référence a été spécifié, et le cas échéant, il rejette la demande avec un code d'erreur non autorisé 403.

Écriture de code : création d'un gestionnaire simple

La tâche suivante consiste à créer un gestionnaire simple. Plus haut dans l'article, nous avons créé un exemple de module : revenez en arrière si vous souhaitez en savoir plus sur la création d'un module à la place.

Pour créer un gestionnaire, nous devons définir une classe qui implémente l'interface System.Web.IHttpHandler (nous pouvons également implémenter System.Web.IHttpAsyncHandler si nous voulons que la page s'exécute de manière asynchrone). Pour ce faire :

1. Si ce n'est déjà fait, supprimez le fichier « class1.cs » généré par le système de projet et ajoutez une nouvelle classe C# appelée MyHandler en cliquant avec le bouton droit sur le projet MyIIS7Project dans l'arborescence de droite, en sélectionnant « Ajouter », « Nouvel élément », en choisissant « Classe » et en tapant « MyHandler.cs » dans le champ Nom.

2. Importez l'espace de noms System.Web afin que nous puissions facilement y accéder.

3. Implémentez l'interface IHttpHandler et définissez les membres de l'interface IsReusable et ProcessRequest(). Pour ce faire, cliquez avec le bouton droit sur l'interface IHttpHandler et choisissez l'option « Implémenter l'interface » :

   

   IsReusable () indique si votre instance de gestionnaire peut être réutilisée ou non pour les demandes suivantes. Dans certains cas, après avoir traité la demande, votre gestionnaire peut se trouver dans un état incorrect pour traiter une autre demande, en particulier si vous avez stocké des données sur la demande précédente dans des variables membres. Le runtime n'utilisera jamais la même instance de votre gestionnaire pour traiter deux requêtes en même temps, même si elle est marquée comme réutilisable. Si votre gestionnaire ne stocke pas d'état par requête dans les variables membres et peut avoir sa fonction ProcessRequest appelée autant de fois que nécessaire, faites en sorte que cette propriété retourne la valeur true pour autoriser la réutilisation.

   La méthode ProcessRequest () est le point d'entrée principal du gestionnaire. Son rôle consiste à traiter la requête spécifiée par l'instance HttpRequest disponible hors de l'instance HttpContext fournie et à générer la réponse appropriée à l'aide de l'instance HttpResponse également disponible sur HttpContext. La méthode ProcessRequest() est appelée par le runtime pendant l'étape de traitement des demandes ExecuteRequestHandler, et UNIQUEMENT SI la requête mappée à votre gestionnaire en fonction des mappages de gestionnaire configurés. Cette méthode est différente de celle d'un module qui reçoit des notifications pour toutes les demandes adressées à l'application.

4. Implémentez d'abord la propriété IsReusable. Étant donné que notre gestionnaire ne stockera aucun état de membre pour la demande et qu'il pourra supporter plusieurs appels à ProcessRequest() avec différentes demandes, nous le marquerons comme réutilisable en renvoyant « true ».

   public bool IsReusable
   {
       get { return true; }
   

5. Enfin, implémentons la méthode ProcessRequest() pour rendre notre gestionnaire réellement utile. Pour que les choses soient agréables et simples, notre gestionnaire retourne l'heure actuelle sur le serveur, ce qui permet éventuellement la spécification du fuseau horaire dans la chaîne de requête. Notre objectif est de pouvoir demander une URL, comme http://myserver/time.tm, et obtenir l'heure actuelle sur le serveur. En outre, nous serons en mesure d'atteindre le temps coordonné universel en demandant http://myserver/time.tm?utc=true. Voici notre implémentation :

   public void ProcessRequest(HttpContext context) 
   { 
       DateTime dt; 
       String useUtc = context.Request.QueryString["utc"]; 
       if (!String.IsNullOrEmpty(useUtc) && 
               useUtc.Equals("true")) 
       { 
           dt = DateTime.UtcNow; 
       } 
       else 
       { 
           dt = DateTime.Now; 
       } 
       context.Response.Write( 
           String.Format( "<h1>{0}</h1>", 
                          dt.ToLongTimeString() 
                          ) ); 
   }
   

   Nous utilisons la collection HttpRequest.QueryString pour récupérer une variable QueryString et écrire l'heure actuelle de réponse à l'aide de la méthode HttpResponse.Write. Il s'agit simplement d'un exemple des types d'opérations que vous pouvez choisir de faire dans votre gestionnaire : la classe HttpRequest fournit beaucoup plus d'informations sur la requête, et la classe HttpResponse fournit plusieurs façons différentes de mettre en forme la réponse retournée au client.

   

Le gestionnaire est terminé.

Code terminé : compilation du module/gestionnaire

Maintenant que nous avons implémenté le module et le gestionnaire, nous pouvons les compiler dans un assembly qui ASP.NET peut charger au moment de l'exécution. Si vous utilisez Visual Studio ou Visual Studio Express, compilez le projet directement à partir de l'outil en appuyant sur « Ctrl-Maj-B » ou en cliquant avec le bouton droit sur le projet et en choisissant « Générer ».

L'assembly .DLL sera généré dans le <dossier ProjectDirectory>\bin\debug, ainsi que le fichier de symboles .PDB que vous pouvez utiliser pour déboguer l'assembly sur le serveur/ y compris les lignes de code source dans les exceptions pendant l'étape de débogage de votre projet.

Si vous chargez votre assemblage sur un serveur de production, veillez à modifier la configuration de la solution de manière à ce qu'elle soit « mise en production » en cliquant avec le bouton droit sur le nœud de la solution, en choisissant Gestionnaire de configuration et en modifiant le type en débogage. Chargez la version Release de l'assembly (laissez le fichier PDB derrière) : les informations de débogage seront supprimées de l'assembly et celui-ci sera optimisé, ce qui permettra d'obtenir un code plus rapide.

Si vous n'utilisez pas Visual Studio, compilez le projet avec le compilateur de ligne de commande C# inclus dans le runtime Framework. Pour compiler votre projet, ouvrez une invite de ligne de commande (veillez à exécuter l'invite de ligne de commande avec l'option « Exécuter en tant qu'administrateur » si vous êtes sur Windows Vista ou Windows Server 2008) :

> %windir%\Microsoft.NET\Framework\v2.0.50727\csc.exe /t:library /out:MyIIS7Project.dll /debug \*.cs /r:System.Web.dll

Les fichiers MyIIS7Project.DLL et MyIIS7Project.PDB sont ainsi produits. Si vous souhaitez générer une version release de l'assembly, omettez le commutateur /debug et incluez le commutateur /o pour optimiser l'assembly.

Déploiement de l'assembly sur le serveur

Le module et le gestionnaire personnalisés ayant été intégrés, nous les déployons dans notre application Web. Il existe plusieurs façons de déployer un module ou un gestionnaire sur l'application, et un certain nombre d'options de configuration que vous pouvez utiliser pour adapter leur déploiement à vos besoins. Nous allons illustrer les étapes de déploiement les plus élémentaires ci-dessous. Pour une discussion avancée sur les options de déploiement et de configuration, notamment sur le déploiement d'un module/gestionnaire pour l'ensemble du serveur, consultez l'article suivant de la série : déploiement de modules et de gestionnaires IIS (bientôt disponible).

Les étapes ci-dessous supposent que vous déployez le module et le gestionnaire sur une application existante sur votre serveur IIS. Si vous n'avez pas d'application créée, utilisez l'application racine du « site Web par défaut » généralement située à l'adresse %systemdrive%\inetpub\wwwroot. Dans l'exemple ci-dessous, nous déployons le module et le gestionnaire sur une application appelée « myiis7project » située dans le site Web par défaut.

Pour déployer le module et le gestionnaire, commencez par rendre l'assembly contenant leur implémentation disponible pour votre application ASP.NET :

1. Copiez l'assembly MyIIS7Project.dll compilé précédemment dans le répertoire /BIN situé à la racine de votre application. Si ce répertoire n'existe pas, créez-le.

2. Configurez le module et le gestionnaire à charger dans l'application. Ouvrez l'outil d'administration IIS7 par le biais du menu Démarrer, saisissez inetmgr.exe dans la zone de démarrage/recherche, puis appuyez sur Entrée. Dans l'outil, double-cliquez sur votre nœud serveur dans l'arborescence de gauche, développez le nœud « Sites », puis double-cliquez sur le site ou l'application auquel vous souhaitez ajouter votre module et votre gestionnaire.

3. Sélectionnez l'icône de fonctionnalité « Modules », puis cliquez sur l'action « Ajouter un module managé ... », puis, dans la boîte de dialogue résultante, saisissez le nom du module (arbitraire) et le type de module complet « MyIIS7Modules.MyModule ». Vous pouvez également sélectionner le type dans la zone de liste déroulante, car l'outil charge automatiquement votre assembly dans la corbeille et découvre les types qui implémentent l'interface IHttpModule. Appuyez sur OK pour ajouter le module.

   

4. Ajoutez le gestionnaire en double-cliquant à nouveau sur le nœud site/application, puis en sélectionnant l'icône de fonctionnalité « Mappages de gestionnaires ». Cliquez ensuite sur l'action « Ajouter un gestionnaire managé », puis, dans la boîte de dialogue résultante, spécifiez « time.tm » pour le chemin d'accès, « MyIIS7Modules.MyHandler » pour le type et « MyHandler » pour le nom (arbitraire). Là encore, le type est présent dans la zone de liste déroulante, car l'outil Administrateur a détecté automatiquement ce type dans votre assembly. Appuyez sur OK pour ajouter le gestionnaire.

   

La configuration de l'application générée par les actions ci-dessus configure le module MyModule à charger dans votre application (ce qui lui permet de s'exécuter pour toutes les requêtes) et mappe le gestionnaire MyHandler pour traiter les demandes à l'URL de time.tm à l'intérieur de votre application.

Cette configuration permet à votre module et à votre application de s'exécuter uniquement dans les applications en mode intégré IIS. Si vous souhaitez que le module et le gestionnaire s'exécutent également en mode Classique sur IIS, ainsi que sur les versions antérieures d'IIS, vous devez également ajouter la configuration de ASP.NET Classique pour le module et le gestionnaire. En outre, lors de l'exécution en mode Classique sur IIS ou sur des versions antérieures d'IIS, votre gestionnaire vous oblige à créer un mappage de script mappant l'extension .tm à ASP.NET dans les mappages de script IIS, et votre module s'exécute uniquement pour les demandes aux extensions mappées à ASP.NET. Pour en savoir plus sur ce problème, consultez Déploiement de modules et de gestionnaires IIS (bientôt disponible).

Vous pouvez également ajouter le module et le gestionnaire à l'aide de l'outil en ligne de commande IIS, AppCmd.exe, ou en manipulant la configuration IIS à partir d'un script ou d'un code managé, ou en plaçant la configuration directement dans le fichier Web.config. Ces options supplémentaires sont abordées en détail dans le déploiement de modules et de gestionnaires IIS (bientôt disponible).

Test du module et du gestionnaire

Nous avons déployé et configuré le module/gestionnaire. Maintenant pour les tester :

1. Testez notre gestionnaire en effectuant une demande de « time.tm » dans notre application. En cas de réussite, nous voyons l'heure actuelle sur le serveur. Effectuez une demande à votre application, comme http://localhost/myiis7project/time.tm lorsque nous avons déployé le gestionnaire sur l'application myiis7project dans le site Web par défaut :

   Si le gestionnaire est correctement déployé sur cette application, vous voyez l'heure actuelle sur le serveur :

   

   Essayez également de demander à http://localhost/myiis7project/time.tm?utc=true d'afficher l'heure en UTC.

2. Testez le module. Créez une page html simple appelée page.html dans votre application qui est liée à l'URL /time.tm :

   page.html

   <html>
     <body>
         <a href="time.tm">View current server time</a>
     </body>
   </html>
   

   Ensuite,demandez à http://localhost/myiis7project/page.html d'afficher le lien. Lorsque vous cliquez sur le lien, vous observez une erreur :

   

   Vous pouvez vous demander si nous n'avons pas simplement demandé la même URL ci-dessus et si nous n'avons pas réussi à voir l'heure. La cause en est que notre module est configuré pour rejeter les demandes adressées à votre application qui spécifient un en-tête de référence, qui est ajouté par le navigateur chaque fois qu'un utilisateur clique sur un lien pour accéder à votre site Web au lieu de saisir simplement l'URL dans le navigateur directement. Par conséquent, lorsque vous avez demandé directement l'URL, vous avez pu y accéder. Toutefois, lorsque vous avez suivi un lien d'une autre page, votre demande a été rejetée par notre module.

Résumé

Dans le présent article, nous avons présenté les étapes de base du développement d'un module et d'un gestionnaire IIS à l'aide des API ASP.NET habituelles, et de leur déploiement dans votre application. Nous avons également abordé les choix qui s'offrent à vous en matière d'environnement de développement et les critères à prendre en compte pour déterminer s'il est préférable de développer un module ou un gestionnaire. Les informations contenues dans cet article devraient vous permettre de créer vos premiers modules et gestionnaires pour optimiser vos applications IIS.

Vous pouvez également consulter un exemple de module qui active l'authentification de base sur ASP. Fournisseurs d'appartenances NET dans le développement d'un module à l'aide de .NET.

Veillez à consulter d'autres exemples de la façon dont les modules et gestionnaires IIS managés peuvent ajouter de la valeur à vos applications et les télécharger pour votre application en accédant aux demandes de redirection vers votre application avec le moduleHttpRedirection, obtenir de belles descriptions de répertoires pour votre site Web IIS avec DirectoryListingModule, et afficher de jolies icônes de fichier dans vos applications ASP.NET avec IconHandler.