ASP.NET déploiement web à l’aide de Visual Studio : Transformations de fichiers Web.config

par Tom Dykstra

Télécharger le projet de démarrage

Cette série de tutoriels vous montre comment déployer (publier) une application web ASP.NET sur Azure App Service Web Apps ou sur un fournisseur d’hébergement tiers, à l’aide de Visual Studio 2012 ou de Visual Studio 2010. Pour plus d’informations sur la série, consultez le premier didacticiel de la série.

Vue d’ensemble

Ce tutoriel vous montre comment automatiser le processus de modification du fichier Web.config lorsque vous le déployez dans différents environnements de destination. La plupart des applications ont des paramètres dans le fichier Web.config qui doivent être différents lorsque l’application est déployée. L’automatisation du processus d’exécution de ces modifications vous empêche de devoir les faire manuellement chaque fois que vous déployez, ce qui serait fastidieux et sujette à des erreurs.

Rappel : Si vous recevez un message d’erreur ou qu’un message d’erreur ne fonctionne pas au fur et à mesure que vous parcourez le tutoriel, veillez à consulter la page de résolution des problèmes.

Transformations Web.config et paramètres Web Deploy

Il existe deux façons d’automatiser le processus de modification des paramètres de fichier Web.config : transformations Web.config et paramètres Web Deploy. Un fichier de transformation Web.config contient le balisage XML qui spécifie comment modifier le fichier Web.config lors du déploiement. Vous pouvez spécifier différentes modifications pour des configurations de build spécifiques et pour des profils de publication spécifiques. Les configurations de build par défaut sont Debug et Release, et vous pouvez créer des configurations de build personnalisées. Un profil de publication correspond généralement à un environnement de destination. (Vous en apprendrez davantage sur les profils de publication dans le Déploiement sur IIS en tant que didacticiel sur l’environnement de test.)

Les paramètres web Deploy peuvent être utilisés pour spécifier de nombreux types de paramètres qui doivent être configurés pendant le déploiement, y compris les paramètres trouvés dans les fichiers Web.config . Lorsqu’ils sont utilisés pour spécifier les modifications de fichier Web.config , les paramètres Web Deploy sont plus complexes à configurer, mais ils sont utiles lorsque vous ne connaissez pas la valeur à définir tant que vous n’avez pas déployé. Par exemple, dans un environnement d’entreprise, vous pouvez créer un package de déploiement et le donner à une personne du service informatique pour l’installer en production, et cette personne doit être en mesure d’entrer des chaîne de connexion ou des mots de passe que vous ne connaissez pas.

Pour le scénario couvert par cette série de tutoriels, vous savez à l’avance tout ce qui doit être effectué dans le fichier Web.config . Vous n’avez donc pas besoin d’utiliser les paramètres Web Deploy. Vous allez configurer certaines transformations qui diffèrent selon la configuration de build utilisée, et certaines qui diffèrent selon le profil de publication utilisé.

Spécification des paramètres Web.config dans Azure

Si les paramètres du fichier Web.config que vous souhaitez modifier se trouvent dans l’élément <connectionStrings> ou dans le cas où vous effectuez un déploiement sur Web Apps dans Azure App Service, vous avez une autre option pour automatiser les modifications pendant le <appSettings> déploiement. Vous pouvez entrer les paramètres que vous souhaitez appliquer dans Azure dans l’onglet Configurer de la page du portail de gestion de votre application web (faites défiler vers le bas les paramètres de l’application et les sections chaîne de connexion s). Lorsque vous déployez le projet, Azure applique automatiquement les modifications. Pour plus d’informations, consultez Sites web Windows Azure : fonctionnement des chaînes d’application et des chaînes de connexion.

Fichiers de transformation par défaut

Dans Explorateur de solutions, développez Web.config pour afficher les fichiers de transformation Web.Debug.config et Web.Release.config créés par défaut pour les deux configurations de build par défaut.

Vous pouvez créer des fichiers de transformation pour les configurations de build personnalisées en cliquant avec le bouton droit sur le fichier Web.config et en choisissant Ajouter des transformations de configuration dans le menu contextuel. Pour ce didacticiel, vous n’avez pas besoin de le faire et l’option de menu est désactivée, car vous n’avez pas créé de configurations de build personnalisées.

Plus tard, vous allez créer trois fichiers de transformation supplémentaires, chacun pour les profils de publication de test, de préproduction et de production. Exemple classique d’un paramètre que vous gérez dans un fichier de transformation de profil de publication, car il dépend de l’environnement de destination est un point de terminaison WCF différent pour le test et la production. Vous allez créer des fichiers de transformation de profil de publication dans les didacticiels ultérieurs après avoir créé les profils de publication qu’ils vont utiliser.

Désactiver le mode débogage

Un exemple de paramètre qui dépend de la configuration de build plutôt que de l’environnement de destination est l’attribut debug . Pour une build Release, vous souhaitez généralement désactiver le débogage quel que soit l’environnement sur lequel vous effectuez le déploiement. Par conséquent, par défaut, les modèles de projet Visual Studio créent des fichiers de transformation Web.Release.config avec du code qui supprime l’attribut debug de l’élément compilation . Voici la configuration Web.Release.config par défaut : en plus d’un exemple de code de transformation qui est commenté, il inclut du code dans l’élément compilation qui supprime l’attribut debug :

<?xml version="1.0" encoding="utf-8"?>

<!-- For more information on using web.config transformation visit https://go.microsoft.com/fwlink/?LinkId=125889 -->

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <!--
    In the example below, the "SetAttributes" transform will change the value of 
    "connectionString" to use "ReleaseSQLServer" only when the "Match" locator 
    finds an attribute "name" that has a value of "MyDB".
    
    <connectionStrings>
      <add name="MyDB" 
        connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" 
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </connectionStrings>
  -->
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
    <!--
      In the example below, the "Replace" transform will replace the entire 
      <customErrors> section of your web.config file.
      Note that because there is only one customErrors section under the 
      <system.web> node, there is no need to use the "xdt:Locator" attribute.
      
      <customErrors defaultRedirect="GenericError.htm"
        mode="RemoteOnly" xdt:Transform="Replace">
        <error statusCode="500" redirect="InternalError.htm"/>
      </customErrors>
    -->
  </system.web>
</configuration>

L’attribut xdt:Transform="RemoveAttributes(debug)" spécifie que vous souhaitez que l’attribut debug soit supprimé de l’élément system.web/compilation dans le fichier Web.config déployé. Cette opération est effectuée chaque fois que vous déployez une build Release.

Limiter l’accès au journal des erreurs aux administrateurs

En cas d’erreur pendant l’exécution de l’application, l’application affiche une page d’erreur générique à la place de la page d’erreur générée par le système et utilise le package NuGet Elmah pour la journalisation et la création de rapports d’erreurs. L’élément customErrors du fichier Web.config de l’application spécifie la page d’erreur :

<customErrors mode="RemoteOnly" defaultRedirect="~/GenericErrorPage.aspx">
  <error statusCode="404" redirect="~/GenericErrorPage.aspx" />
</customErrors>

Pour afficher la page d’erreur, remplacez temporairement l’attribut mode de l’élément customErrors par « RemoteOnly » par « On » et exécutez l’application à partir de Visual Studio. Provoquez une erreur en demandant une URL non valide, telle que Studentsxxx.aspx. Au lieu d’une page d’erreur « La ressource est introuvable » générée par IIS, vous voyez la page GenericErrorPage.aspx .

Pour afficher le journal des erreurs, remplacez tout dans l’URL après le numéro de port par elmah.axd (par exemple http://localhost:51130/elmah.axd) et appuyez sur Entrée :

N’oubliez pas de définir l’élément customErrors en mode « RemoteOnly » lorsque vous avez terminé.

Sur votre ordinateur de développement, il est pratique d’autoriser l’accès gratuit à la page du journal des erreurs, mais en production qui serait un risque de sécurité. Pour le site de production, vous souhaitez ajouter une règle d’autorisation qui limite l’accès au journal des erreurs aux administrateurs et pour vous assurer que la restriction fonctionne également dans le test et la préproduction. Par conséquent, il s’agit d’une autre modification que vous souhaitez implémenter chaque fois que vous déployez une build Release, et qu’elle appartient donc au fichier Web.Release.config .

Ouvrez Web.Release.config et ajoutez un nouvel location élément immédiatement avant la balise de fermeture configuration , comme illustré ici.

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <!--
    In the example below, the "SetAttributes" transform will change the value of 
    "connectionString" to use "ReleaseSQLServer" only when the "Match" locator 
    finds an attribute "name" that has a value of "MyDB".
    
    <connectionStrings>
      <add name="MyDB" 
        connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" 
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </connectionStrings>
  -->
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
    <!--
      In the example below, the "Replace" transform will replace the entire 
      <customErrors> section of your web.config file.
      Note that because there is only one customErrors section under the 
      <system.web> node, there is no need to use the "xdt:Locator" attribute.
      
      <customErrors defaultRedirect="GenericError.htm"
        mode="RemoteOnly" xdt:Transform="Replace">
        <error statusCode="500" redirect="InternalError.htm"/>
      </customErrors>
    -->
  </system.web>
  <location path="elmah.axd" xdt:Transform="Insert">
    <system.web>
      <authorization>
        <allow roles="Administrator" />
        <deny users="*" />
      </authorization>
    </system.web>
  </location>
</configuration>

La Transform valeur d’attribut de « Insert » entraîne l’ajout de cet location élément en tant que frère à tous les éléments existants location dans le fichier Web.config . (Il existe déjà un location élément qui spécifie des règles d’autorisation pour la page Mettre à jour les crédits .)

Vous pouvez maintenant afficher un aperçu de la transformation pour vous assurer que vous l’avez codé correctement.

Dans Explorateur de solutions, cliquez avec le bouton droit sur Web.Release.config, puis cliquez sur Aperçu de la transformation.

Une page s’ouvre qui vous montre le fichier Web.config de développement à gauche et ce que le fichier Web.config déployé se présente à droite, avec les modifications mises en surbrillance.

( Dans la préversion, vous remarquerez peut-être des modifications supplémentaires pour lesquelles vous n’avez pas écrit de transformations : cela implique généralement la suppression d’espace blanc qui n’affecte pas les fonctionnalités.)

Lorsque vous testez le site après le déploiement, vous allez également tester pour vérifier que la règle d’autorisation est effective.

Paramètre que vous allez gérer dans les fichiers de transformation de profil de publication

Un scénario courant consiste à avoir des paramètres de fichier Web.config qui doivent être différents dans chaque environnement sur lequel vous déployez. Par exemple, une application qui appelle un service WCF peut avoir besoin d’un autre point de terminaison dans les environnements de test et de production. L’application Contoso University inclut également un paramètre de ce type. Ce paramètre contrôle un indicateur visible sur les pages d’un site qui vous indique l’environnement dans lequel vous êtes, tel que le développement, le test ou la production. La valeur de paramètre détermine si l’application ajoute « (Dev) » ou « (Test) » au titre principal de la page maître Site.Master :

L’indicateur d’environnement est omis lorsque l’application s’exécute en préproduction ou en production.

Les pages web contoso University lisent une valeur définie dans appSettings le fichier Web.config pour déterminer l’environnement dans lequel l’application s’exécute :

<appSettings>
    <add key="Environment" value="Dev" />
</appSettings>

La valeur doit être « Test » dans l’environnement de test, et « Prod » pour la préproduction et la production.

Le code suivant dans un fichier de transformation implémente cette transformation :

<appSettings>
    <add key="Environment" value="Test" xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
</appSettings>

La xdt:Transform valeur d’attribut « SetAttributes » indique que l’objectif de cette transformation est de modifier les valeurs d’attribut d’un élément existant dans le fichier Web.config . La xdt:Locator valeur d’attribut « Match(key) » indique que l’élément à modifier est celui dont key l’attribut correspond à l’attribut key spécifié ici. Le seul autre attribut de l’élément add est value, et c’est ce qui sera modifié dans le fichier Web.config déployé. Le code illustré ici entraîne le déploiement de l’attribut value de l’élément appSettings Environment sur « Test » dans le fichier Web.config déployé.

Cette transformation appartient aux fichiers de transformation de profil de publication, que vous n’avez pas encore créés. Vous allez créer et mettre à jour les fichiers de transformation qui implémentent cette modification lorsque vous créez les profils de publication pour les environnements de test, de préproduction et de production. Vous allez le faire dans le déploiement sur IIS et déployer dans des didacticiels de production .

Définition des chaînes de connexion

Bien que le fichier de transformation par défaut contient un exemple qui montre comment mettre à jour un chaîne de connexion, dans la plupart des cas, vous n’avez pas besoin de configurer chaîne de connexion transformations, car vous pouvez spécifier des chaîne de connexion dans le profil de publication. Vous allez le faire dans le déploiement sur IIS et déployer dans des didacticiels de production .

Résumé

Vous avez maintenant fait autant que possible avec les transformations Web.config avant de créer les profils de publication, et vous avez vu un aperçu de ce qui sera dans le fichier Web.config déployé.

Dans le tutoriel suivant, vous allez vous occuper des tâches de configuration de déploiement qui nécessitent la définition des propriétés du projet.

Informations supplémentaires

Pour plus d’informations sur les rubriques abordées par ce didacticiel, consultez Utilisation des transformations Web.config pour modifier les paramètres dans le fichier Web.config de destination ou le fichier app.config pendant le déploiement dans la carte de contenu de déploiement web pour Visual Studio et ASP.NET.