Referenz zu Dateitransformationen und zur Variablenersetzung

Artikel
04/05/2024

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

Einige Aufgaben, z. B. die Aufgabe Azure App Service-Bereitstellung der Version 3 und höher und der Aufgabe IIS Web App-Bereitstellung ermöglichen Benutzer*innen das Konfigurieren des Pakets basierend auf der angegebenen Umgebung. Diese Aufgaben verwenden msdeploy.exe, die das Überschreiben von Werten in der Datei web.config mit Werten aus der Datei parameters.xml unterstützt. Dateitransformationen und Variablenersetzungen sind jedoch nicht auf Web-App-Dateien beschränkt. Sie können diese Techniken mit allen XML- oder JSON-Dateien verwenden.

Hinweis

Dateitransformationen und das Ersetzen von Variablen werden auch von der separaten Dateitransformationsaufgabe zur Verwendung in Azure Pipelines unterstützt. Sie können die Dateitransformationsaufgabe verwenden, um Dateitransformationen und Variablenersetzungen auf beliebige Konfigurations- und Parameterdateien anzuwenden.

Die Konfigurationsersetzung wird im Abschnitt Optionen für Dateitransformation und Variablenersetzung der Einstellungen für die Aufgaben angegeben. Die Optionen für Transformationen und Ersetzungen sind:

XML-Transformation
XML-Variablenersetzung
JSON-Variablenersetzung

Wenn die Aufgabe ausgeführt wird, führt sie zunächst die XML-Transformation, die XML-Variablenersetzung und die JSON-Variablenersetzung für Konfigurations- und Parameterdateien aus. Als Nächstes wird msdeploy.exe aufgerufen, die die Datei parameters.xml verwendet, um Werte in der Datei web.config zu ersetzen.

XML-Transformation

Die XML-Transformation unterstützt das Transformieren der Konfigurationsdateien (*.config-Dateien) mit der Web.config-Transformationssyntax und basiert auf der Umgebung, in der das Webpaket bereitgestellt wird. Diese Option ist nützlich, wenn Sie Konfigurationen für verschiedene Umgebungen hinzufügen, entfernen oder ändern möchten. Die Transformation wird für andere Konfigurationsdateien angewandt, einschließlich Konfigurationsdateien für Konsolen- oder Windows-Dienstanwendungen (z. B. FabrikamService.exe.config).

Dateinamenskonventionen für Konfigurationstransformationen

Die XML-Transformation wird für die Datei *.config für Transformationskonfigurationsdateien mit dem Namen *.Release.config oder *.<stage>.config in der folgenden Reihenfolge ausgeführt:

*.Release.config (z. B. fabrikam.Release.config)
*.<stage>.config (z. B. fabrikam.Production.config)

Angenommen, das Paket enthält die folgenden Dateien:

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

und Ihr Stagingname ist Production, dann wird die Transformation für Web.config mit Web.Release.config gefolgt von Web.Production.config angewandt.

Beispiel für eine XML-Transformation

Erstellen Sie ein Webanwendungspaket mit den erforderlichen Konfigurations- und Transformationsdateien. Verwenden Sie sich beispielsweise die folgenden Konfigurationsdateien:

Konfigurationsdatei

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

Transformationsdatei

<?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 dieser Beispielkonfigurationsdatei für die Transformation werden drei Schritte ausgeführt:

Hinzufügen einer neuen Datenbankverbindungszeichenfolge innerhalb des ConnectionStrings-Elements
Ändern des Werts von Webpages:Enabled innerhalb des appSettings-Elements
Entfernen des debug-Attributs aus dem compilation-Element innerhalb des System.Web-Elements

Weitere Informationen finden Sie unter Syntax der Web.config-Transformation für die Bereitstellung von Webanwendungsprojekten mit Visual Studio.

Erstellen Sie eine Releasepipeline mit einer Stage namens Release.
Fügen Sie eine Aufgabe Azure App Service-Bereitstellung hinzu, und legen Sie die Option XML-Transformation fest (aktivieren).
Speichern Sie die Releasepipeline, und starten Sie ein neues Release.

Öffnen Sie die Datei Web.config, um die Transformationen von Web.Release.config anzuzeigen.

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

Hinweise zur XML-Transformation

Sie können dieses Verfahren verwenden, um ein Standardpaket zu erstellen und es in mehreren Stages bereitzustellen.
Die XML-Transformation wird nur wirksam, wenn sich die Konfigurationsdatei und die Transformationsdatei im selben Ordner innerhalb des angegebenen Pakets befinden.
Standardmäßig wendet MSBuild die Transformation an, während das Webpaket generiert wird, wenn das <DependentUpon>-Element bereits in der Transformationsdatei in der Datei *.csproj vorhanden ist. In solchen Fällen löst die Aufgabe Azure App Service-Bereitstellung einen Fehler aus, da keine weitere Transformation auf die Datei Web.config angewandt wird. Daher wird empfohlen, das <DependentUpon>-Element aus allen Transformationsdateien zu entfernen, um Konfigurationen während des Builds bei Verwendung der XML-Transformation zu deaktivieren.

Legen Sie die Buildaktion-Eigenschaft für jede der Transformationsdateien (Web.config) auf Inhalt fest, damit die Dateien in den Stammordner kopiert werden.

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

XML-Variablenersetzung

Mit diesem Feature können Sie Konfigurationseinstellungen in Konfigurationsdateien (*.config-Dateien) innerhalb von Webpaketen und XML-Parameterdateien (parameters.xml) ändern. Auf diese Weise kann dasselbe Paket basierend auf der Umgebung konfiguriert werden, in der es bereitgestellt wird.

Die Variablenersetzung wird nur auf die Elemente applicationSettings, appSettings, connectionStrings und configSections von Konfigurationsdateien angewandt. Wenn Sie Werte außerhalb dieser Elemente ersetzen möchten, können Sie eine Datei parameters.xml verwenden. Sie müssen jedoch eine Pipelineaufgabe von Drittanbietern für die Variablenersetzung verwenden.

Beispiel für die XML-Variablenersetzung

Betrachten Sie als Beispiel die Aufgabe, die folgenden Werte in Web.config zu ändern:

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

Erstellen Sie eine Releasepipeline mit einer Stage namens Release.
Fügen Sie eine Aufgabe Azure App Service-Bereitstellung hinzu, und legen Sie die Option XML-Variablenersetzung fest (aktivieren).

Definieren Sie die erforderlichen Werte in den Releasepipelinevariablen:

Name	Wert	Sicher	`Scope`
DefaultConnection	Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf	Nein	Freigabe
AdminUserName	ProdAdminName	Nein	Freigabe
AdminPassword	[Ihr Kennwort]	Ja	Freigabe
invariantName	System.Data.SqlClientExtension	Nein	Freigabe

Speichern Sie die Releasepipeline, und starten Sie ein neues Release.

Öffnen Sie die Datei Web.config, um die Variablenersetzungen anzuzeigen.

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

Hinweise zur XML-Variablenersetzung

Standardmäßig verfügen ASP.NET-Anwendungen über ein standardmäßig parametrisiertes connection-Attribute. Diese Werte werden nur in der Datei parameters.xml im Webpaket außer Kraft gesetzt.
Da die Ersetzung vor der Bereitstellung erfolgt, können Benutzer*innen die Werte in Web.config mit parameters.xml (innerhalb des Webpakets) oder einer Datei setparameters außer Kraft setzen.

JSON-Variablenersetzung

Dieses Feature ersetzt Werte in JSON-Konfigurationsdateien. Es überschreibt die Werte in den angegebenen JSON-Konfigurationsdateien (z. B. appsettings.json) mit den Werten, die den Namen der Releasepipeline und der Stagevariablen entsprechen.

Um Variablen in bestimmten JSON-Dateien zu ersetzen, stellen Sie eine durch Zeilenumbrüche getrennte Liste von JSON-Dateien bereit. Die Dateinamen müssen relativ zum Stammordner angegeben werden. Angenommen, Ihr Paket über folgende Struktur:

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

und Sie möchten Werte in appsettings.json ersetzen. In diesem Fall geben Sie den relativen Pfad zum Stammordner ein, z. B. content/website/appsettings.json. Alternativ können Sie Platzhaltermuster verwenden, um nach bestimmten JSON-Dateien zu suchen. **/appsettings.json gibt z. B. den relativen Pfad und den Namen der Dateien mit dem Namen appsettings.json zurück.

Beispiel für die JSON-Variablenersetzung

Betrachten Sie als Beispiel die Aufgabe zur Außerkraftsetzung von Werten in dieser JSON-Datei:

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

Die Aufgabe besteht darin, die Werte von ConnectionString und DebugMode, den ersten der Werte User und den Wert von NewWelcomeMessage an den entsprechenden Stellen in der JSON-Dateihierarchie außer Kraft zu setzen.

Klassisch
YAML

Erstellen Sie eine Releasepipeline mit einer Stage namens Release.
Fügen Sie eine Aufgabe Azure App Service-Bereitstellung hinzu, und geben Sie eine durch Zeilenumbrüche getrennte Liste von JSON-Dateien ein, um die Variablenwerte im Textfeld JSON-Variablenersetzung zu ersetzen. Die Dateinamen müssen relativ zum Stammordner sein. Sie können Platzhalter verwenden, um nach JSON-Dateien zu suchen. **/*.json bedeutet z. B., dass Werte in allen JSON-Dateien innerhalb des Pakets ersetzt werden.

Definieren Sie die erforderlichen Ersetzungswerte in Releasepipeline- oder Stagevariablen.

Name	Wert	Sicher	`Scope`
Data.DebugMode	deaktiviert	Nein	Freigabe
Data.DefaultConnection.ConnectionString	Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;	Nein	Freigabe
Data.DBAccess.Users.0	Admin-3	Ja	Freigabe
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	Nein	Freigabe

Speichern Sie die Releasepipeline, und starten Sie ein neues Release.

Nach der Transformation enthält der JSON-Code Folgendes:

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

Der folgende YAML-Codeschnipsel zeigt die JSON-Variablenersetzung.

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

Hinweise zur JSON-Variablenersetzung

Um Werte auf geschachtelten Ebenen der Datei außer Kraft zu setzen, verketten Sie die Namen mit einem Punkt (.) in hierarchischer Reihenfolge.
Ein JSON-Objekt kann ein Array enthalten, auf dessen Werte durch den Index verwiesen werden kann. Um beispielsweise den ersten Wert im oben gezeigten Array User zu ersetzen, verwenden Sie den Variablennamen DBAccess.Users.0. Um den Wert in NewWelcomeMessage zu aktualisieren, verwenden Sie den Variablennamen FeatureFlags.Preview.1.NewWelcomeMessage. Die Aufgabe Dateitransformation bietet jedoch die Möglichkeit, ganze Arrays in JSON-Dateien zu transformieren. Sie können auch DBAccess.Users = ["NewUser1","NewUser2","NewUser3"] verwenden.
Bei der JSON-Variablenersetzung werden nur Zeichenfolgenersetzungen unterstützt.
Die Ersetzung wird nur für Dateien mit UTF-8- und UTF-16-LE-Codierung unterstützt.
Wenn die eingegebene Dateispezifikation keiner Datei entspricht, löst die Aufgabe einen Fehler aus.
Beim Abgleich von Variablennamen wird die Groß-/Kleinschreibung beachtet.
Die Variablenersetzung wird nur auf die JSON-Schlüssel angewandt, die in der Objekthierarchie vordefiniert sind. Es werden keine neuen Schlüssel erstellt.
Wenn ein Variablenname Punkte („.“) enthält, versucht die Transformation, das Element innerhalb der Hierarchie zu finden. Wenn der Variablenname beispielsweise first.second.third lautet, sucht der Transformationsprozess nach:
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
sowie nach "first.second.third" : "value".