Expressions de modèle

Les expressions de modèle rendent vos modèles Azure Pipelines plus dynamiques et réutilisables. À l’aide d’expressions de modèle, vous pouvez :

• Paramétrer des modèles : passez des valeurs aux modèles pour personnaliser leur comportement sans dupliquer du code.
• Incluez de manière conditionnelle le contenu : ajoutez ou excluez dynamiquement des étapes de pipeline, des travaux ou des étapes en fonction des valeurs de paramètre.
• Insérer et itérer sur des collections : générez plusieurs éléments de pipeline à partir de tableaux ou de paires clé-valeur.
• Réduire la répétition : créez des modèles flexibles et réutilisables qui fonctionnent dans différents scénarios et équipes.

Utilisez des expressions de modèle pour spécifier la façon dont les valeurs sont résolues dynamiquement pendant l’initialisation du pipeline. Encapsulez votre expression de modèle dans cette syntaxe : ${{ }}.

Les expressions de modèle peuvent développer des paramètres et des variables de modèle. Utilisez des paramètres pour influencer la façon dont un modèle est développé. L’objet parameters fonctionne comme variablesl’objet dans une expression. Seules les variables prédéfinies peuvent être utilisées dans les expressions de modèle.

Par exemple, vous définissez un modèle :

# File: steps/vsbuild.yml

parameters:
- name: 'solution'
  default: '**/*.sln'
  type: string

steps:
- task: VSBuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: VSTest@3
  inputs:
    testSelector: 'testAssemblies' 
    testAssemblyVer2: ${{ parameters.solution }} # property dereference syntax
    searchFolder: '$(System.DefaultWorkingDirectory)' 

Vous référencez ensuite le modèle et lui transmettez le paramètre facultatif solution :

# File: azure-pipelines.yml

steps:
- template: steps/vsbuild.yml
  parameters:
    solution: my.sln

Contexte

Dans une expression de modèle, vous avez accès au parameters contexte (ensemble de données disponibles dans l’expression, tels que les paramètres et les variables passés au modèle) qui contient les valeurs des paramètres passés. En outre, vous avez accès au contexte variables qui contient toutes les variables spécifiées dans le fichier YAML, ainsi qu’à la plupart des variables prédéfinies (notées sur chaque variable de cet article). Il est important de noter qu’il n’a pas de variables d’exécution telles que celles stockées sur le pipeline ou données lorsque vous démarrez une exécution. L’expansion du modèle se produit au début de l’exécution, de sorte que ces variables ne sont pas disponibles.

Fonctions d’expression de modèle

Vous pouvez utiliser des fonctions générales dans vos modèles. Vous pouvez également utiliser quelques fonctions d’expression de modèle.

format

• Remplacement de jeton de chaîne simple
• Paramètres minimaux : 2. Paramètres maximum : N
• Exemple : ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

fusionner

• Évalue le premier argument de type de chaîne non vide et non nulle
• Paramètres minimaux : 2. Paramètres maximum : N
• Exemple :

parameters:
- name: 'customVersion'
  type: string
  default: ''
- name: 'defaultVersion'
  type: string
  default: '1.0.0'

steps:
- script: echo Version is ${{ coalesce(parameters.customVersion, parameters.defaultVersion) }}

Ajout

Utilisez des expressions de modèle pour modifier la structure d’un pipeline YAML. Par exemple, utilisez l’expression suivante pour insérer dans une séquence :

# File: jobs/build.yml

parameters:
- name: 'preBuild'
  type: stepList
  default: []
- name: 'preTest'
  type: stepList
  default: []
- name: 'preSign'
  type: stepList
  default: []

jobs:
- job: Build
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: cred-scan
  - ${{ parameters.preBuild }}
  - task: VSBuild@1
  - ${{ parameters.preTest }}
  - task: VSTest@3
  - ${{ parameters.preSign }}
  - script: sign

# File: .vsts.ci.yml

jobs:
- template: jobs/build.yml
  parameters:
    preBuild:
    - script: echo hello from pre-build
    preTest:
    - script: echo hello from pre-test

Lorsque vous insérez un tableau dans un tableau, vous aplatirez le tableau imbriqué.

Pour insérer dans un mappage (collection de paires clé-valeur, similaire à un dictionnaire ou un objet dans YAML), utilisez la propriété spéciale ${{ insert }}.

# Default values
parameters:
- name: 'additionalVariables'
  type: object
  default: {}

jobs:
- job: build
  variables:
    configuration: debug
    arch: x86
    ${{ insert }}: ${{ parameters.additionalVariables }}
  steps:
  - task: VSBuild@1
  - task: VSTest@3

jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

Insertion conditionnelle

Si vous souhaitez insérer de manière conditionnelle dans une séquence ou un mappage dans un modèle, utilisez les insertions et l’évaluation des expressions. Vous pouvez également utiliser if des instructions en dehors des modèles tant que vous utilisez la syntaxe de modèle.

Par exemple, pour insérer dans une séquence dans un modèle :

# File: steps/build.yml

parameters:
- name: 'toolset'
  default: vsbuild
  type: string
  values:
  - vsbuild
  - dotnet

steps:
# msbuild
- ${{ if eq(parameters.toolset, 'msbuild') }}:
  - task: VSBuild@1
  - task: VSTest@3

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: UseDotNet@2
    inputs:
      command: build
  - task: UseDotNet@2
    inputs:
      command: test

# File: azure-pipelines.yml

steps:
- template: steps/build.yml
  parameters:
    toolset: dotnet

Par exemple, pour insérer dans un mappage dans un modèle :

# File: steps/build.yml

parameters:
- name: 'debug'
  type: boolean
  default: false

steps:
- script: tool
  env:
    ${{ if eq(parameters.debug, true) }}:
      TOOL_DEBUG: true
      TOOL_DEBUG_DIR: _dbg

steps:
- template: steps/build.yml
  parameters:
    debug: true

Vous pouvez également utiliser l’insertion conditionnelle pour les variables. Dans cet exemple, start imprime toujours et this is a test imprime uniquement lorsque la foo variable est égale à test.

variables:
  - name: foo
    value: test

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.foo, 'test') }}:
  - script: echo "this is a test" # runs when foo=test

Vous pouvez également définir des variables en fonction des valeurs d’autres variables. Dans le pipeline suivant, myVar est utilisé pour définir la valeur de conditionalVar.

trigger:
- main

pool: 
   vmImage: 'ubuntu-latest' 

variables:
  - name: myVar
    value: 'baz'

  - name: conditionalVar
    ${{ if eq(variables['myVar'], 'foo') }}:
      value: 'bar'
    ${{ elseif eq(variables['myVar'], 'baz') }}:
      value: 'qux'
    ${{ else }}:
      value: 'default'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.conditionalVar, 'bar') }}:
  - script: echo "the value of myVar is set in the if condition" # runs when myVar=foo
- ${{ if eq(variables.conditionalVar, 'qux') }}:
  - script: echo "the value of myVar is set in the elseif condition" # runs when myVar=baz

Insertion itérative

La each directive active l’insertion itérative basée sur une séquence YAML (tableau) ou un mappage (paires clé-valeur).

Par exemple, vous pouvez encapsuler les étapes de chaque travail avec d’autres étapes avant et après :

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This will get sandwiched between SetupMyBuildTools and PublishMyTelemetry.
    - job: B
      steps:
      - script: echo So will this!

Vous pouvez également utiliser stringList pour définir et itérer sur les paramètres qui contiennent une liste d’éléments.

parameters:
- name: regions
  type: stringList
  displayName: Regions
  values:
    - WUS
    - CUS
    - EUS
  default: 
    - WUS
    - EUS 

stages:
- ${{ each stage in parameters.regions}}:
  - stage: ${{stage}}
    displayName: Deploy to ${{stage}}
    jobs:
    - job:
      steps:
      - script: ./deploy ${{stage}}

Vous pouvez également manipuler les propriétés de tout ce que vous effectuez une itération. Par exemple, pour ajouter d’autres dépendances :

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- job: SomeSpecialTool                # Run your special tool in its own job first
  steps:
  - task: RunSpecialTool@1
- ${{ each job in parameters.jobs }}: # Then do each job
  - ${{ each pair in job }}:          # Insert all properties other than "dependsOn"
      ${{ if ne(pair.key, 'dependsOn') }}:
        ${{ pair.key }}: ${{ pair.value }}
    dependsOn:                        # Inject dependency
    - SomeSpecialTool
    - ${{ if job.dependsOn }}:
      - ${{ job.dependsOn }}

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This job depends on SomeSpecialTool, even though it's not explicitly shown here.
    - job: B
      dependsOn:
      - A
      steps:
      - script: echo This job depends on both Job A and on SomeSpecialTool.

Échappement d’une valeur

Si vous devez échapper à une valeur qui contient ${{littéralement , encapsulez la valeur dans une chaîne d’expression. Par exemple, utilisez ${{ 'my${{value' }} ou ${{ 'my${{value with a '' single quote too' }}.