FileTransform@2 – Dateitransformation v2-Aufgabe

Verwenden Sie diese Aufgabe, um Token durch variable Werte in XML- oder JSON-Konfigurationsdateien zu ersetzen.

Syntax

# File transform v2
# Replace tokens with variable values in XML or JSON configuration files.
- task: FileTransform@2
  inputs:
    folderPath: '$(System.DefaultWorkingDirectory)/**/*.zip' # string. Required. Package or folder. Default: $(System.DefaultWorkingDirectory)/**/*.zip.
    #enableXmlTransform: true # boolean. XML transformation. Default: true.
    #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config' # string. Optional. Use when enableXmlTransform == true. XML Transformation rules. Default: -transform **\*.Release.config -xml **\*.config.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

Eingänge

folderPath - Paket- oder Ordner-
string. Erforderlich. Standardwert: $(System.DefaultWorkingDirectory)/**/*.zip.

Dateipfad zum Paket oder ordner.

Variablen sind Build und Release. Wildcards werden unterstützt.

Beispiel: $(System.DefaultWorkingDirectory)/**/*.zip. Bei gezippten Ordnern werden die Inhalte an den TEMP-Speicherort, die ausgeführten Transformationen und die Ergebnisse extrahiert, die am ursprünglichen Artefaktspeicherort gezippt wurden.

enableXmlTransform - XML-Transformation
boolean. Standardwert: true.

Konfigurationstransformationen werden vor der Variablenersetzung ausgeführt.

XML-Transformationen werden nur für windows-Plattform unterstützt.

xmlTransformationRules - XML-Transformationsregeln
string. Wahlfrei. Wird verwendet, wenn enableXmlTransform == true. Standardwert: -transform **\*.Release.config -xml **\*.config.

Stellt eine neulinetrennte Liste der Transformationsdateiregeln mithilfe der Syntax bereit: -transform <pathToTransformFile> -xml <pathToSourceConfigurationFile>. Der Ergebnisdateipfad ist optional, und wenn nicht angegeben, wird die Quellkonfigurationsdatei durch die transformierte Ergebnisdatei ersetzt.

jsonTargetFiles - JSON-Zieldateien
string.

Stellt eine durch neue Zeile getrennte Liste von Dateien bereit, um die Variablenwerte zu ersetzen. Dateinamen werden relativ zum Stammordner bereitgestellt.

Um beispielsweise den Wert von ConnectionString im folgenden Beispiel zu ersetzen, müssen Sie eine Variable als Data.DefaultConnection.ConnectionString in der Build- oder Releasepipeline (oder in der Umgebung der Releasepipeline) definieren.

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

Die Variable Substitution wird nach Konfigurationstransformationen ausgeführt.

Hinweis: Es werden nur benutzerdefinierte Variablen verwendet, die in Build-/Releasepipelinen definiert sind. Standard-/systemdefinierte Pipelinevariablen werden ausgeschlossen. Wenn die gleichen Variablen in der Releasepipeline und in der Phase definiert sind, werden die Versionspipelinevariablen durch die Phasenvariablen ersetzt.

xmlTargetFiles - XML-Zieldateien
string.

Stellt eine durch neue Zeile getrennte Liste von Dateien bereit, um die Variablenwerte zu ersetzen. Dateinamen werden relativ zum Stammordner bereitgestellt.

Für XML werden variablen, die in den Build- oder Releasepipelinen definiert sind, mit den einträgen key oder name in den Abschnitten appSettings, applicationSettingsund connectionStrings jeder Konfigurationsdatei und parameters.xmlabgeglichen.

Die Variable Substitution wird nach Konfigurationstransformationen ausgeführt.

Hinweis: Es werden nur benutzerdefinierte Variablen verwendet, die in Build-/Release-Pipelines definiert sind. Standard-/systemdefinierte Pipelinevariablen werden ausgeschlossen. Wenn die gleichen Variablen in der Releasepipeline und in der Phase definiert sind, werden die Versionspipelinevariablen durch die Phasenvariablen ersetzt.

Aufgabensteuerungsoptionen

Alle Aufgaben verfügen zusätzlich zu ihren Aufgabeneingaben über Steuerungsoptionen. Weitere Informationen finden Sie unter Steuerelementoptionen und allgemeinen Aufgabeneigenschaften.

Ausgabevariablen

Nichts.

Bemerkungen

Neuerungen in Dateitransformation, Version 2:

• Optimierte Aufgabenfelder, mit denen Benutzer beliebige/alle Transformationsfunktionen (XML), Variablenersetzung (JSON und XML) in einer einzelnen Aufgabeninstanz aktivieren können.
• Die Aufgabe schlägt fehl, wenn eine der konfigurierten Transformationen/Ersetzungen NICHT angewendet wird oder wenn die Aufgabe no-opist.

Verwenden Sie diese Aufgabe, um Dateitransformationen und Variablenersetzungen auf Konfigurations- und Parameterdateien anzuwenden. Ausführliche Informationen zur Verarbeitung von Übersetzungen finden Sie unter Dateitransformationen und Variablenersetzungsreferenz.

Wichtig

Diese Aufgabe ist für Webpakete vorgesehen und erfordert eine Webpaketdatei. Es funktioniert nicht für eigenständige JSON-Dateien.

Dateitransformationen

• Derzeit werden Dateitransformationen nur für XML-Dateien unterstützt.
• Zum Anwenden einer XML-Transformation auf Konfigurationsdateien (*.config) müssen Sie eine durch neue Zeile getrennte Liste von Transformationsdateiregeln mithilfe der Syntax angeben:-t ransform <path to the transform file> -xml <path to the source file> -result <path to the result file>
• Dateitransformationen sind in vielen Szenarien nützlich, insbesondere wenn Sie einen App-Dienst bereitstellen und Konfigurationen für verschiedene Umgebungen (z. B. Dev, Test oder Prod) hinzufügen, entfernen oder ändern möchten, indem Sie den Standard Web.config Transformationssyntaxfolgen.
• Sie können diese Funktionalität auch verwenden, um andere Dateien zu transformieren, einschließlich Konfigurationsdateien für Konsolen- oder Windows-Dienstanwendungen (z. B. FabrikamService.exe.config).
• Konfigurationsdateitransformationen werden vor Variablenersetzungen ausgeführt.

Variablenersetzung

• Derzeit werden nur XML- und JSON-Dateiformate zur Variablenersetzung unterstützt.
• Token, die in den Zielkonfigurationsdateien definiert sind, werden aktualisiert und dann durch Variablenwerte ersetzt.
• Variablenersetzungen werden nach Konfigurationsdateitransformationen ausgeführt.
• Die Variablenersetzung wird nur für die JSON-Schlüssel angewendet, die in der Objekthierarchie vordefinierte sind. Es werden keine neuen Schlüssel erstellt.

Anmerkung

Es werden nur benutzerdefinierte Variablen verwendet, die in Build- und Releasepipelinen definiert sind. Standard- und Systempipelinevariablen werden ausgeschlossen.

Hier ist eine Liste der derzeit ausgeschlossenen Präfixe:

• agent.
• azure_http_user_agent
• build.
• common.
• release.
• system.
• tf_

Wenn die gleichen Variablen sowohl in der Releasepipeline als auch in einer Phase definiert sind, werden die durch die Phase definierten Variablen die durch die Pipeline definierten Variablen ersetzt.

Siehe auch: Dateitransformationen und Variablenersetzungsreferenz.

Beispiele

Wenn Sie eine XML-Transformation für alle Konfigurationsdateien benötigen, die mit mustern .Production.configbenannt sind, sollte die Transformationsregel folgendermaßen angegeben werden:

-transform **\*.Production.config -xml **\*.config

Wenn Sie über eine Konfigurationsdatei verfügen, die basierend auf dem Phasennamen in Ihrer Pipeline benannt ist, können Sie Folgendes verwenden:

-transform **\*.$(Release.EnvironmentName).config -xml **\*.config

Um JSON-Variablen zu ersetzen, die geschachtelt oder hierarchisch sind, geben Sie sie mithilfe von JSONPath-Ausdrücken an. Um beispielsweise den Wert von ConnectionString- im folgenden Beispiel zu ersetzen, müssen Sie eine Variable als Data.DefaultConnection.ConnectionString in der Build- oder Releasepipeline (oder in einer Phase innerhalb der Releasepipeline) definieren.

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

Anforderungen

Anforderung	Beschreibung
Pipelinetypen	YAML, Classic Build, Classic Release
Läuft auf	Agent, DeploymentGroup
Anforderungen	Nichts
Funktionen	Dieser Vorgang erfüllt keine Anforderungen für nachfolgende Vorgänge im Auftrag.
Befehlseinschränkungen	Jegliche
Settable-Variablen	Jegliche
Agentversion	Alle unterstützten Agentversionen.
Vorgangskategorie	Nützlichkeit

Siehe auch

• Dateitransformationen und Variablenersetzungsreferenz