Expressions

# Expressions are used to define conditions for a step, job, or stage
steps:
- task: ...
  condition: <expression>

Une autre utilisation courante des expressions est la définition de variables. Les expressions peuvent être évaluées au moment de la compilation ou au moment de l’exécution. Les expressions au moment de la compilation peuvent être utilisées n’importe où ; les expressions au moment de l’exécution peuvent être utilisées dans des variables et des conditions. Les expressions au moment de l’exécution sont destinées à calculer le contenu des variables et de l’état (exemple : condition).

# Two examples of expressions used to define variables
# The first one, a, is evaluated when the YAML file is compiled into a plan.
# The second one, b, is evaluated at runtime.
# Note the syntax ${{}} for compile time and $[] for runtime expressions.
variables:
  a: ${{ <expression> }}
  b: $[ <expression> ]

La différence entre les syntaxes d’expression au moment de l’exécution et de la compilation est principalement le contexte disponible. Dans une expression au moment de la compilation (${{ <expression> }}), vous avez accès à parameters et variables, défini statiquement. Dans une expression au moment de l’exécution ($[ <expression> ]), vous avez accès à variables, mais pas aux paramètres.

Dans cet exemple, une expression au moment de l’exécution définit la valeur de $(isMain). Une variable statique dans une expression au moment de la compilation définit la valeur de $(compileVar).

variables:
  staticVar: 'my value' # static variable
  compileVar: ${{ variables.staticVar }} # compile time expression
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')] # runtime expression

steps:
  - script: |
      echo ${{variables.staticVar}} # outputs my value
      echo $(compileVar) # outputs my value
      echo $(isMain) # outputs True

coalesce

• Évalue les paramètres dans l’ordre (de gauche à droite) et renvoie la première valeur qui n’est pas nulle ou n'est pas une chaîne vide.
• Aucune valeur n'est retournée si les valeurs de paramètre sont toutes null ou vides.
• Paramètres min. : 2. Paramètres max. : N
• Exemple : coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Prend un objet complexe et le génère au format JSON.
• Paramètres min. : 1. Paramètres max. : 1.

parameters:
  - name: listOfValues
    type: object
    default:
      this_is:
        a_complex: object
        with:
          - one
          - two

steps:
- script: |
    echo "${MY_JSON}"
  env:
    MY_JSON: ${{ convertToJson(parameters.listOfValues) }}

Sortie du script :

{
  "this_is": {
    "a_complex": "object",
    "with": [
      "one",
      "two"
    ]
  }
}

counter

• Cette fonction ne peut être utilisée que dans une expression qui définit une variable. Elle ne peut pas être utilisée comme faisant partie d’une condition pour une étape, un travail ou une phase.
• Évalue un nombre incrémenté à chaque exécution d’un pipeline.
• Paramètres : 2. Voir prefix et seed.
• Le préfixe est une expression de chaîne. Une valeur distincte de compteur est suivie pour chaque valeur unique de préfixe. Le prefix doit utiliser des caractères UTF-16.
• La valeur initiale est la valeur de départ du compteur

Vous pouvez créer un compteur qui est automatiquement incrémenté de 1 lors de chaque exécution de votre pipeline. Lorsque vous définissez un compteur, vous fournissez un prefix et un seed. Voici un exemple qui illustre cela.

variables:
  major: 1
  # define minor as a counter with the prefix as variable major, and seed as 100.
  minor: $[counter(variables['major'], 100)]

steps:
- bash: echo $(minor)

Dans l'exemple ci-dessus, la valeur de minor dans la première exécution de la pipeline est de 100. Dans la deuxième exécution, elle est de 101, à condition que la valeur de major soit toujours égale à 1.

Si vous modifiez le fichier YAML et mettez à jour la valeur de la variable major sur 2, lors de la prochaine exécution du pipeline, la valeur de minor sera 100. Les exécutions suivantes incrémentent le compteur à 101, 102, 103, ...

Plus tard, si vous modifiez le fichier YAML et que vous définissez à nouveau la valeur de major sur 1, la valeur du compteur reprend là où ce dernier s’est arrêté pour ce préfixe. Dans cet exemple, il reprend à 102.

Voici un autre exemple de définition d’une variable pour jouer un rôle de compteur qui commence à 100, qui est incrémenté de 1 à chaque exécution et qui est réinitialisé à 100 tous les jours.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Voici un exemple illustrant un compteur qui conserve une valeur distincte pour les demandes de tirage et les exécutions de CI.

variables:
  patch: $[counter(variables['build.reason'], 0)]

Les compteurs sont limités à un pipeline. En d’autres termes, sa valeur est incrémentée pour chaque exécution de ce pipeline. Il n’existe pas de compteurs pour l’étendue du projet.

format

• Évalue les paramètres de fin et les insère dans la chaîne de paramètres de début
• Paramètres min. : 1. Paramètres max. : N
• Exemple : format('Hello {0} {1}', 'John', 'Doe')
• Utilise des spécificateurs de format de date et d’heure personnalisés .NET pour la mise en forme de date (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
• Exemple : format('{0:yyyyMMdd}', pipeline.startTime). Dans ce cas, pipeline.startTime est une variable d’objet date/heure spéciale.
• Échappez en doublant les accolades. Par exemple : format('literal left brace {{ and literal right brace }}')

join

• Concatène tous les éléments du tableau de paramètres de droite, séparés par la chaîne de paramètre de gauche.
• Paramètres min. : 2. Paramètres max. : 2
• Chaque élément du tableau est converti en chaîne. Les objets complexes sont convertis en chaîne vide.
• Si le paramètre de droite n’est pas un tableau, le résultat est le paramètre de droite converti en chaîne.

Dans cet exemple, un point-virgule est ajouté entre chaque élément du tableau. Le type de paramètre est un objet.

parameters:
- name: myArray
  type: object
  default:
    - FOO
    - BAR
    - ZOO

variables:
   A: ${{ join(';',parameters.myArray) }}

steps:
  - script: echo $A # outputs FOO;BAR;ZOO

lower

• Convertit une chaîne ou une valeur de variable en caractères minuscules
• Paramètres min. : 1. Paramètres max. : 1
• Retourne l’équivalent minuscule d’une chaîne
• Exemple : lower('FOO') retourne foo.

remplacer

• Retourne une nouvelle chaîne dans laquelle toutes les instances d’une chaîne dans l’instance actuelle sont remplacées par une autre chaîne.
• Paramètres min. : 3. Paramètres max. : 3
• replace(a, b, c) : retourne a, avec toutes les instances de b remplacées par c
• Exemple : replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (retourne http://server/saml/consume)

split

• Divise une chaîne en sous-chaînes en fonction de caractères de délimitation spécifiés
• Paramètres min. : 2. Paramètres max. : 2
• Le premier paramètre est la chaîne à fractionner
• Le deuxième paramètre se compose des caractères délimitants
• Retourne un tableau de sous-chaînes. Le tableau inclut des chaînes vides lorsque les caractères délimitants apparaissent consécutivement ou à la fin de la chaîne
• Exemple :

  variables:
  - name: environments
    value: prod1,prod2 
  steps:  
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Exemple d'utilisation de split() avec replace() :

  parameters:
  - name: resourceIds
    type: object
    default:
    - /subscriptions/mysubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/kubernetes-internal
    - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes
  - name: environments
    type: object
    default: 
    - prod1
    - prod2
  
  trigger:
  - main
  
  steps:
  - ${{ each env in parameters.environments }}:
    - ${{ each resourceId in parameters.resourceIds }}:
        - script: echo ${{ replace(split(resourceId, '/')[8], '-', '_') }}_${{ env }}
  

upper

• Convertit une valeur de chaîne ou de variable en caractères majuscules
• Paramètres min. : 1. Paramètres max. : 1
• Retourne l’équivalent majuscule d’une chaîne
• Exemple : upper('bah') retourne BAH.

Vous pouvez utiliser les clauses if, elseif et else pour affecter des valeurs de variable de manière conditionnelle ou définir des entrées pour des tâches. Vous pouvez également exécuter une étape de manière conditionnelle lorsqu’une condition est remplie.

Vous pouvez utiliser if pour affecter des valeurs de variable de manière conditionnelle ou définir des entrées pour des tâches. Vous pouvez également exécuter une étape de manière conditionnelle lorsqu’une condition est remplie.

Les clauses elseif et else sont disponibles à partir d’Azure DevOps 2022 et ne sont pas disponibles pour Azure DevOps Server 2020 et les versions antérieures d’Azure DevOps.

Définir de manière conditionnelle une entrée de tâche

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)'
    ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      artifact: 'prod'
    ${{ else }}:
      artifact: 'dev'
    publishLocation: 'pipeline'

Exécuter une étape de manière conditionnelle

Si aucune variable n’est définie ou si la valeur de foo ne correspond pas aux conditions if, l’instruction else s’exécute. Ici, la valeur de foo retourne true dans la condition elseif.

variables:
  - name: foo
    value: contoso # triggers elseif condition

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start"
- ${{ if eq(variables.foo, 'adaptum') }}:
  - script: echo "this is adaptum"
- ${{ elseif eq(variables.foo, 'contoso') }}: # true
  - script: echo "this is contoso" 
- ${{ else }}:
  - script: echo "the value is not adaptum or contoso"

Each (mot clé)

Vous pouvez utiliser le mot clé each pour effectuer une boucle dans les paramètres avec le type d’objet.

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

En outre, vous pouvez itérer au sein d’un objet à travers des éléments imbriqués.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Les dépendances

Les expressions peuvent utiliser le contexte des dépendances pour référencer des travaux ou des phases précédents. Vous pouvez utiliser les dépendances pour :

• Référencer l’état du travail d’un travail précédent
• Référencer l’état de phase d’une phase précédente
• Référencer des variables de sortie dans le travail précédent dans la même phase
• Référencer les variables de sortie à la phase précédente d’une phase
• Référencer des variables de sortie dans un travail à une phase précédente de la phase suivante

Le contexte est appelé dependencies pour les travaux et les phases et fonctionne comme les variables. Si vous faites référence à une variable de production d'un projet dans une autre étape, le contexte est appelé stageDependencies.

Si vous rencontrez des problèmes avec des variables de sortie contenant des guillemets (' ou "), consultez ce guide de résolution des problèmes.

Vue d'ensemble de la syntaxe des dépendances

La syntaxe du référencement des variables de production avec dépendances varie en fonction des circonstances. Voici une vue d'ensemble des scénarios les plus courants. Il peut parfois arriver que la syntaxe alternative fonctionne également.

Il existe également différentes syntaxes pour les variables de production dans les projets de déploiement en fonction de la stratégie de déploiement. Pour en savoir plus, consultez Projets de déploiement.

Dépendances phase à phase

Structurellement, l’objet dependencies est une carte des noms de travaux et de phases vers results et outputs. Exprimé au format JSON, il se présente comme suit :

"dependencies": {
  "<STAGE_NAME>" : {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
        "jobName.stepName.variableName": "value"
    }
  },
  "...": {
    // another stage
  }
}

Utilisez cette forme de dependencies pour mapper dans des variables ou vérifier les conditions à un niveau intermédiaire.

Dans cet exemple, il existe deux étapes, A et B. L'étape A a la condition false et ne s'exécute jamais comme résultat. L'étape B s'exécute si le résultat de l'étape A est Succeeded, SucceededWithIssues ou Skipped. La phase B s’exécute parce que la phase A a été ignorée.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Les phases peuvent également utiliser des variables de sortie d’une autre phase. Dans cet exemple, il existe également deux étapes. L'étape A inclut un projet, A1, qui définit une variable de production shouldrun sur true. L'étape B s'exécute quand shouldrun est true. Comme shouldrun est true, l'étape B s'exécute.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

Dépendances de travail à travail au sein d’une phase

Au niveau du travail au sein d’une seule phase, les données dependencies ne contiennent pas d’informations au niveau de la phase.

"dependencies": {
  "<JOB_NAME>": {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
      "stepName.variableName": "value1"
    }
  },
  "...": {
    // another job
  }
}

Dans cet exemple, il existe trois projets (a, b et c). Le projet a toujours été ignoré en raison de condition: false. Le projet b s'exécute, car aucune condition n'est associée. Le projet c s'exécute, car toutes ses dépendances réussissent (projet b) ou sont ignorées (projet a).

jobs:
- job: a
  condition: false
  steps:
  - script: echo Job a
- job: b
  steps:
  - script: echo Job b
- job: c
  dependsOn:
  - a
  - b
  condition: |
    and
    (
      in(dependencies.a.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'),
      in(dependencies.b.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
    )
  steps:
  - script: echo Job c

Dans cet exemple, le travail B dépend d’une variable de sortie du travail A.

jobs:
- job: A
  steps:
  - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
  # or on Windows:
  # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
    name: printvar

- job: B
  condition: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Dépendances de travail à travail entre différentes phases

Au niveau du travail, vous pouvez également référencer les sorties d’un travail d’une phase précédente. Cela nécessite l’utilisation du contexte stageDependencies.

"stageDependencies": {
  "<STAGE_NAME>" : {
    "<JOB_NAME>": {
      "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
      "outputs": {
          "stepName.variableName": "value"
      }
    },
    "...": {
      // another job
    }
  },
  "...": {
    // another stage
  }
}

Dans cet exemple, le travail B1 s’exécute si le travail A1 est ignoré. Le travail B2 vérifie la valeur de la variable de sortie du travail A1 pour déterminer s'il doit s’exécuter.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  dependsOn: A
  jobs:
  - job: B1
    condition: in(stageDependencies.A.A1.result, 'Skipped') # change condition to `Succeeded and stage will be skipped`
    steps:
    - script: echo hello from Job B1
  - job: B2
    condition: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')
    steps:
     - script: echo hello from Job B2

Si un travail dépend d’une variable définie par un travail de déploiement à une phase différente, la syntaxe est différente. Dans l’exemple suivant, le travail run_tests s’exécute si le travail de déploiement build_job a défini runTests sur true. Notez que la clé utilisée pour le dictionnaire outputs est build_job.setRunTests.runTests.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  jobs:  
    - job: run_tests
      condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true')
      steps:
        ...

Variables de production de projet de déploiement

Si une phase dépend d’une variable définie par un travail de déploiement dans une autre phase, la syntaxe est différente. Dans l’exemple suivant, la phase test dépend de build_job pour le déploiement, qui définit shouldTest sur true. Notez que dans le condition de la phase test, build_job apparaît deux fois.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')
  jobs:
    - job: A
      steps:
        - script: echo Hello from job A

Dans l’exemple ci-dessus, la condition fait référence à un environnement et non à une ressource d’environnement. Pour référencer une ressource d’environnement, vous devez ajouter le nom de la ressource d’environnement à la condition de dépendances. Dans l’exemple suivant, la condition fait référence à une ressource de machine virtuelle d’environnement nommée vmtest.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: vmtest
      resourceName: winVM2
      resourceType: VirtualMachine
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.Deploy_winVM2.setRunTests.runTests'], 'true')
  jobs:
  - job: A
    steps:
     - script: echo Hello from job A