Referens för filtransformering och variabel ersättning

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Vissa uppgifter, till exempel Azure App Service Deploy task version 3 och senare och IIS Web App Deploy-uppgiften , gör det möjligt för användare att konfigurera paketet baserat på den angivna miljön. Dessa uppgifter använder msdeploy.exe, som stöder åsidosättande av värden i filen web.config med värden från parameters.xml-filen. Filtransformeringar och variabelersättning är dock inte begränsade till webbappfiler. Du kan använda dessa tekniker med xml- eller JSON-filer.

Kommentar

Filtransformeringar och variabelersättning stöds också av den separata filtransformeringsaktiviteten för användning i Azure Pipelines. Du kan använda filtransformeringsaktiviteten för att tillämpa filtransformeringar och variabelersättningar på alla konfigurations- och parameterfiler.

Konfigurationsersättning anges i avsnittet Alternativ för filtransformering och variabelersättning i inställningarna för aktiviteterna. Alternativen för transformering och ersättning är:

• XML-transformering
• XML-variabelersättning
• JSON-variabelersättning

När aktiviteten körs utför den först XML-transformering, XML-variabelersättning och JSON-variabelersättning på konfigurations- och parameterfiler. Därefter anropas msdeploy.exe, som använder filen parameters.xml för att ersätta värden i filen web.config.

XML-transformering

XML-transformering stöder transformering av konfigurationsfilerna (*.config filer) genom att följa Web.config Transformation Syntax och baseras på miljön som webbpaketet ska distribueras till. Det här alternativet är användbart när du vill lägga till, ta bort eller ändra konfigurationer för olika miljöer. Transformering tillämpas för andra konfigurationsfiler, inklusive konfigurationsfiler för konsol- eller Windows-tjänstprogram (till exempel FabrikamService.exe.config).

Namngivningskonventioner för konfigurationstransformeringsfiler

XML-transformering körs på *.config filen för transformeringskonfigurationsfiler med namnet *.Release.config eller *.<stage>.config och körs i följande ordning:

1. *.Release.config (till exempel fabrikam. Release.config)
2. *.<stage>.config (till exempel fabrikam. Production.config)

Om ditt paket till exempel innehåller följande filer:

• Web.config
• Web.Debug.config
• Web.Release.config
• Web.Production.config

och ditt fasnamn är Produktion, transformeringen tillämpas Web.config med Web.Release.config följt av Web.Production.config.

EXEMPEL på XML-transformering

1. Skapa ett webbprogrampaket med nödvändiga konfigurations- och transformeringsfiler. Använd till exempel följande konfigurationsfiler:

   Konfigurationsfil

   <?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>
   

   Transformera fil

   <?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>
   

   I det här exemplet gör transformeringskonfigurationsfilen tre saker:

   • Den lägger till en ny databas anslutningssträng inuti elementetConnectionStrings.
   • Den ändrar värdet Webpages:Enabled för inuti elementet appSettings .
   • Det tar debug bort attributet från elementet compilation inuti elementet System.Web .

   Mer information finns i Web.config Transformation Syntax for Web Project Deployment Using Visual Studio

2. Skapa en versionspipeline med en fas med namnet Release.

3. Lägg till en Azure App Service Deploy-uppgift och ange (tick) xml-transformeringsalternativet .

   

4. Spara versionspipelinen och starta en ny version.

5. Web.config Öppna filen för att se transformeringarna från Web.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>
   

Anteckningar om XML-transformering

• Du kan använda den här tekniken för att skapa ett standardpaket och distribuera det till flera steg.

• XML-omvandlingen börjar gälla endast när konfigurationsfilen och transformeringsfilen finns i samma mapp i det angivna paketet.

• Som standard tillämpar MSBuild transformeringen eftersom den genererar webbpaketet om elementet <DependentUpon> redan finns i transformeringsfilen i *.csproj filen. I sådana fall misslyckas Azure App Service Deploy-uppgiften eftersom ingen ytterligare transformering tillämpas på Web.config filen. Därför rekommenderar vi att elementet <DependentUpon> tas bort från alla transformeringsfiler för att inaktivera konfiguration av byggtid när XML-transformering används.

• Ange egenskapen Skapa åtgärd för var och en av transformeringsfilerna (Web.config) till Innehåll så att filerna kopieras till rotmappen.

  ...
  <Content Include="Web.Debug.config">
     <DependentUpon>Web.config</DependentUpon>
  </Content>
  <Content Include="Web.Release.config">
     <DependentUpon>Web.config</DependentUpon>
  </Content>
  ...
  

XML-variabelersättning

Med den här funktionen kan du ändra konfigurationsinställningarna i konfigurationsfiler (*.config filer) i webbpaket och XML-parameterfiler (parameters.xml). På så sätt kan samma paket konfigureras baserat på den miljö som det ska distribueras till.

Variabelersättning börjar gälla endast för elementen applicationSettings, appSettings, connectionStringsoch configSections i konfigurationsfilerna. Om du vill ersätta värden utanför dessa element kan du använda en (parameters.xml) fil, men du måste använda en pipelineaktivitet från tredje part för att hantera variabelersättningen.

Exempel på XML-variabelersättning

Tänk till exempel på uppgiften att ändra följande värden i 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>

1. Skapa en versionspipeline med en fas med namnet Release.

2. Lägg till en Azure App Service Deploy-uppgift och ange (tick) alternativet XML-variabelersättning .

   

3. Definiera de värden som krävs i versionspipelinevariabler:

   Name	Värde	Säkra	Omfattning
   Standard Anslut ion	Datakälla=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf	Nej	Frisläpp
   AdminUserName	ProdAdminName	Nej	Frisläpp
   AdminPassword	[ditt lösenord]	Ja	Frisläpp
   invariantName	System.Data.SqlClientExtension	Nej	Frisläpp

4. Spara versionspipelinen och starta en ny version.

5. Web.config Öppna filen för att se variabelersättningarna.

   <?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>
   

Xml-variabelersättningsanteckningar

• Som standard har ASP.NET program ett standardparameteriserat anslutningsattribut. Dessa värden åsidosättas endast i parameters.xml filen i webbpaketet.

• Eftersom ersättning sker före distributionen kan användaren åsidosätta värdena i Web.config med hjälp av parameters.xml (inuti webbpaketet) eller en setparameters fil.

JSON-variabelersättning

Den här funktionen ersätter värden i JSON-konfigurationsfilerna. Den åsidosätter värdena i de angivna JSON-konfigurationsfilerna (till exempel appsettings.json) med värdena som matchar namnen på versionspipelinen och stegvariablerna.

Om du vill ersätta variabler i specifika JSON-filer anger du en ny radavgränsad lista över JSON-filer. Filnamn måste anges i förhållande till rotmappen. Om ditt paket till exempel har den här strukturen:

/WebPackage(.zip)
  /---- content
    /----- website
      /---- appsettings.json
      /---- web.config
      /---- [other folders] 
  /--- archive.xml
  /--- systeminfo.xml

och du vill ersätta värden i appsettings.json anger du den relativa sökvägen från rotmappen, till exempel content/website/appsettings.json. Du kan också använda jokerteckenmönster för att söka efter specifika JSON-filer. Returnerar till exempel **/appsettings.json den relativa sökvägen och namnet på filer med namnet appsettings.json.

Exempel på JSON-variabelersättning

Tänk till exempel på uppgiften att åsidosätta värden i den här JSON-filen:

{
  "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"
        }
      ]
    }
  }
}

Uppgiften är att åsidosätta värdena för Anslut ionString, DebugMode, den första av värdena Användare och NewWelcomeMessage på respektive plats i JSON-filhierarkin.

Klassisk

1. Skapa en versionspipeline med en fas med namnet Release.

2. Lägg till en Azure App Service Deploy-uppgift och ange en ny radavgränsad lista över JSON-filer för att ersätta variabelvärdena i textrutan JSON-variabelersättning . Filnamn måste vara relativa till rotmappen. Du kan använda jokertecken för att söka efter JSON-filer. Till exempel: **/*.json innebär ersättningsvärden i alla JSON-filer i paketet.

   

3. Definiera nödvändiga ersättningsvärden i versionspipeline- eller fasvariabler.

   Name	Värde	Säkra	Omfattning
   Data.DebugMode	inaktiverat	Nej	Frisläpp
   Data.Default Anslut ion.AnslutionString	Datakälla=(prodDB)\MSDB; AttachDbFilename=prod.mdf;	Nej	Frisläpp
   Data.DBAccess.Users.0	Admin-3	Ja	Frisläpp
   Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	Nej	Frisläpp

4. Spara versionspipelinen och starta en ny version.

5. Efter omvandlingen innehåller JSON följande:

   {
     "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"
           }
         ]
       }
     }
   }
   '''
   
   

YAML

Följande YAML-kodfragment visar JSON-variabelersättning.

variables:
  Data.DebugMode: disabled
  Data.DefaultConnection.ConnectionString: 'Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;'
  Data.DBAccess.Users.0: Admin-3
  Data.FeatureFlags.Preview.1.NewWelcomeMessage: AllAccounts

# Update appsettings.json via FileTransform task.
- task: FileTransform@1
  displayName: 'File transformation: appsettings.json'
  inputs:
    folderPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
    targetFiles: '**/appsettings.json'
    fileType: json
  
# Deploy web app
- task: AzureWebApp@1
  inputs:
    azureSubscription: <Name of the Azure subscription>
    appName: <Name of the Azure WebApp>
    package: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip

JSON-variabelersättningsanteckningar

• Om du vill ersätta värden i kapslade nivåer i filen sammanfogar du namnen med en punkt (.) i hierarkisk ordning.

• Ett JSON-objekt kan innehålla en matris vars värden kan refereras till av deras index. Om du till exempel vill ersätta det första värdet i matrisen Användare som visas ovan använder du variabelnamnet DBAccess.Users.0. Om du vill uppdatera värdet i NewWelcomeMessage använder du variabelnamnet FeatureFlags.Preview.1.NewWelcomeMessage. Men filtransformeringsaktiviteten har möjlighet att transformera hela matriser i JSON-filer. Du kan också använda DBAccess.Users = ["NewUser1","NewUser2","NewUser3"].

• Endast strängersättning stöds för JSON-variabelersättning.

• Ersättning stöds endast för UTF-8- och UTF-16 LE-kodade filer.

• Om filspecifikationen du anger inte matchar någon fil misslyckas uppgiften.

• Matchning av variabelnamn är skiftlägeskänsligt.

• Variabelersättning används endast för JSON-nycklar som är fördefinierade i objekthierarkin. Den skapar inte nya nycklar.

• Om ett variabelnamn innehåller punkter ("."), försöker transformeringen hitta objektet i hierarkin. Om variabelnamnet till exempel är first.second.thirdsöker transformeringsprocessen efter:

  "first" : {
    "second": {
      "third" : "value"
    }
  }
  

  samt "first.second.third" : "value".