FileTransform@2 - Tâche transformation de fichier v2

Article
11/21/2024

Utilisez cette tâche pour remplacer les jetons par des valeurs de variable dans des fichiers de configuration XML ou JSON.

Syntaxe

# 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.

# 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.
    #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config' # string. XML Transformation rules. Default: -transform **\*.Release.config -xml **\*.config.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

Entrées

folderPath - package ou dossier
string. Obligatoire. Valeur par défaut : $(System.DefaultWorkingDirectory)/**/*.zip.

Chemin d’accès du fichier au package ou à un dossier.

Les variables sont build et version. Les caractères génériques sont pris en charge.

Par exemple, $(System.DefaultWorkingDirectory)/**/*.zip. Pour les dossiers compressés, le contenu est extrait à l’emplacement TEMP, aux transformations exécutées et aux résultats compressés dans l’emplacement d’artefact d’origine.

enableXmlTransform - transformation XML
boolean. Valeur par défaut : true.

Les transformations de configuration sont exécutées avant la substitution de variable.

Les transformations XML sont prises en charge uniquement pour la plateforme Windows.

xmlTransformationRules - règles de transformation XML
string. Optionnel. Utilisez quand enableXmlTransform == true. Valeur par défaut : -transform **\*.Release.config -xml **\*.config.

Fournit une liste séparée par une ligne de règles de fichier de transformation à l’aide de la syntaxe : -transform <pathToTransformFile> -xml <pathToSourceConfigurationFile>. Le chemin d’accès au fichier de résultats est facultatif et, s’il n’est pas spécifié, le fichier de configuration source est remplacé par le fichier de résultats transformé.

xmlTransformationRules - règles de transformation XML
string. Valeur par défaut : -transform **\*.Release.config -xml **\*.config.

jsonTargetFiles - fichiers cibles JSON
string.

Fournit une liste de fichiers séparés par une nouvelle ligne pour remplacer les valeurs de variable. Les noms de fichiers doivent être fournis par rapport au dossier racine.

Par exemple, pour remplacer la valeur de ConnectionString dans l’exemple ci-dessous, vous devez définir une variable comme Data.DefaultConnection.ConnectionString dans le pipeline de build ou de mise en production (ou l’environnement du pipeline de mise en production).

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

La substitution de variable est exécutée après les transformations de configuration.

Remarque : Seules les variables personnalisées définies dans les pipelines de build/mise en production sont utilisées en substitution. Les variables de pipeline définies par défaut/système sont exclues. Si les mêmes variables sont définies dans le pipeline de mise en production et dans l’étape, les variables intermédiaires remplacent les variables de pipeline de mise en production.

xmlTargetFiles - fichiers cibles XML
string.

Fournit une liste de fichiers séparés par une nouvelle ligne pour remplacer les valeurs de variable. Les noms de fichiers doivent être fournis par rapport au dossier racine.

Pour XML, les variables définies dans les pipelines de build ou de mise en production sont mises en correspondance avec les entrées de key ou de name dans les appSettings, applicationSettingset connectionStrings sections de n’importe quel fichier de configuration et parameters.xml.

La substitution de variable est exécutée après les transformations de configuration.

Remarque : seules les variables personnalisées définies dans les pipelines de build/mise en production sont utilisées en substitution. Les variables de pipeline définies par défaut/système sont exclues. Si les mêmes variables sont définies dans le pipeline de mise en production et dans l’étape, les variables intermédiaires remplacent les variables de pipeline de mise en production.

Options de contrôle de tâche

Toutes les tâches ont des options de contrôle en plus de leurs entrées de tâche. Pour plus d’informations, consultez Options de contrôle et propriétés de tâche courantes.

Variables de sortie

Aucun.

Remarques

Nouveautés de la transformation de fichier version 2 :

Champs de tâche optimisés qui permettent aux utilisateurs d’activer toutes/toutes les fonctionnalités de transformation (XML), de substitution de variable (JSON et XML) dans une seule instance de tâche.
La tâche échoue quand l’une des transformations/substitution configurées n’est pas appliquée ou lorsque la tâche est no-op.

Utilisez cette tâche pour appliquer des transformations de fichiers et des substitutions de variables sur les fichiers de configuration et de paramètres. Pour plus d’informations sur le traitement des traductions, consultez référence de transformation de fichier et de substitution de variables.

Important

Cette tâche est destinée aux packages web et nécessite un fichier de package web. Il ne fonctionne pas sur les fichiers JSON autonomes.

Transformations de fichiers

À l’heure actuelle, les transformations de fichiers sont prises en charge uniquement pour les fichiers XML.
Pour appliquer une transformation XML aux fichiers de configuration (*.config), vous devez spécifier une liste de règles de fichier de transformation séparées par une nouvelle ligne à l’aide de la syntaxe :-t ransform <path to the transform file> -xml <path to the source file> -result <path to the result file>
Les transformations de fichiers sont utiles dans de nombreux scénarios, en particulier lorsque vous effectuez un déploiement sur un service d’application et que vous souhaitez ajouter, supprimer ou modifier des configurations pour différents environnements (tels que Dev, Test ou Prod) en suivant la syntaxe de transformation de Web.config standard.
Vous pouvez également utiliser cette fonctionnalité pour transformer d’autres fichiers, notamment les fichiers de configuration de l’application de service Console ou Windows (par exemple, FabrikamService.exe.config).
Les transformations de fichier de configuration sont exécutées avant les substitutions de variables.

Substitution de variable

Actuellement, seuls les formats de fichiers XML et JSON sont pris en charge pour la substitution de variable.
Les jetons définis dans les fichiers de configuration cible sont mis à jour, puis remplacés par des valeurs de variable.
Les substitutions de variables sont exécutées après les transformations de fichier de configuration.
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.

Note

Seules les variables personnalisées définies dans les pipelines de build et de mise en production sont utilisées en substitution. Les variables de pipeline système et par défaut sont exclues.

Voici la liste des préfixes actuellement exclus :

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

Si les mêmes variables sont définies dans le pipeline de mise en production et dans une phase, les variables définies par l’étape remplacent les variables définies par le pipeline.

Consultez également : transformation de fichier et référence de substitution de variable.

Exemples

Si vous avez besoin d’une transformation XML pour s’exécuter sur tous les fichiers de configuration nommés avec le modèle .Production.config, la règle de transformation doit être spécifiée comme suit :

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

Si vous avez un fichier de configuration nommé en fonction du nom de l’étape dans votre pipeline, vous pouvez utiliser :

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

Pour remplacer les variables JSON imbriquées ou hiérarchiques, spécifiez-les à l’aide d’expressions JSONPath. Par exemple, pour remplacer la valeur de ConnectionString dans l’exemple ci-dessous, vous devez définir une variable comme Data.DefaultConnection.ConnectionString dans le pipeline de build ou de mise en production (ou dans une phase dans le pipeline de mise en production).

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

Exigences

Exigence	Description
Types de pipelines	YAML, Build Classique, Version Classique
Exécutions sur	Agent, DeploymentGroup
demandes	Aucun
fonctionnalités de	Cette tâche ne répond à aucune demande de tâches ultérieures dans le travail.
restrictions de commande	Quelconque
variables settables	Quelconque
Version de l’agent	Toutes les versions de l’agent prises en charge.
Catégorie de tâche	Utilité

Voir aussi

transformation de fichier et référence de substitution de variables

Partager via