Expressions de modèle
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 variables
l’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
, steps
et 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' }}
.