Syntaxe de transformation d'un fichier Web.config pour le déploiement d'un projet d'application Web
Les fichiers Web.config incluent généralement des paramètres qui doivent être différents en fonction de l'environnement dans lequel l'application s'exécute. Par exemple, vous aurez peut-être à modifier une chaîne de connexion de base de données ou à désactiver le débogage lorsque vous déployez un fichier Web.config. Pour les projets d'application Web, ASP.NET fournit des outils qui automatisent le processus de modification (transformation) des fichiers Web.config lors de leur déploiement. Pour chaque environnement dans lequel vous voulez procéder au déploiement, vous créez un fichier de transformation qui spécifie uniquement les différences entre le fichier Web.config d'origine et celui déployé sur cet environnement.
Un fichier de transformation est un fichier XML qui spécifie la manière dont un fichier Web.config doit être modifié lors de son déploiement. Les actions de transformation sont spécifiées à l'aide des attributs XML définis dans l'espace de noms XML-Document-Transform, mappé au préfixe xdt. L'espace de noms XML-Document-Transform définit deux attributs : Locator et Transform. L'attribut Locator spécifie l'élément ou l'ensemble d'éléments du fichier Web.config que vous souhaitez modifier. L'attribut Transform spécifie ce que vous souhaitez faire aux éléments trouvés par l'attribut Locator.
L'exemple suivant montre le contenu d'un fichier de transformation qui modifie une chaîne de connexion et remplace l'élément customErrors :
<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
<connectionStrings>
<add name="MyDB"
connectionString="value for the deployed Web.config file"
xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
</connectionStrings>
<system.web>
<customErrors defaultRedirect="GenericError.htm"
mode="RemoteOnly" xdt:Transform="Replace">
<error statusCode="500" redirect="InternalError.htm"/>
</customErrors>
</system.web>
</configuration>
L'élément racine d'un fichier de transformation doit spécifier l'espace de noms XML-Document-Transform dans sa balise d'ouverture, comme indiqué dans l'exemple précédent. Les éléments Transform et Locator ne sont pas reproduits dans le fichier Web.config déployé.
Les sections suivantes fournissent les informations de référence à propos de la syntaxe à utiliser dans les fichiers de transformation.
Syntaxe de l'attribut Locator
Chacune des sections suivantes explique la syntaxe d'un attribut Locator.
Condition
Spécifie une expression XPath ajoutée à l'expression XPath de l'élément actuel. Les éléments qui correspondent à l'expression XPath combinée sont sélectionnés.
Syntaxe
Locator="Condition(XPath expression)"
Exemple
L'exemple suivant indique comment sélectionner des éléments de chaîne de connexion dont la valeur d'attribut name est oldname ou un attribut providerName dont la valeur est oldprovider. Dans le fichier Web.config déployé, les éléments sélectionnés sont remplacés par l'élément spécifié dans le fichier de transformation.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="Condition(@name='oldname'
or @providerName='oldprovider')" />
</connectionStrings>
</configuration>
L'expression XPath appliquée au fichier Web.config de développement résultant de l'expression Condition spécifiée est la suivante :
configuration/connectionStrings[@name='AWLT' or @providerName='System.Data.SqlClient']
Cette expression est le résultat de la combinaison d'une condition XPath implicite pour l'élément actuel (configuration/connectionStrings) et de l'expression spécifiée explicitement.
Match
Sélectionne le ou les éléments dont la valeur correspond aux attributs spécifiés. Si plusieurs noms d'attribut sont spécifiés, seuls les éléments qui correspondent à tous les attributs spécifiés sont sélectionnés.
Syntaxe
Locator="Match(comma-delimited list of one or more attribute names)"
Exemple
L'exemple suivant indique comment sélectionner l'élément add de la chaîne de connexion dont AWLT se trouve dans l'attribut name, dans le fichier Web.config de développement. Dans le fichier Web.config déployé, l'élément sélectionné est remplacé par l'élément add spécifié dans le fichier de transformation.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="Match(name)" />
</connectionStrings>
</configuration>
XPath
Spécifie une expression XPath absolue qui s'applique au fichier Web.config de développement. (contrairement à Condition, l'expression que vous spécifiez n'est pas ajoutée à l'expression XPath implicite qui correspond à l'élément actuel)
Syntaxe
Locator="XPath(XPath expression)"
Exemple
L'exemple suivant indique comment sélectionner les mêmes éléments sélectionnés dans l'exemple précédent pour le mot clé Condition.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="XPath(configuration/connectionStrings[@name='AWLT'
or @providerName='System.Data.SqlClient'])" />
</connectionStrings>
</configuration>
Syntaxe de l'attribut Transform
Chacune des sections suivantes explique la syntaxe d'un attribut Transform.
Replace
Remplace l'élément sélectionné par l'élément spécifié dans le fichier de transformation. Si plusieurs éléments sont sélectionnés, seul le premier élément sélectionné est remplacé. Pour obtenir un exemple d'utilisation du mot clé Replace, consultez les exemples d'attributs Locator.
Syntaxe
Transform="Replace"
Insert
Ajoute l'élément défini dans le fichier de transformation en tant que frère du ou des éléments sélectionnés. Le nouvel élément est ajouté à la fin de toute collection.
Syntaxe
Transform="Insert"
Exemple
L'exemple suivant indique comment sélectionner toutes les chaînes de connexion dans le fichier Web.config de développement. Dans le fichier Web.config déployé, la chaîne de connexion spécifiée est ajoutée à la fin de la collection.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Insert" />
</connectionStrings>
</configuration>
InsertBefore
Insère l'élément défini dans la transformation XML immédiatement avant l'élément sélectionné par l'expression XPath spécifiée. L'expression XPath doit être une expression absolue, car elle s'applique au fichier Web.config de développement dans son ensemble et n'est pas uniquement ajoutée à l'expression XPath implicite de l'élément actuel.
Syntaxe
Transform="InsertBefore(XPath expression)"
Exemple
L'exemple suivant indique comment sélectionner l'élément deny qui refuse l'accès à tous les utilisateurs, puis insère un élément allow avant d'accorder l'accès aux administrateurs.
<configuration xmlns:xdt="...">
<authorization>
<allow roles="Admins"
xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />
</authorization>
</configuration>
InsertAfter
Insère l'élément défini dans la transformation XML immédiatement après l'élément sélectionné par l'expression XPath spécifiée. L'expression XPath doit être une expression absolue, car elle s'applique au fichier Web.config de développement dans son ensemble et n'est pas ajoutée à l'expression XPath implicite de l'élément actuel.
Syntaxe
Transform="InsertAfter(XPath expression)"
Exemple
L'exemple suivant indique comment sélectionner l'élément allow qui accorde l'accès aux administrateurs et insère un élément deny après avoir refusé l'accès à un utilisateur spécifié.
<configuration xmlns:xdt="...">
<authorization>
<deny users="UserName"
xdt:Transform="InsertAfter
(/configuration/system.web/authorization/allow[@roles='Admins'])" />
</authorization>
</configuration>
Supprimer
Supprime l'élément sélectionné. Si plusieurs éléments sont sélectionnés, supprime le premier élément.
Syntaxe
Transform="Remove"
Exemple
L'exemple suivant indique comment sélectionner tous les éléments add des chaînes de connexion dans le fichier Web.config de développement. Dans le fichier Web.config déployé, seul le premier élément de chaîne de connexion est supprimé.
<configuration xmlns:xdt="...">
<connectionStrings>
<add xdt:Transform="Remove" />
</connectionStrings>
</configuration>
RemoveAll
Supprime le ou les éléments sélectionnés.
Syntaxe
Transform="RemoveAll"
Exemple
L'exemple suivant indique comment sélectionner toutes les chaînes de connexion dans le fichier Web.config de développement. Dans le fichier Web.config déployé, tous les éléments sont supprimés.
<configuration xmlns:xdt="...">
<connectionStrings>
<add xdt:Transform="RemoveAll" />
</connectionStrings>
</configuration>
RemoveAttributes
Supprime tous les attributs spécifiés des éléments sélectionnés.
Syntaxe
Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"
Exemple
L'exemple suivant indique comment sélectionner tous les éléments compilation dans le fichier Web.config de développement. (étant donné qu'il ne peut y avoir qu'un seul élément compilation dans le fichier de configuration, vous n'avez pas à spécifier un attribut Locator) Dans le fichier Web.config déployé, les attributs debug et batch sont supprimés de l'élément compilation.
<configuration xmlns:xdt="...">
<compilation
xdt:Transform="RemoveAttributes(debug,batch)">
</compilation>
</configuration>
SetAttributes
Affecte les valeurs spécifiées aux attributs des éléments sélectionnés. L'attribut de transformation Replace remplace un élément entier, y compris tous ses attributs. Par opposition, l'attribut SetAttributes vous permet de laisser l'élément tel quel, mais modifie les attributs sélectionnés.
Syntaxe
Transform="SetAttributes(comma-delimited list of one or more attribute names)"
Exemple
L'exemple suivant indique comment sélectionner tous les éléments compilation dans le fichier Web.config de développement. (étant donné qu'il ne peut y avoir qu'un seul élément compilation dans le fichier de configuration, vous n'avez pas à spécifier un attribut Locator) Dans le fichier Web.config déployé, la valeur de l'attribut batch de l'élément compilation est définie sur false.
<configuration xmlns:xdt="...">
<compilation
batch="false"
xdt:Transform="SetAttributes(batch)">
</compilation>
</configuration>
Omission d'attributs Locator
Les attributs Locator sont facultatifs. Si vous ne spécifiez pas d'attribut Locator, l'élément à modifier est spécifié implicitement par l'élément pour lequel l'attribut Transform est spécifié. Dans l'exemple suivant, l'élément system.web entier est remplacé, car aucun attribut Locator n'est spécifié pour indiquer le contraire.
<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
<system.web xdt:Transform="Replace">
<customErrors defaultRedirect="GenericError.htm"
mode="RemoteOnly">
<error statusCode="500" redirect="InternalError.htm"/>
</customErrors>
</system.web>
</configuration>
Utilisation des attributs Transform et Locator sur des éléments séparés
Un attribut Transform n'a pas à être défini dans le même élément qu'un élément Locator. Vous pouvez spécifier un élément Locator pour un élément parent pour sélectionner des éléments contenant les éléments enfants que vous souhaitez utiliser. Vous pouvez ensuite spécifier un attribut Transform dans un élément enfant pour appliquer une modification aux enfants.
L'exemple suivant indique comment utiliser l'attribut Locator pour sélectionner des éléments location pour le chemin d'accès spécifié. Toutefois, seuls les éléments enfants des éléments location sélectionnés sont transformés.
<configuration xmlns:xdt="...">
<location path="C:\MySite\Admin" xdt:Locator="Match(path)">
<system.web>
<pages viewStateEncryptionMode="Always"
xdt:Transform="SetAttributes(viewStateEncryptionMode)" />
</system.web>
</location>
</configuration>
Si vous spécifiez un attribut Locator mais ne spécifiez pas l'attribut Transform dans le même élément ou dans un élément enfant, aucune modification n'est effectuée.
Notes
Un attribut Transform sur un élément parent peut affecter les éléments enfants même si aucun attribut Transform ne leur est associé.Par exemple, si vous mettez l'attribut xdt:Transform="Replace" dans l'élément system.web, tous les éléments enfants de l'élément system.web sont remplacés par le contenu du fichier de transformation.
Voir aussi
Concepts
Vue d'ensemble du déploiement de projet d'application Web ASP.NET
Historique des modifications
Date |
Historique |
Motif |
|---|---|---|
|
Mai 2011 |
Correction de l'explication du fonctionnement de la transformation Replace. |
Commentaires client. |