Paramètres de modèle

Vous pouvez spécifier des paramètres et leurs types de données dans un modèle et référencer ces paramètres dans un pipeline. Avec templateContext, vous pouvez passer des propriétés supplémentaires à des index, des étapes et des travaux qui sont utilisés comme paramètres dans un modèle.

Vous pouvez également utiliser des paramètres en dehors des modèles. Vous pouvez uniquement utiliser des littéraux pour les valeurs par défaut des paramètres. Consultez la section sur les paramètres dans le schéma YAML.

Passage de paramètres

Les paramètres doivent contenir un nom et un type de données. Dans azure-pipelines.yml, lorsque le paramètre yesNo est défini sur une valeur booléenne, la build réussit. Quand yesNo est défini sur une chaîne telle que apples, la build échoue.

# File: simple-param.yml
parameters:
- name: yesNo # name of the parameter; required
  type: boolean # data type of the parameter; required
  default: false

steps:
- script: echo ${{ parameters.yesNo }}

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: simple-param.yml
  parameters:
      yesNo: false # set to a non-boolean value to have the build fail

Utiliser templateContext pour passer des propriétés aux modèles

Vous pouvez utiliser templateContext pour passer des propriétés supplémentaires à des phases, des étapes et des travaux utilisés comme paramètres dans un modèle. Plus précisément, vous pouvez spécifier templateContext dans le type de données de paramètre jobList, deploymentListou stageList .

Vous pouvez utiliser templateContext pour faciliter la configuration des environnements lors du traitement de chaque travail. En regroupant un travail et son objet de propriétés d’environnement, templateContext vous pouvez avoir un YAML plus facile à gérer et à comprendre.

Dans cet exemple, le paramètre testSet dans testing-template.yml a le type de données jobList. Le modèle testing-template.yml crée une variable testJob à l’aide de chaque mot clé. Le modèle référence ensuite le testJob.templateContext.expectedHTTPResponseCode, qui est défini dans azure-pipeline.yml et passé au modèle.

Lorsque le code de réponse est 200, le modèle effectue une requête REST. Lorsque le code de réponse est 500, le modèle génère toutes les variables d’environnement pour le débogage.

templateContext peut contenir des propriétés.

#testing-template.yml

parameters: 
- name: testSet
  type: jobList

jobs:
- ${{ each testJob in parameters.testSet }}:  # Iterate over each job in the 'testSet' parameter
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}: # Check if the HTTP response is 200
    - job:
      steps: 
      - powershell: 'Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ | Format-Table -Property Title, pubDate'
      - ${{ testJob.steps }}    
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}: # Check if the HTTP response is 500
    - job:
      steps:
      - powershell: 'Get-ChildItem -Path Env:\' # Run a PowerShell script to list environment variables
      - ${{ testJob.steps }} # Include additional steps from the 'testJob' object

#azure-pipeline.yml

trigger: none

pool:
  vmImage: ubuntu-latest

extends:
  template: testing-template.yml 
  parameters:
    testSet:  # Define the 'testSet' parameter to pass to the template
    - job: positive_test # Define a job named 'positive_test'
      templateContext:
        expectedHTTPResponseCode: 200 # Set the expected HTTP response code to 200 for this job
      steps:
      - script: echo "Run positive test" 
    - job: negative_test # Define a job named 'negative_test'
      templateContext:
        expectedHTTPResponseCode: 500 # Set the expected HTTP response code to 500 for this job
      steps:
      - script: echo "Run negative test" 

Paramètres pour sélectionner un modèle au moment de l’exécution

Vous pouvez appeler différents modèles à partir d’un pipeline YAML en fonction d’une condition. Dans cet exemple, l’élément YAML experimental.yml s’exécute lorsque le paramètre experimentalTemplate a la valeur true.

#azure-pipeline.yml
parameters:
- name: experimentalTemplate 
  displayName: 'Use experimental build process?'
  type: boolean
  default: false

steps:
- ${{ if eq(parameters.experimentalTemplate, true) }}: # Check if 'experimentalTemplate' is true
  - template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:  # Check if 'experimentalTemplate' is not true
  - template: stable.yml

Types de données de paramètre

Les types de données step, stepList, job, jobList, deploymentList, stagelist et stageList utilisent tous le format de schéma YAML standard. Cet exemple inclut string, number, boolean, object, step et stepList.

parameters:
- name: myString  # Define a parameter named 'myString'
  type: string  # The parameter type is string
  default: a string  # Default value is 'a string'

- name: myMultiString  # Define a parameter named 'myMultiString'
  type: string  # The parameter type is string
  default: default  # Default value is 'default'
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myNumber  # Define a parameter named 'myNumber'
  type: number  # The parameter type is number
  default: 2  # Default value is 2
  values:  # Allowed values for 'myNumber'
  - 1  
  - 2  
  - 4  
  - 8  
  - 16  

- name: myBoolean  # Define a parameter named 'myBoolean'
  type: boolean  # The parameter type is boolean
  default: true  # Default value is true

- name: myObject  # Define a parameter named 'myObject'
  type: object  # The parameter type is object
  default:  # Default value is an object with nested properties
    foo: FOO  # Property 'foo' with value 'FOO'
    bar: BAR  # Property 'bar' with value 'BAR'
    things:  # Property 'things' is a list
    - one  
    - two  
    - three  
    nested:  # Property 'nested' is an object
      one: apple  # Property 'one' with value 'apple'
      two: pear  # Property 'two' with value 'pear'
      count: 3  # Property 'count' with value 3

- name: myStep  # Define a parameter named 'myStep'
  type: step  # The parameter type is step
  default:  # Default value is a step
    script: echo my step 

- name: mySteplist  # Define a parameter named 'mySteplist'
  type: stepList  # The parameter type is stepList
  default:  # Default value is a list of steps
    - script: echo step one  
    - script: echo step two  

trigger: none  

jobs: 
- job: stepList  # Define a job named 'stepList'
  steps: ${{ parameters.mySteplist }}  # Use the steps from the 'mySteplist' parameter

- job: myStep  # Define a job named 'myStep'
  steps:
    - ${{ parameters.myStep }}  # Use the step from the 'myStep' parameter

Vous pouvez itérer au sein d’un objet et imprimer chaque chaîne de l’objet.

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

steps:
- ${{ each value in parameters.listOfStrings }}: # Iterate over each value in the 'listOfStrings' parameter
  - script: echo ${{ value }} # Output the current value in the iteration

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 }} : # Iterate over each fruit in the 'listOfFruits'
  - ${{ each fruitColor in fruit.colors}} : # Iterate over each color in the current fruit's colors
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }} # Echo the current fruit's name and color

Paramètres obligatoires

Vous pouvez ajouter une étape de validation au début de votre modèle pour vérifier les paramètres dont vous avez besoin.

Voici un exemple qui vérifie le paramètre solution à l’aide de Bash :

# File: steps/msbuild.yml

parameters:
- name: 'solution'
  default: ''
  type: string

steps:
- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi
  env:
    SOLUTION: ${{ parameters.solution }}
  displayName: Check for required parameters
- task: msbuild@1
  inputs:
    solution: ${{ parameters.solution }}
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}

Pour montrer que le modèle échoue s’il manque le paramètre requis :

# File: azure-pipelines.yml

# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml

Vous pouvez passer des paramètres aux modèles. La parameters section définit les paramètres disponibles dans le modèle et leurs valeurs par défaut. Les modèles sont développés juste avant l’exécution du pipeline afin que les valeurs entourées par ${{ }} soient remplacées par les paramètres qu’il reçoit du pipeline englobant. Par conséquent, seules les variables prédéfinies peuvent être utilisées dans les paramètres.

Pour utiliser des paramètres dans plusieurs pipelines, découvrez comment créer un groupe de variables.

Modèles de travail, de phase et d’étape avec des paramètres

# File: templates/npm-with-params.yml

parameters:
  name: ''  # defaults for any parameters that aren't specified
  vmImage: ''

jobs:
- job: ${{ parameters.name }}
  pool: 
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

Lorsque vous utilisez le modèle dans votre pipeline, spécifiez des valeurs pour les paramètres du modèle.

# File: azure-pipelines.yml

jobs:
- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: Linux
    vmImage: 'ubuntu-latest'

- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: macOS
    vmImage: 'macOS-10.13'

- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: Windows
    vmImage: 'windows-latest'

Vous pouvez également utiliser des paramètres avec des modèles d’étape ou de phase. Par exemple, les étapes avec les paramètres :

# File: templates/steps-with-params.yml

parameters:
  runExtendedTests: 'false'  # defaults for any parameters that aren't specified

steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, 'true') }}:
  - script: npm test --extended

Lorsque vous utilisez le modèle dans votre pipeline, spécifiez des valeurs pour les paramètres du modèle.

# File: azure-pipelines.yml

steps:
- script: npm install

- template: templates/steps-with-params.yml  # Template reference
  parameters:
    runExtendedTests: 'true'

Les paramètres ne sont pas limités aux chaînes scalaires. Tant que l’endroit où le paramètre se développe attend un mappage, le paramètre peut être un mappage. De même, les séquences peuvent être passées là où des séquences sont attendues. Par exemple :

# azure-pipelines.yml
jobs:
- template: process.yml
  parameters:
    pool:   # this parameter is called `pool`
      vmImage: ubuntu-latest  # and it's a mapping rather than a string


# process.yml
parameters:
  pool: {}

jobs:
- job: build
  pool: ${{ parameters.pool }}