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. Vous pouvez évaluer des expressions au moment de la compilation ou au moment de l’exécution. Utilisez des expressions de temps de compilation n’importe où ; utilisez des expressions runtime dans des variables et des conditions. Utilisez des expressions runtime pour 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

fusionner

• Évalue les paramètres dans l’ordre (de gauche à droite) et retourne la première valeur qui n’est pas null ou une chaîne vide.
• Retourne aucune valeur si toutes les valeurs de paramètre sont null ou des chaînes vides.
• Paramètres minimaux : 2. Paramètres maximum : 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"
    ]
  }
}

compteur

• Utilisez cette fonction uniquement dans une expression qui définit une variable. Ne l’utilisez pas dans une condition pour une étape, une tâche ou un stade.
• Évalue un nombre qui incrémente avec chaque exécution d’un pipeline.
• Prend deux paramètres : prefix et seed.
• prefix est une expression de chaîne. La fonction effectue le suivi d’une valeur de compteur distincte pour chaque valeur unique prefix. Utilisez des caractères UTF-16 dans le prefix.
• seed est la valeur de départ du compteur.

Vous pouvez créer un compteur qui s'accroît automatiquement de un chaque fois que votre pipeline s’exécute. Lorsque vous définissez un compteur, fournissez un prefix et un seed. L’exemple suivant illustre ce concept.

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)

La valeur de minor dans l’exemple précédent est 100 pendant la première exécution du pipeline. Dans la deuxième exécution, la valeur est 101, tant que la valeur de major reste 1.

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

Si vous modifiez ultérieurement le fichier YAML et définissez la valeur de major retour sur 1, la valeur du compteur reprend là où elle s’est arrêtée pour ce préfixe. Dans cet exemple, il reprend à 102.

L’exemple suivant montre comment définir une variable comme compteur qui commence à 100, incrémente de 1 pour chaque exécution et est réinitialisée à 100 par jour.

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

L’exemple suivant montre un compteur qui conserve une valeur distincte pour les demandes de tirage et les exécutions CI.

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

Les compteurs sont limités à un pipeline. En d’autres termes, le pipeline incrémente la valeur du compteur pour chaque exécution. Aucun compteur n'est spécifique au 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 }}')

iif

• Renvoie le deuxième paramètre si le premier paramètre prend la valeur True, et le troisième paramètre sinon.
• Paramètres min. : 1. Paramètres max. : 3
• Le premier paramètre doit être une condition
• Exemple : iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') retourne « ManagedDevOpsPool » pendant l'exécution du pipeline en réponse à une demande de tirage.

joindre

• 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 minimaux : 2. Paramètres maximum : 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

baisser

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

remplacer

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

fractionner

• Fractionne une chaîne en sous-chaînes en fonction des caractères de délimitation spécifiés.
• Paramètres minimaux : 2. Paramètres maximum : 2.
• Le premier paramètre est la chaîne à fractionner.
• Le deuxième paramètre est les caractères de limitation.
• Retourne un tableau de sous-chaînes. Le tableau inclut des chaînes vides lorsque les caractères de délimitation 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 }}
  

couper

• Retourne le paramètre sans espaces blancs de début et de fin
• Paramètres min. : 1. Paramètres max. : 1
• Exemple : trim(' variable ') retourne « variable »

supérieur

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

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

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. Dans cet exemple, la valeur de foo retourne true dans la elseif condition.

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"

Chaque mot clé

Utilisez le each mot clé pour parcourir 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 }}

Vous pouvez également effectuer une itération via des éléments imbriqués au sein d’un objet.

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. Utilisez des dépendances pour :

• Consulter l'état d'une tâche précédente
• 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 les variables de sortie ayant des caractères de guillemets (' ou ") dans ces variables, 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.

La syntaxe des variables de sortie dans les travaux de déploiement varie 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 un mappage des noms de tâches et de phases vers results et outputs. Exprimé en tant que JSON, il ressemble à ceci :

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

Utilisez cette forme de dependencies pour mapper des variables ou vérifier des conditions à un niveau d'étape.

Dans cet exemple, deux étapes existent, A et B. L’étape A a la condition false et ne s’exécute pas. 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, deux étapes existent. 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 entre tâches au sein d'une étape

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 emplois (a, b et c). Job a est toujours ignoré en raison de condition: false. La tâche b s’exécute, car elle n’a aucune condition 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 d'une tâche à une autre entre les différentes étapes

Au niveau de la tâche, vous pouvez également référencer les résultats d'une tâche d'une étape 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, la tâche B1 s’exécute si la tâche A1 est ignorée. 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 la configuration de déploiement build_job, qui règle 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