Expressions de modèle

  • Article

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 de modèle, ainsi que des variables. Vous pouvez utiliser 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.

Notes

Les expressions sont développées uniquement pour stages, jobs, stepset containers (à l’intérieur resources). Vous ne pouvez pas, par exemple, utiliser une expression à l’intérieur trigger ou une ressource comme repositories. En outre, sur Azure DevOps 2020 RTW, vous ne pouvez pas utiliser d’expressions de modèle dans containers.

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

# File: steps/msbuild.yml

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

steps:
- task: msbuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}  # property dereference syntax

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

# File: azure-pipelines.yml

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

Context

Dans une expression de modèle, vous avez accès au parameters contexte 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 min. : 2. Paramètres max. : N
  • Exemple : ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

  • Évalue le premier argument de type de chaîne non vide et non nulle
  • Paramètres min. : 2. Paramètres max. : N
  • Exemple :
parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

steps:
- script: echo ${{ coalesce(parameters.foo, parameters.bar, 'Nothing to see') }}

Insertion

Vous pouvez utiliser des expressions de modèle pour modifier la structure d’un pipeline YAML. Pour instance, afin d’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: msbuild@1
  - ${{ parameters.preTest }}
  - task: vstest@2
  - ${{ 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

Lorsqu’un tableau est inséré dans un tableau, le tableau imbriqué est aplatit.

Pour insérer dans un mappage, 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: msbuild@1
  - task: vstest@2

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: msbuild
  type: string
  values:
  - msbuild
  - dotnet

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

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: dotnet@1
    inputs:
      command: build
  - task: dotnet@1
    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

Insertion itérative

La each directive autorise 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 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 placer une valeur d’échappement qui contient ${{littéralement , encapsulez la valeur dans une chaîne d’expression. Par exemple, ${{ 'my${{value' }} ou ${{ 'my${{value with a '' single quote too' }}.