Paramètres de modèle

2025-06-12

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 également passer des propriétés à des phases, des étapes, et des tâches qui sont utilisées 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 d’autres propriétés à des étapes, 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

Type de données	Remarques
`string`	chaîne
`stringList`	une liste d’éléments, plusieurs peuvent être sélectionnés. Non disponible dans les modèles
`number`	peut être limité à `values:`, sinon toute chaîne de type nombre est acceptée
`boolean`	`true` ou `false`
`object`	toute structure YAML
`step`	une seule étape
`stepList`	Séquence d’étapes
`job`	un seul travail
`jobList`	Séquence de travaux
`deployment`	une seule tâche de déploiement
`deploymentList`	séquence de travaux de déploiement
`stage`	une seule phase
`stageList`	séquence d'étapes

Les types de données step, stepList, job, jobList, deployment, deploymentList, stage, stringList et stageList utilisent tous le format de schéma YAML standard. Cet exemple inclut string, , numberboolean, object, stepet stepList.

Remarque

Le stringList type de données n’est pas disponible dans les modèles. Utilisez plutôt le object type de données dans les modèles.

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', only one default
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myStringlist # Define a parameter named 'myStringlist'
  type: stringList # The parameter type is stringList
  displayName: Regions
  values: # Allowed values for 'myStringlist'
    - WUS
    - CUS
    - EUS
  default: # Default values
    - WUS
    - CUS
    
- 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

- job: stringList  # Define a job named 'stringList'
  steps:
  - ${{ each region in parameters.myStringlist }}:
      - script: echo ${{region}}

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

Vous pouvez également référencer directement les clés d’un objet et les valeurs correspondantes.

parameters:
  - name: myObject
    type: object
    default:
      key1: 'value1'
      key2: 'value2'
      key3: 'value3'

jobs:
- job: ExampleJob
  displayName: 'Example object parameter job'
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: |
      echo "Keys in myObject:"
      echo "Key1: ${{ parameters.myObject.key1 }}"
      echo "Key2: ${{ parameters.myObject.key2 }}"
      echo "Key3: ${{ parameters.myObject.key3 }}"
    displayName: 'Display object keys and values'

Paramètres obligatoires

Les pipelines signalent automatiquement une erreur si un paramètre est manquant. Vous pouvez ajouter une étape de validation au début de votre modèle pour rechercher les paramètres dont vous avez besoin et prendre les mesures appropriées.

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: VSBuild@1
  inputs:
    solution: ${{ parameters.solution }}
- task: VSTest@3
  inputs:
    testSelector: 'testAssemblies' 
    testAssemblyVer2: ${{ parameters.solution }} 
    searchFolder: '$(System.DefaultWorkingDirectory)'

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