Syntaxe de transformation d'un fichier Web.config pour le déploiement d'un projet d'application Web à l'aide de Visual Studio

  • Article

Cette rubrique fournit des informations de référence sur la syntaxe d' xdt:Transform et d' xdt:Locator que vous utilisez dans les fichiers de transformation Web.config dans les produits suivants :

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 transformations soient appliquées pendant le déploiement, mais vous pouvez afficher un aperçu des modifications dans Visual Studio. Dans Explorateur de solutions, cliquez avec le bouton droit sur le fichier de transformation (par exemple, Web.Release.config) et sélectionnez transformation d'aperçu. Visual Studio affiche le fichier Web.config d'origine et le fichier Web.config transformé côte à côte.

Syntaxe de l'attribut Locator

Chacune des sections suivantes explique la syntaxe d'un attribut Locator.

Dd465326.collapse_all(fr-fr,VS.110).gifCondition

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.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Locator="Condition(XPath expression)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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/add[@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.

Dd465326.collapse_all(fr-fr,VS.110).gifMatch

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.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Locator="Match(comma-delimited list of one or more attribute names)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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>

Dd465326.collapse_all(fr-fr,VS.110).gifXPath

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)

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Locator="XPath(XPath expression)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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.

Dd465326.collapse_all(fr-fr,VS.110).gifReplace

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.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="Replace"

Dd465326.collapse_all(fr-fr,VS.110).gifInsert

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.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="Insert"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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>

Dd465326.collapse_all(fr-fr,VS.110).gifInsertBefore

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.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="InsertBefore(XPath expression)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

L'exemple suivant indique comment sélectionner l'élément d' deny qui refuse l'accès à tous les utilisateurs. Il insère ensuite un élément d' allow avant l'élément d' deny pour accorder l'accès aux administrateurs.

<configuration xmlns:xdt="...">
  <authorization>
    <allow roles="Admins"
      xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />
  </authorization>
</configuration>

Dd465326.collapse_all(fr-fr,VS.110).gifInsertAfter

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.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="InsertAfter(XPath expression)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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>

Dd465326.collapse_all(fr-fr,VS.110).gifEnlever

Supprime l'élément sélectionné. Si plusieurs éléments sont sélectionnés, supprime le premier élément.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="Remove"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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>

Dd465326.collapse_all(fr-fr,VS.110).gifRemoveAll

Supprime le ou les éléments sélectionnés.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="RemoveAll"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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>

Dd465326.collapse_all(fr-fr,VS.110).gifRemoveAttributes

Supprime tous les attributs spécifiés des éléments sélectionnés.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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>

Dd465326.collapse_all(fr-fr,VS.110).gifSetAttributes

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. Si vous ne spécifiez pas qui l'attribut à la modification, tous les attributs qui sont présents dans l'élément du fichier de transformation sont modifiés.

La transformation d' SetAttributes affecte tous les éléments sélectionnés. Ce comportement est différent de l'attribut de transformation d' Replace , qui affecte uniquement le premier élément sélectionné si plusieurs éléments sont sélectionnés.

Dd465326.collapse_all(fr-fr,VS.110).gifSyntaxe

Transform="SetAttributes(comma-delimited list of one or more attribute names)"

Dd465326.collapse_all(fr-fr,VS.110).gifExemple

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

Organigramme des informations relatives au déploiement Web pour Visual Studio et ASP.NET

Autres ressources

Transformations du fichier Web.config (didacticiel sur le site ASP.NET)