Utiliser des variables dans les pipelines de mise en production classique
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
L'emploi de variables dans les pipelines de mise en production classique constitue un moyen pratique d’échanger et de transporter des données dans votre pipeline. Chaque variable est stockée en tant que chaîne et sa valeur peut changer d'une exécution de pipeline à l'autre.
Contrairement aux paramètres d'exécution, qui sont disponibles uniquement au moment de l’analyse des modèles, les variables dans les pipelines de mise en production classique sont accessibles tout au long du processus de déploiement.
Lorsque vous configurez des tâches destinées au déploiement de votre application à chaque phase de votre pipeline de mise en production classique, les variables sont capables de vous aider de la manière suivante :
Pour simplifier la personnalisation : définissez une fois un pipeline de déploiement générique, puis adaptez-le facilement aux différentes phases. Par exemple, utilisez une variable représentant une chaîne de connexion pour le déploiement web, et ajustez-en la valeur selon les besoins de chaque phase. C'est ce que l'on appelle des variables personnalisées.
Pour tirer parti des informations contextuelles : accédez aux détails du contexte de mise en production, comme une phase, un artefact ou l’agent qui exécute le déploiement. Par exemple, vos scripts peuvent avoir besoin de l’emplacement de la build pour son téléchargement, ou du répertoire de travail de l’agent pour créer des fichiers temporaires. C'est ce que l'on appelle des variables par défaut.
Remarque
Pour les pipelines YAML, consultez Variables définies par l’utilisateur et Variables prédéfinies pour plus d’informations.
Les variables par défaut
Les variables par défaut fournissent des informations essentielles sur le contexte d’exécution de vos tâches et scripts en cours d’exécution. Ces variables vous permettent d’accéder aux détails concernant le système, la mise en production, la phase ou l’agent correspondant à l'exécution en cours.
À l’exception de System.Debug, les variables par défaut sont en lecture seule, leurs valeurs étant définies automatiquement par le système.
Certaines des principales variables sont décrites dans les tableaux ci-dessous. Pour afficher la liste complète, consultez Afficher les valeurs actuelles de toutes les variables.
Variables système
| Nom de la variable | Description |
|---|---|
| System.TeamFoundationServerUri | URL de la connexion de service dans Azure Pipelines. Utilisez-la à partir de vos scripts ou tâches pour appeler les API REST Azure Pipelines. Exemple : https://fabrikam.vsrm.visualstudio.com/ |
| System.TeamFoundationCollectionUri | URL de la collection Team Foundation ou d’Azure Pipelines. Utilisez-la à partir de vos scripts ou tâches pour appeler les API REST sur d’autres services comme Build et Gestion de version. Exemple : https://dev.azure.com/fabrikam/ |
| System.CollectionId | ID de la collection de cette build ou cette mise en production. Exemple : 6c6f3423-1c84-4625-995a-f7f143a1e43d |
| System.DefinitionId | ID du pipeline de mise en production de la mise en production actuelle. Exemple : 1 |
| System.TeamProject | Nom du projet de cette build ou cette mise en production. Exemple : Fabrikam |
| System.TeamProjectId | ID du projet de cette build ou cette mise en production. Exemple : 79f5c12e-3337-4151-be41-a268d2c73344 |
| System.ArtifactsDirectory | Répertoire dans lequel les artefacts sont téléchargés lors du déploiement d’une mise en production. Le répertoire est effacé avant chaque déploiement s’il nécessite le téléchargement d’artefacts sur l’agent. Identique à Agent.ReleaseDirectory et System.DefaultWorkingDirectory. Exemple : C:\agent\_work\r1\a |
| System.DefaultWorkingDirectory | Répertoire dans lequel les artefacts sont téléchargés lors du déploiement d’une mise en production. Le répertoire est effacé avant chaque déploiement s’il nécessite le téléchargement d’artefacts sur l’agent. Identique à Agent.ReleaseDirectory et System.ArtifactsDirectory. Exemple : C:\agent\_work\r1\a |
| System.WorkFolder | Répertoire de travail de cet agent, où des sous-dossiers sont créés pour chaque build ou mise en production. Identique à Agent.RootDirectory et Agent.WorkFolder. Exemple : C:\agent\_work |
| System.Debug | Il s’agit de la seule variable système pouvant être définie par les utilisateurs. Définissez cette valeur sur true pour exécuter la mise en production en mode débogage à des fins de recherche des erreurs. Exemple : true |
Variables de mise en production
| Nom de la variable | Description |
|---|---|
| Release.AttemptNumber | Nombre de fois où cette mise en production est déployée dans cette phase. Exemple : 1 |
| Release.DefinitionEnvironmentId | ID de la phase dans le pipeline de mise en production correspondant. Exemple : 1 |
| Release.DefinitionId | ID du pipeline de mise en production de la mise en production actuelle. Exemple : 1 |
| Release.DefinitionName | Nom du pipeline de mise en production de la mise en production actuelle. Exemple : fabrikam-cd |
| Release.Deployment.RequestedFor | Nom d’affichage de l’identité qui a déclenché (démarré) le déploiement en cours. Exemple : Mateo Escobedo |
| Release.Deployment.RequestedForEmail | Adresse e-mail de l’identité qui a déclenché (démarré) le déploiement en cours. Exemple : mateo@fabrikam.com |
| Release.Deployment.RequestedForId | ID de l’identité qui a déclenché (démarré) le déploiement en cours. Exemple : 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.DeploymentID | ID du déploiement. Unique par travail. Exemple : 254 |
| Release.DeployPhaseID | ID de la phase où le déploiement est en cours d’exécution. Exemple : 127 |
| Release.EnvironmentId | L’ID de l’instance de phase dans une mise en production dans laquelle le déploiement est en cours. Exemple : 276 |
| Release.EnvironmentName | Nom de la phase du déploiement en cours. Exemple : Dev |
| Release.EnvironmentUri | URI de l’instance de phase dans une mise en production dans laquelle le déploiement est en cours. Exemple : vstfs://ReleaseManagement/Environment/276 |
| Release.Environments.{stage-name}.status | État du déploiement de la phase. Exemple : InProgress |
| Release.PrimaryArtifactSourceAlias | Alias de la source d’artefact principal. Exemple : fabrikam\_web |
| Release.Reason | Motif du déploiement. Les valeurs prises en charge sont les suivantes :ContinuousIntegration : la mise en production a démarré dans le déploiement continu une fois la build terminée.Manual : la mise en production a été démarrée manuellement.None : le motif du déploiement n’est pas spécifié.Schedule : la mise en production a démarré à partir d’une planification. |
| Release.ReleaseDescription | Description textuelle fournie au moment de la mise en production. Exemple : Critical security patch |
| Release.ReleaseId | Identificateur de l’enregistrement de mise en production actuel. Exemple : 118 |
| Release.ReleaseName | Nom de la mise en production actuelle. Exemple : Release-47 |
| Release.ReleaseUri | URI de la mise en production actuelle. Exemple : vstfs://ReleaseManagement/Release/118 |
| Release.ReleaseWebURL | URL de cette mise en production. Exemple : https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary |
| Release.RequestedFor | Nom d’affichage de l’identité ayant déclenché la mise en production. Exemple : Mateo Escobedo |
| Release.RequestedForEmail | Adresse e-mail de l’identité ayant déclenché la mise en production. Exemple : mateo@fabrikam.com |
| Release.RequestedForId | ID de l’identité ayant déclenché la mise en production. Exemple : 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.SkipArtifactsDownload | Valeur booléenne qui indique si le téléchargement des artefacts sur l’agent doit être ignoré ou non. Exemple : FALSE |
| Release.TriggeringArtifact.Alias | Alias de l’artefact qui a déclenché la mise en production. Il est vide quand la mise en production a été planifiée ou déclenchée manuellement. Exemple : fabrikam\_app |
Variables de la phase de mise en production
| Nom de la variable | Description |
|---|---|
| Release.Environments.{stage name}.Status | État de déploiement de cette mise en production dans une phase spécifiée. Exemple : NotStarted |
Variables de l’agent
| Nom de la variable | Description |
|---|---|
| Agent.Name | Nom de l’agent inscrit auprès du pool d’agents. Il peut être différent du nom de l’ordinateur. Exemple : fabrikam-agent |
| Agent.MachineName | Nom de l’ordinateur sur lequel l’agent est configuré. Exemple : fabrikam-agent |
| Agent.Version | Version du logiciel de l’agent. Exemple : 2.109.1 |
| Agent.JobName | Nom du travail en cours d’exécution, comme Release ou Build. Exemple : Release |
| Agent.HomeDirectory | Dossier dans lequel l’agent est installé. Ce dossier contient le code et les ressources de l’agent. Exemple : C:\agent |
| Agent.ReleaseDirectory | Répertoire dans lequel les artefacts sont téléchargés lors du déploiement d’une mise en production. Le répertoire est effacé avant chaque déploiement s’il nécessite le téléchargement d’artefacts sur l’agent. Identique à System.ArtifactsDirectory et System.DefaultWorkingDirectory. Exemple : C:\agent\_work\r1\a |
| Agent.RootDirectory | Répertoire de travail de cet agent, où des sous-dossiers sont créés pour chaque build ou mise en production. Identique à Agent.WorkFolder et System.WorkFolder. Exemple : C:\agent\_work |
| Agent.WorkFolder | Répertoire de travail de cet agent, où des sous-dossiers sont créés pour chaque build ou mise en production. Identique à Agent.RootDirectory et System.WorkFolder. Exemple : C:\agent\_work |
| Agent.DeploymentGroupId | ID du groupe de déploiement avec lequel l’agent est inscrit. Disponible uniquement dans les travaux de groupe de déploiement. Exemple : 1 |
Variables des artefacts de mise en production
Pour chaque artefact référencé dans une mise en production, vous pouvez utiliser les variables d’artefact suivantes. Notez que toutes les variables ne s’appliquent pas à chaque type d’artefact. Le tableau ci-dessous répertorie les variables d’artefact par défaut et fournit des exemples de leurs valeurs en fonction du type d’artefact. Un exemple vide indique que la variable n’est pas applicable à ce type d’artefact.
Remplacez l’espace réservé {alias} par la valeur que vous avez spécifiée pour l’alias de la source d’artefact ou par la valeur par défaut générée pour le pipeline de mise en production.
| Nom de la variable | Description |
|---|---|
| Release.Artifacts.{alias}.DefinitionId | Identificateur du pipeline ou du référentiel de build. Exemples : Azure Pipelines : 1GitHub : fabrikam/asp |
| Release.Artifacts.{alias}.DefinitionName | Nom du pipeline ou du référentiel de build. Exemples : Azure Pipelines : fabrikam-ciTFVC : $/fabrikamGit : fabrikamGitHub : fabrikam/asp (main) |
| Release.Artifacts.{alias}.BuildNumber | Numéro de build ou identificateur de commit. Exemples : Azure Pipelines : 20170112.1Jenkins : 20170112.1TFVC : Changeset 3Git : 38629c964GitHub : 38629c964 |
| Release.Artifacts.{alias}.BuildId | Identificateur de build. Exemples : Azure Pipelines : 130Jenkins : 130GitHub : 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts.{alias}.BuildURI | URL de la build. Exemples : Azure Pipelines : vstfs://build-release/Build/130GitHub : https://github.com/fabrikam/asp |
| Release.Artifacts.{alias}.SourceBranch | Chemin d’accès complet et nom de la branche à partir de laquelle la source a été générée. Exemples : Azure Pipelines : refs/heads/main |
| Release.Artifacts.{alias}.SourceBranchName | Nom uniquement de la branche à partir de laquelle la source a été générée. Exemples : Azure Pipelines : main |
| Release.Artifacts.{alias}.SourceVersion | Commit qui a été généré. Exemples : Azure Pipelines : bc0044458ba1d9298cdc649cb5dcf013180706f7 |
| Release.Artifacts.{alias}.Repository.Provider | Type de référentiel à partir duquel la source a été générée. Exemples : Azure Pipelines : Git |
| Release.Artifacts.{alias}.RequestedForID | Identificateur du compte qui a déclenché la build. Exemples : Azure Pipelines : 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.Artifacts.{alias}.RequestedFor | Nom du compte qui a demandé la build. Exemples : Azure Pipelines : Mateo Escobedo |
| Release.Artifacts.{alias}.Type | Type de la source d’artefact, comme Build. Exemples : Azure Pipelines : BuildJenkins : JenkinsTFVC : TFVCGit : GitGitHub : GitHub |
| Release.Artifacts.{alias}.PullRequest.TargetBranch | Chemin complet et nom de la branche cible d’une demande de tirage. Cette variable est initialisée uniquement si la mise en production est déclenchée via un flux de demande de tirage. Exemples : Azure Pipelines : refs/heads/main |
| Release.Artifacts.{alias}.PullRequest.TargetBranchName | Nom uniquement de la branche cible d’une demande de tirage. Cette variable est initialisée uniquement si la mise en production est déclenchée via un flux de demande de tirage. Exemples : Azure Pipelines : main |
Variables de l’artefact principal
Dans les pipelines de mise en production classiques, si vous utilisez plusieurs artefacts, vous pouvez en désigner en tant qu'artefact principal. Azure Pipelines remplit alors les variables suivantes pour l’artefact principal désigné.
| Nom de la variable | Identique à |
|---|---|
| Build.DefinitionId | Release.Artifacts.{Primary artifact alias}.DefinitionId |
| Build.DefinitionName | Release.Artifacts.{Primary artifact alias}.DefinitionName |
| Build.BuildNumber | Release.Artifacts.{Primary artifact alias}.BuildNumber |
| Build.BuildId | Release.Artifacts.{Primary artifact alias}.BuildId |
| Build.BuildURI | Release.Artifacts.{Primary artifact alias}.BuildURI |
| Build.SourceBranch | Release.Artifacts.{Primary artifact alias}.SourceBranch |
| Build.SourceBranchName | Release.Artifacts.{Primary artifact alias}.SourceBranchName |
| Build.SourceVersion | Release.Artifacts.{Primary artifact alias}.SourceVersion |
| Build.Repository.Provider | Release.Artifacts.{Primary artifact alias}.Repository.Provider |
| Build.RequestedForID | Release.Artifacts.{Primary artifact alias}.RequestedForID |
| Build.RequestedFor | Release.Artifacts.{Primary artifact alias}.RequestedFor |
| Build.Type | Release.Artifacts.{Primary artifact alias}.Type |
| Build.PullRequest.TargetBranch | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch |
| Build.PullRequest.TargetBranchName | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName |
Utiliser les variables par défaut
Vous pouvez utiliser les variables par défaut de deux manières : en tant que paramètres pour des tâches dans un pipeline de mise en production ou dans vos scripts.
Vous pouvez utiliser une variable par défaut directement en tant qu’entrée dans une tâche. Par exemple, pour transmettre Release.Artifacts.{Artifact alias}.DefinitionName en tant qu’argument à une tâche PowerShell pour un artefact dont l'alias est ASPNET4.CI, vous devez utiliser $(Release.Artifacts.ASPNET4.CI.DefinitionName).
Pour utiliser une variable par défaut dans votre script, vous devez d’abord remplacer . par _ dans les noms des variables par défaut. Par exemple, pour imprimer la valeur d’un Release.Artifacts.{Artifact alias}.DefinitionName artefact avec ASPNET4.CI comme alias dans un script PowerShell, utilisez $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME. Notez que l’alias d’origine, ASPNET4.CI, est remplacé par ASPNET4_CI.
Variables personnalisées
Les variables personnalisées peuvent être définies dans différentes étendues.
Groupes de variables : utilisez-les pour partager des valeurs entre toutes les définitions d’un projet. Cela est utile lorsque vous souhaitez utiliser les mêmes valeurs sur l'ensemble des définitions, phases et tâches d’un projet, et pouvoir les gérer à partir d’un emplacement unique. Les groupes de variables sont définis et gérés dans Pipelines>Bibliothèque.
Variables de pipeline de mise en production : utilisez-les pour partager des valeurs entre toutes les phases d’un pipeline de mise en production. Elles sont particulièrement utiles dans les scénarios où vous avez besoin d’une valeur cohérente entre les différentes phases et tâches, avec la possibilité de la mettre à jour à partir d’un emplacement unique. Ces variables sont définies et gérées sous l’onglet Variables du pipeline de mise en production. Dans la page Variables de pipeline, ouvrez la liste déroulante Étendue et sélectionnez Mise en production lors de l’ajout d’une variable.
Variables de phase : utilisez-les pour partager des valeurs dans une phase spécifique d’un pipeline de mise en production. Cela est utile pour des valeurs qui diffèrent d’une phase à l’autre, mais qui restent les mêmes dans toutes les tâches d’une phase. Ces variables sont définies et gérées sous l’onglet Variables du pipeline de mise en production. Dans la page Variables de pipeline, ouvrez la liste déroulante Étendue et sélectionnez l'environnement approprié lors de l’ajout d’une variable.
L’utilisation de variables personnalisées au niveau du projet, du pipeline de mise en production et de la phase vous offre les possibilités suivantes :
Éviter de dupliquer des valeurs, afin de faciliter la mise à jour de l’ensemble des occurrences en un seul changement.
Sécuriser des valeurs sensibles en les empêchant d’être consultées ou modifiées par des utilisateurs. Pour marquer une variable comme sécurisée (secrète), sélectionnez l’icône
située face à elle.Important
Les valeurs des variables masquées (secrètes) sont stockées en toute sécurité sur le serveur et ne peuvent pas être consultées par les utilisateurs après l’enregistrement. Lors du déploiement, Azure Pipelines déchiffre ces valeurs qui sont référencées par des tâches et les transmet à l’agent via un canal HTTPS sécurisé.
Remarque
La création de variables personnalisées peut écraser les variables standard. Par exemple, si vous définissez une variable Path personnalisée sur un agent Windows, elle remplace la variable $env:Path, ce qui peut empêcher PowerShell de s’exécuter correctement.
Utiliser des variables personnalisées
Pour utiliser des variables personnalisées dans vos tâches, placez le nom de la variable entre parenthèses et de le faire précéder d’un caractère $. Par exemple, pour une variable nommée adminUserName, vous pouvez insérer sa valeur actuelle dans une tâche en tant que $(adminUserName).
Remarque
Les variables provenant de différents groupes liés à un pipeline dans la même étendue (par exemple, un travail ou une phase) peuvent être en conflit, ce qui entraîne des résultats imprévisibles. Pour éviter cela, assurez-vous d'utiliser des noms uniques pour les variables de tous vos groupes de variables.
Définir et modifier vos variables dans un script
Pour définir ou modifier une variable à partir d’un script, utilisez la commande de journalisation task.setvariable. La valeur de la variable mise à jour est limitée au travail en cours d’exécution et ne persiste pas dans les différents travaux ou phases. Veuillez noter que les noms de variables sont transformés en majuscules, et les caractères « . » et « » sont remplacés par « _ ».
Par exemple, Agent.WorkFolder devient AGENT_WORKFOLDER.
- Sous Windows, vous accédez à cet variable en tant que
%AGENT_WORKFOLDER%ou$env:AGENT_WORKFOLDER. - Sur Linux et macOS, veuillez utiliser
$AGENT_WORKFOLDER.
Conseil
Vous pouvez exécuter un script :
- Sur un agent Windows en utilisant une tâche de script Batch ou une tâche PowerShell.
- sur un agent macOS ou Linux en utilisant une tâche de script Shell.
Script Batch
Définir les variables sauce et secret.Sauce
@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic
Lire les variables
Arguments
"$(sauce)" "$(secret.Sauce)"
Script
@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)
Définir les variables 
Définir les variables Sortie de console après lecture des variables :
No problem reading crushed tomatoes or crushed tomatoes
But I cannot read
But I can read ******** (but the log is redacted so I do not spoil the secret)
Afficher les valeurs actuelles de l’ensemble des variables
Sélectionnez Pipelines>Mises en production, puis sélectionnez votre pipeline de mise en production.
Ouvrez la vue récapitulative de votre mise en production et sélectionnez la phase qui vous intéresse. Dans la liste des étapes, choisissez Initialiser le travail.
Cette opération ouvre les journaux de cette phase. Faites défiler vers le bas pour afficher les valeurs utilisées par l’agent pour ce travail.
Exécuter une mise en production en mode débogage
L’exécution d’une mise en production en mode débogage peut vous aider à diagnostiquer et résoudre des problèmes ou des défaillances en vous montrant des informations supplémentaires pendant l’exécution de la mise en production. Vous pouvez activer le mode débogage pour l’intégralité de la mise en production ou bien uniquement pour les tâches d'une phase de mise en production spécifique.
Pour activer le mode débogage pour une mise en production entière, ajoutez une variable nommée
System.Debugdéfinie sur la valeurtruesous l’onglet Variables du pipeline de mise en production.Pour activer le mode débogage sur une phase spécifique, ouvrez la boîte de dialogue Configurer la phase dans le menu contextuel de la phase et ajoutez une variable nommée
System.Debugdéfinie sur la valeurtrueà l’onglet Variables.Vous pouvez également créer un groupe de variables contenant une variable nommée
System.Debugdéfinie sur la valeurtrueet lier ce groupe de variables au pipeline de mise en production.
Conseil
En cas d’erreur en vous connectant au service Azure ARM, consultez Guide pratique pour résoudre les problèmes de connexion au service Azure Resource Manager.