Transformations de fichiers et référence de substitution de variable
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
Certaines tâches, telles que la tâche de déploiement Azure App Service version 3 et ultérieure et la tâche de déploiement d’application web IIS, permettent aux utilisateurs de configurer le package en fonction de l’environnement spécifié. Ces tâches utilisent msdeploy.exe, qui prend en charge la substitution de valeurs dans le fichier web.config avec les valeurs du fichier parameters.xml . Toutefois, les transformations de fichiers et la substitution de variables ne sont pas limitées aux fichiers d’application web. Vous pouvez utiliser ces techniques avec n’importe quel fichier XML ou JSON.
Notes
Les transformations de fichiers et substitutions de variables sont également prises en charge par la tâche Transformation de fichier à utiliser dans Azure Pipelines. Vous pouvez utiliser la tâche Transformation de fichier pour appliquer des transformations de fichiers et substitutions de variables à tout fichier de configuration et de paramètres.
La substitution de configuration est spécifiée dans la section Options de transformation de fichier et de substitution de variables des paramètres des tâches. Les options de transformation et de substitution sont les suivantes :
Lorsque la tâche s’exécute, elle effectue d’abord une transformation XML, une substitution de variable XML et une substitution de variable JSON sur les fichiers de configuration et de paramètres. Ensuite, il appelle msdeploy.exe, qui utilise le fichier parameters.xml pour remplacer les valeurs dans le fichier web.config .
Transformation XML
La transformation XML prend en charge la transformation des fichiers de configuration (*.config fichiers) en suivant la syntaxe de transformation Web.config et est basée sur l’environnement dans lequel le package web sera déployé.
Cette option est utile lorsque vous souhaitez ajouter, supprimer ou modifier des configurations pour différents environnements.
La transformation sera appliquée à d’autres fichiers de configuration, y compris les fichiers de configuration de la console ou de l'application de service Windows (par exemple, FabrikamService.exe.config).
Conventions de nommage de fichier de transformation de configuration
La transformation XML sera exécutée sur le fichier pour les *.config fichiers de configuration de transformation nommés *.Release.config ou *.<stage>.config et sera exécutée dans l’ordre suivant :
*.Release.config(par exemple, fabrikam.Release.config)*.<stage>.config(par exemple, fabrikam.Production.config)
Par exemple, si votre package contient les fichiers suivants :
- Web.config
- Web.Debug.config
- Web.Release.config
- Web.Production.config
et votre nom d’étape est Production, la transformation est appliquée Web.config avec suivi Web.Release.config de Web.Production.config.
Exemple de transformation XML
Créez un package d’application web avec les fichiers de configuration et de transformation nécessaires. Par exemple, utilisez les fichiers de configuration suivants :
Fichier de configuration
<?xml version="1.0" encoding="utf-8"?> <configuration> <connectionStrings> <add name="DefaultConnection" connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" /> </connectionStrings> <appSettings> <add key="webpages:Version" value="3.0.0.0" /> <add key="webpages:Enabled" value="false" /> </appSettings> <system.web> <authentication mode="None" /> <compilation targetFramework="4.5" debug="true" /> </system.web> </configuration>Fichier de transformation
<?xml version="1.0"?> <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform"> <connectionStrings> <add name="MyDB" connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" xdt:Transform="Insert" /> </connectionStrings> <appSettings> <add xdt:Transform="Replace" xdt:Locator="Match(key)" key="webpages:Enabled" value="true" /> </appSettings> <system.web> <compilation xdt:Transform="RemoveAttributes(debug)" /> </system.web> </configuration>Cet exemple de fichier de configuration de transformation effectue trois opérations :
- Il ajoute une nouvelle chaîne de connexion de base de données à l’intérieur de l’élément
ConnectionStrings. - Il modifie la valeur de
Webpages:Enabledà l’intérieur de l’élémentappSettings. - Il supprime l’attribut
debugde l’élémentcompilationà l’intérieur de l’élémentSystem.Web.
Pour plus d’informations, consultez Syntaxe de transformation d'un fichier Web.config pour le déploiement d'un projet Web à l'aide de Visual Studio
- Il ajoute une nouvelle chaîne de connexion de base de données à l’intérieur de l’élément
Créez un pipeline de mise en production avec une étape nommée Mise en production.
Ajoutez une tâche de déploiement Azure App Service et définissez (cochez) l’option de transformation XML.
Enregistrez le pipeline de mise en production et démarrez une nouvelle mise en production.
Ouvrez le
Web.configfichier pour voir les transformations deWeb.Release.config.<?xml version="1.0" encoding="utf-8"?> <configuration> <connectionStrings> <add name="DefaultConnection" connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" /> <add name="MyDB" connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" /> </connectionStrings> <appSettings> <add key="webpages:Version" value="3.0.0.0" /> <add key="webpages:Enabled" value="true" /> </appSettings> <system.web> <authentication mode="None" /> <compilation targetFramework="4.5" /> </system.web> </configuration>
Notes de transformation XML
Vous pouvez utiliser cette technique pour créer un package par défaut et le déployer sur plusieurs étapes.
La transformation XML prend effet uniquement lorsque le fichier de configuration et le fichier de transformation se trouvent dans le même dossier au sein du package spécifié.
Par défaut, MSBuild applique la transformation car il génère le package web si l’élément
<DependentUpon>est déjà présent dans le fichier de transformation dans le*.csprojfichier. Dans ce cas, la tâche de déploiement Azure App Service échoue, car aucune transformation supplémentaire n’est appliquée auWeb.configfichier. Par conséquent, il est recommandé de supprimer l’élément<DependentUpon>de tous les fichiers de transformation pour désactiver toute configuration au moment de la build lors de l’utilisation de la transformation XML.Définissez la propriété Action de génération pour chacun des fichiers de transformation (
Web.config) sur Contenu afin que les fichiers soient copiés dans le dossier racine.... <Content Include="Web.Debug.config"> <DependentUpon>Web.config</DependentUpon> </Content> <Content Include="Web.Release.config"> <DependentUpon>Web.config</DependentUpon> </Content> ...
Substitution de variable XML
Cette fonctionnalité vous permet de modifier les paramètres de configuration dans les fichiers de configuration (fichiers *.config) à l’intérieur des packages web et des fichiers de paramètres XML (parameters.xml).
De cette façon, le même package peut être configuré en fonction de l’environnement dans lequel il sera déployé.
La substitution de variable prend effet uniquement sur les éléments applicationSettings, appSettings, connectionStringset configSections des fichiers de configuration. Si vous cherchez à remplacer des valeurs en dehors de ces éléments, vous pouvez utiliser un fichier (parameters.xml), mais vous devez utiliser une tâche de pipeline tierce pour gérer la substitution de variable.
Exemple de substitution de variable XML
Par exemple, considérez la tâche de modification des valeurs suivantes dans Web.config :
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSection>
<section name="entityFramework" />
</configSection>
<connectionStrings>
<!-- Change connectionString in this line: -->
<add name="DefaultConnection"
connectionString="Data Source=(LocalDB)\LocalDB;FileName=Local.mdf" />
</connectionStrings>
<appSettings>
<add key="ClientValidationEnabled" value="true" />
<add key="UnobstructiveJavascriptEnabled" value="true" />
<!-- Change AdminUserName in this line: -->
<add key="AdminUserName" value="__AdminUserName__" />
<!-- Change AdminPassword in this line: -->
<add key="AdminPassword" value="__AdminPassword__" />
</appSettings>
<entityFramework>
<defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
<parameters></parameters>
</defaultConnectionFactory>
<providers>
<!-- Change invariantName in this line: -->
<provider invariantName="System.Data.SqlClient" type="System.Data.Entity.SqlServer" />
</providers>
</entityFramework>
</configuration>
Créez un pipeline de mise en production avec une étape nommée Mise en production.
Ajoutez une tâche de déploiement Azure App Service et définissez (cochez) l’option de substitution de variable XML.
Définissez les valeurs requises dans les variables de pipeline de mise en production :
Nom Valeur Sécuriser Étendue DefaultConnection Source de données=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf No Libérer AdminUserName ProdAdminName No Libérer AdminPassword [votre mot de passe] Oui Libérer invariantName System.Data.SqlClientExtension No Libérer Enregistrez le pipeline de mise en production et démarrez une nouvelle mise en production.
Ouvrez le fichier
Web.configpour voir les substitutions de variables.<?xml version="1.0" encoding="utf-8"?> <configuration> <configSection> <section name="entityFramework" /> </configSection> <connectionStrings> <add name="DefaultConnection" connectionString="Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf" /> </connectionStrings> <appSettings> <add key="ClientValidationEnabled" value="true" /> <add key="UnobstructiveJavascriptEnabled" value="true" /> <add key="AdminUserName" value="ProdAdminName" /> <add key="AdminPassword" value="*password_masked_for_display*" /> </appSettings> <entityFramework> <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory"> <parameters></parameters> </defaultConnectionFactory> <providers> <provider invariantName="System.Data.SqlClientExtension" type="System.Data.Entity.SqlServer" /> </providers> </entityFramework> </configuration>
Notes sur la substitution de variable XML
Par défaut, les applications ASP.NET ont un attribut de connexion paramétrable par défaut. Ces valeurs sont remplacées uniquement dans le fichier
parameters.xmlà l’intérieur du package web.Étant donné que la substitution se produit avant le déploiement, l’utilisateur peut remplacer les valeurs dans
Web.configusingparameters.xml(à l’intérieur du package web) ou dans un fichiersetparameters.
Substitution de variable JSON
Cette fonctionnalité remplace les valeurs dans les fichiers de configuration JSON.
Elle remplace les valeurs dans les fichiers de configuration JSON spécifiés (par exemple, appsettings.json) par les valeurs correspondant aux noms des variables de pipeline de mise en production et de phase.
Pour remplacer des variables dans des fichiers JSON spécifiques, fournissez une liste de fichiers JSON séparés par une nouvelle ligne. Les noms de fichiers doivent être spécifiés par rapport au dossier racine. Par exemple, si votre package a cette structure :
/WebPackage(.zip)
/---- content
/----- website
/---- appsettings.json
/---- web.config
/---- [other folders]
/--- archive.xml
/--- systeminfo.xml
et que vous souhaitez remplacer des valeurs dans appsettings.json, entrez le chemin d’accès relatif à partir du dossier racine ; par exemple content/website/appsettings.json.
Vous pouvez également utiliser des modèles génériques pour rechercher des fichiers JSON spécifiques.
Par exemple, **/appsettings.json retourne le chemin d’accès relatif et le nom des fichiers nommés appsettings.json.
Exemple de substitution de variable JSON
Par exemple, considérez la tâche de substitution de valeurs dans ce fichier JSON :
{
"Data": {
"DefaultConnection": {
"ConnectionString": "Data Source=(LocalDb)\\MSDB;AttachDbFilename=aspcore-local.mdf;"
},
"DebugMode": "enabled",
"DBAccess": {
"Administrators": ["Admin-1", "Admin-2"],
"Users": ["Vendor-1", "vendor-3"]
},
"FeatureFlags": {
"Preview": [
{
"newUI": "AllAccounts"
},
{
"NewWelcomeMessage": "Newusers"
}
]
}
}
}
La tâche consiste à remplacer les valeurs de ConnectionString, DebugMode, la première des valeurs Users et NewWelcomeMessage aux emplacements respectifs de la hiérarchie de fichiers JSON.
Créez un pipeline de mise en production avec une étape nommée Mise en production.
Ajoutez une tâche de déploiement Azure App Service et entrez une liste de fichiers JSON séparés par une ligne pour remplacer les valeurs de variable dans la zone de texte substitution de variable JSON. Les noms de fichiers doivent être relatifs au dossier racine. Vous pouvez utiliser des caractères génériques pour rechercher des fichiers JSON. Par exemple :
**/*.jsonsignifie remplacer des valeurs dans tous les fichiers JSON du package.
Définissez les valeurs de substitution requises dans les variables de pipeline de mise en production ou de phase.
Nom Valeur Sécuriser Étendue Data.DebugMode disabled No Libérer Data.DefaultConnection.ConnectionString Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf; Non Libérer Data.DBAccess.Users.0 Admin-3 Oui Libérer Data.FeatureFlags.Preview.1.NewWelcomeMessage AllAccounts Non Libérer Enregistrez le pipeline de mise en production et démarrez une nouvelle mise en production.
Après la transformation, le JSON contient les éléments suivants :
{ "Data": { "DefaultConnection": { "ConnectionString": "Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;" }, "DebugMode": "disabled", "DBAccess": { "Administrators": ["Admin-1", "Admin-2"], "Users": ["Admin-3", "vendor-3"] }, "FeatureFlags": { "Preview": [ { "newUI": "AllAccounts" }, { "NewWelcomeMessage": "AllAccounts" } ] } } } '''
Notes sur la substitution de variable JSON
Pour remplacer des valeurs dans les niveaux imbriqués du fichier, concatènez les noms avec un point (
.) dans l’ordre hiérarchique.Un objet JSON peut contenir un tableau dont les valeurs peuvent être référencées par leur index. Par exemple, pour remplacer la première valeur du tableau Utilisateurs ci-dessus, utilisez le nom
DBAccess.Users.0de la variable . Pour mettre à jour la valeur dans NewWelcomeMessage, utilisez le nomFeatureFlags.Preview.1.NewWelcomeMessagede la variable. Toutefois, la tâche de transformation de fichier a la possibilité de transformer des tableaux entiers dans des fichiers JSON. Vous pouvez également utiliserDBAccess.Users = ["NewUser1","NewUser2","NewUser3"].Seule la substitution de chaîne est prise en charge pour la substitution de variable JSON.
La substitution est prise en charge uniquement pour les fichiers encodés UTF-8 et UTF-16 LE.
Si la spécification de fichier que vous entrez ne correspond à aucun fichier, la tâche échoue.
La correspondance de nom de variable respecte la casse.
La substitution de variable est appliquée uniquement pour les clés JSON prédéfinies dans la hiérarchie d’objets. Elle ne crée pas de nouvelles clés.
Si un nom de variable inclut des points (« . »), la transformation tente de localiser l’élément dans la hiérarchie. Par exemple, si le nom de la variable est
first.second.third, le processus de transformation recherche :"first" : { "second": { "third" : "value" } }ainsi que
"first.second.third" : "value".
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour