Naslaginformatie over bestandstransformaties en variabelevervanging

Artikel
04/04/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Bij sommige taken, zoals de Azure-app Service Deploy-taak versie 3 en hoger en de TAAK IIS Web App Deploy, kunnen gebruikers het pakket configureren op basis van de opgegeven omgeving. Deze taken gebruiken msdeploy.exe, die ondersteuning biedt voor het overschrijven van waarden in het web.config-bestand met waarden uit het parameters.xml-bestand . Bestandstransformaties en variabele vervanging zijn echter niet beperkt tot web-app-bestanden. U kunt deze technieken gebruiken met xml- of JSON-bestanden.

Notitie

Bestandstransformaties en het vervangen van variabelen worden ook ondersteund door de afzonderlijke taak Bestandstransformatie voor gebruik in Azure Pipelines. U kunt de taak Bestandstransformatie gebruiken om bestandstransformaties en variabele vervangingen toe te passen op configuratie- en parameterbestanden.

Configuratievervanging wordt opgegeven in de sectie Opties voor bestandstransformatie en variabele vervanging van de instellingen voor de taken. De transformatie- en vervangingsopties zijn:

XML-transformatie
VERVANGING van XML-variabele
Vervanging van JSON-variabele

Wanneer de taak wordt uitgevoerd, wordt eerst XML-transformatie, vervanging van XML-variabelen en JSON-variabelen uitgevoerd op configuratie- en parameterbestanden. Vervolgens wordt msdeploy.exe aangeroepen, waarbij het parameters.xml-bestand wordt gebruikt om waarden in het web.config-bestand te vervangen.

XML-transformatie

XML-transformatie ondersteunt het transformeren van de configuratiebestanden (*.configbestanden) door de syntaxis van web.config-transformatie te volgen en is gebaseerd op de omgeving waarin het webpakket wordt geïmplementeerd. Deze optie is handig als u configuraties voor verschillende omgevingen wilt toevoegen, verwijderen of wijzigen. Transformatie wordt toegepast op andere configuratiebestanden, waaronder configuratiebestanden voor console- of Windows-servicetoepassingen (bijvoorbeeld FabrikamService.exe.config).

Naamconventies voor configuratietransformatiebestand

XML-transformatie wordt uitgevoerd op het *.config bestand voor transformatieconfiguratiebestanden met de naam *.Release.config of *.<stage>.config en wordt uitgevoerd in de volgende volgorde:

*.Release.config (bijvoorbeeld fabrikam. Release.config)
*.<stage>.config (bijvoorbeeld fabrikam. Production.config)

Als uw pakket bijvoorbeeld de volgende bestanden bevat:

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

en uw fasenaam is Productie, de transformatie wordt toegepast Web.config , gevolgd Web.Release.config door Web.Production.config.

Voorbeeld van XML-transformatie

Maak een webtoepassingspakket met de benodigde configuratie en transformeerbestanden. Gebruik bijvoorbeeld de volgende configuratiebestanden:

Configuratiebestand

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

Bestand transformeren

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

In dit voorbeeld wordt het configuratiebestand voor transformatie drie dingen uitgevoerd:

Er wordt een nieuwe database toegevoegd verbindingsreeks in het ConnectionStrings element.
De waarde van Webpages:Enabled het appSettings element wordt gewijzigd.
debug Het kenmerk wordt verwijderd uit het compilation element in het element in het System.Web element.

Zie De syntaxis van de web.config-transformatie voor webprojectimplementatie met Visual Studio voor meer informatie

Maak een release-pijplijn met een fase met de naam Release.
Voeg een Azure-app Service Deploy-taak toe en stel de XML-transformatieoptie (tick) in.
Sla de release-pijplijn op en start een nieuwe release.

Open het Web.config bestand om de transformaties van 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>

XML-transformatienotities

U kunt deze techniek gebruiken om een standaardpakket te maken en dit in meerdere fasen te implementeren.
XML-transformatie wordt alleen van kracht wanneer het configuratiebestand en transformatiebestand zich in dezelfde map in het opgegeven pakket bevinden.
MSBuild past standaard de transformatie toe terwijl het webpakket wordt gegenereerd als het <DependentUpon> element al aanwezig is in het transformatiebestand in het *.csproj bestand. In dergelijke gevallen mislukt de Azure-app Service Deploy-taak omdat er geen verdere transformatie wordt toegepast op het Web.config bestand. Daarom wordt het aanbevolen dat het <DependentUpon> element wordt verwijderd uit alle transformatiebestanden om een build-timeconfiguratie uit te schakelen bij het gebruik van XML-transformatie.

Stel de eigenschap Build Action voor elk van de transformatiebestanden (Web.config) in op Inhoud , zodat de bestanden naar de hoofdmap worden gekopieerd.

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

VERVANGING van XML-variabele

Met deze functie kunt u configuratie-instellingen wijzigen in configuratiebestanden (*.config bestanden) in webpakketten en XML-parametersbestanden (parameters.xml). Op deze manier kan hetzelfde pakket worden geconfigureerd op basis van de omgeving waarnaar het wordt geïmplementeerd.

Variabele vervanging wordt alleen van kracht op de applicationSettings, appSettings- connectionStringsen configSections elementen van configuratiebestanden. Als u waarden buiten deze elementen wilt vervangen, kunt u een (parameters.xml)-bestand gebruiken, maar u moet een pijplijntaak van derden gebruiken om de vervanging van de variabele af te handelen.

Voorbeeld van vervanging van XML-variabele

Houd bijvoorbeeld rekening met de taak van het wijzigen van de volgende waarden in 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>

Maak een release-pijplijn met een fase met de naam Release.
Voeg een Azure-app Service Deploy-taak toe en stel de optie voor het vervangen van de XML-variabele in (tick).

Definieer de vereiste waarden in releasepijplijnvariabelen:

Naam	Weergegeven als	Beveiligen	Bereik
Standaard Verbinding maken ion	Gegevensbron=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf	Nee	Vrijgeven
AdminUserName	Prod Beheer Naam	Nee	Vrijgeven
AdminPassword	[uw wachtwoord]	Ja	Vrijgeven
invariantName	System.Data.SqlClientExtension	Nee	Vrijgeven

Sla de release-pijplijn op en start een nieuwe release.

Open het Web.config bestand om de variabelen te vervangen.

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

Opmerkingen bij vervanging van XML-variabelen

Standaard hebben ASP.NET toepassingen een standaard geparameteriseerd verbindingskenmerk. Deze waarden worden alleen overschreven in het parameters.xml bestand in het webpakket.
Omdat vervanging plaatsvindt vóór de implementatie, kan de gebruiker de waarden Web.config in het gebruik parameters.xml (binnen het webpakket) of een setparameters bestand overschrijven.

Vervanging van JSON-variabele

Deze functie vervangt waarden in de JSON-configuratiebestanden. Hiermee worden de waarden in de opgegeven JSON-configuratiebestanden (bijvoorbeeld appsettings.json) overschreven met de waarden die overeenkomen met de namen van release-pijplijn- en fasevariabelen.

Als u variabelen in specifieke JSON-bestanden wilt vervangen, geeft u een door nieuwe regels gescheiden lijst met JSON-bestanden op. Bestandsnamen moeten worden opgegeven ten opzichte van de hoofdmap. Als uw pakket bijvoorbeeld deze structuur heeft:

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

en u wilt waarden in appsettings.json vervangen, voert u het relatieve pad uit de hoofdmap in, bijvoorbeeld content/website/appsettings.json. U kunt ook jokertekenpatronen gebruiken om te zoeken naar specifieke JSON-bestanden. Retourneert bijvoorbeeld **/appsettings.json het relatieve pad en de naam van bestanden met de naam appsettings.json.

Voorbeeld van vervanging van JSON-variabele

Denk bijvoorbeeld aan de taak voor het overschrijven van waarden in dit JSON-bestand:

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

De taak is het overschrijven van de waarden van Verbinding maken ionString, DebugMode, de eerste van de gebruikerswaarden en NewWelcomeMessage op de respectieve plaatsen in de JSON-bestandshiërarchie.

Klassiek
YAML

Maak een release-pijplijn met een fase met de naam Release.
Voeg een Azure-app Service Deploy-taak toe en voer een door nieuwe regels gescheiden lijst met JSON-bestanden in om de variabele waarden in het tekstvak voor vervanging van JSON-variabelen te vervangen. Bestandsnamen moeten relatief zijn ten opzichte van de hoofdmap. U kunt jokertekens gebruiken om te zoeken naar JSON-bestanden. Bijvoorbeeld: **/*.json vervangt waarden in alle JSON-bestanden in het pakket.

Definieer de vereiste vervangingswaarden in releasepijplijn- of fasevariabelen.

Naam	Weergegeven als	Beveiligen	Bereik
Data.DebugMode	disabled	Nee	Vrijgeven
Data.Default Verbinding maken ion.Verbinding makenionString	Gegevensbron=(prodDB)\MSDB; AttachDbFilename=prod.mdf;	Nee	Vrijgeven
Data.DBAccess.Users.0	Beheer-3	Ja	Vrijgeven
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	Nee	Vrijgeven

Sla de release-pijplijn op en start een nieuwe release.

Na de transformatie bevat de JSON het volgende:

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

Na het YAML-fragment ziet u de vervanging van JSON-variabelen.

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

Opmerkingen bij vervanging van JSON-variabelen

Als u waarden in geneste niveaus van het bestand wilt vervangen, voegt u de namen samen met een punt (.) in hiërarchische volgorde.
Een JSON-object kan een matrix bevatten waarvan naar waarden kan worden verwezen door hun index. Als u bijvoorbeeld de eerste waarde in de hierboven weergegeven matrix Gebruikers wilt vervangen, gebruikt u de naam DBAccess.Users.0van de variabele. Als u de waarde in NewWelcomeMessage wilt bijwerken, gebruikt u de naam FeatureFlags.Preview.1.NewWelcomeMessagevan de variabele. De bestandstransformatietaak heeft echter de mogelijkheid om hele matrices in JSON-bestanden te transformeren. U kunt ook .DBAccess.Users = ["NewUser1","NewUser2","NewUser3"]
Alleen tekenreeksvervanging wordt ondersteund voor vervanging van JSON-variabelen.
Vervanging wordt alleen ondersteund voor UTF-8- en UTF-16 LE-gecodeerde bestanden.
Als de bestandsspecificatie die u invoert niet overeenkomt met een bestand, mislukt de taak.
Variabelenaamkoppeling is hoofdlettergevoelig.
Variabelevervanging wordt alleen toegepast op de vooraf gedefinieerde JSON-sleutels in de objecthiërarchie. Er worden geen nieuwe sleutels gemaakt.
Als een variabelenaam puntjes (.) bevat, probeert de transformatie het item in de hiërarchie te vinden. Als de naam van de variabele bijvoorbeeld is first.second.third, zoekt het transformatieproces naar:
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
en "first.second.third" : "value".

Delen via