Paramètres de runtime

Article
08/08/2024

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Les paramètres de runtime vous permettent d’avoir plus de contrôle sur les valeurs qui peuvent être passées à un pipeline. Avec des paramètres de runtime, vous pouvez :

Fournir des valeurs différentes aux scripts et aux tâches au moment de l’exécution
Types de paramètres de contrôle, plages autorisées et valeurs par défaut
Sélection dynamique de travaux et d’étapes à l’aide d’expressions de modèle

Vous pouvez spécifier des paramètres dans des modèles et dans le pipeline. Les paramètres ont des types de données comme des nombres et des chaînes et ils peuvent être limités à un sous-ensemble de valeurs. La section parameters dans un fichier YAML définit les paramètres disponibles.

Les paramètres sont uniquement disponibles au moment de l’analyse des modèles. Les paramètres sont développés juste avant les exécutions de pipeline afin que les valeurs entourées par ${{ }} soient remplacées par des valeurs de paramètre. Utilisez des variables si vous avez besoin que vos valeurs soient plus largement disponibles pendant votre exécution de pipeline.

Notes

Ces conseils ne s’appliquent pas aux pipelines classiques. Pour connaître les paramètres dans les pipelines classiques, consultez Paramètres de processus (classique).

Les paramètres doivent contenir un nom et un type de données. Les paramètres ne peuvent pas être facultatifs. Une valeur par défaut doit être affectée dans votre fichier YAML ou lorsque vous exécutez votre pipeline. Si vous n’affectez pas de valeur par défaut ou si vous ne définissez pas default sur false, la première valeur disponible est utilisée.

Utilisez templateContext pour 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.

Utiliser des paramètres dans les pipelines

Définissez les paramètres de runtime au début d’un fichier YAML.

Cet exemple de pipeline inclut un paramètre image avec trois agents hébergés en tant qu’options string. Dans la section des travaux, la valeur pool spécifie l’agent à partir du paramètre utilisé pour exécuter le travail. trigger est défini sur « none » afin que vous puissiez sélectionner la valeur de image lorsque vous déclenchez manuellement l’exécution de votre pipeline.

parameters:
- name: image
  displayName: Pool Image
  type: string
  default: ubuntu-latest
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest

trigger: none

jobs:
- job: build
  displayName: build
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber) with ${{ parameters.image }}

Lorsque le pipeline s’exécute, vous sélectionnez l’image du pool. Si vous n’effectuez pas de sélection, l’option par défaut ubuntu-latest est utilisée.

Paramètres de runtime

Utiliser des conditions avec des paramètres

Vous pouvez également utiliser des paramètres dans le cadre de la logique conditionnelle. Avec des conditions, une partie d’un fichier YAML s’exécute si elle répond aux critères if.

Utiliser des paramètres pour déterminer les étapes qui s’exécutent

Ce pipeline ajoute un deuxième paramètre booléen, test, qui peut être utilisé pour déterminer si des tests sont exécutés ou non dans le pipeline. Lorsque la valeur de test est true, l’étape qui génère l’exécution de tous les tests s’exécute.

parameters:
- name: image
  displayName: Pool Image
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest
- name: test
  displayName: Run Tests?
  type: boolean
  default: false

trigger: none

jobs:
- job: build
  displayName: Build and Test
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber)
  - ${{ if eq(parameters.test, true) }}:
    - script: echo "Running all the tests"

Utiliser des paramètres pour définir la configuration utilisée

Vous pouvez également utiliser des paramètres pour définir le travail qui s’exécute. Dans cet exemple, différentes architectures sont générées en fonction de la valeur du paramètre config, qui est un type string. Par défaut, les architectures x86 et x64 sont générées.

parameters:
- name: configs
  type: string
  default: 'x86,x64'

trigger: none

jobs:
- ${{ if contains(parameters.configs, 'x86') }}:
  - job: x86
    steps:
    - script: echo Building x86...
- ${{ if contains(parameters.configs, 'x64') }}:
  - job: x64
    steps:
    - script: echo Building x64...
- ${{ if contains(parameters.configs, 'arm') }}:
  - job: arm
    steps:
    - script: echo Building arm...

Exclure un index de manière sélective

Vous pouvez également utiliser des paramètres pour déterminer si un index s’exécute. Dans cet exemple, il existe un pipeline avec quatre index et des travaux différents pour chaque index. L’index Test de performances s’exécute si le paramètre runPerfTests a la valeur true. La valeur par défaut de runPerfTests est false. Par conséquent, sans aucune mise à jour, seuls trois des quatre index s’exécutent.

parameters:
- name: runPerfTests
  type: boolean
  default: false

trigger: none

stages:
- stage: Build
  displayName: Build
  jobs:
  - job: Build
    steps:
    - script: echo running Build


- stage: UnitTest
  displayName: Unit Test
  dependsOn: Build
  jobs:
  - job: UnitTest
    steps:
    - script: echo running UnitTest


- ${{ if eq(parameters.runPerfTests, true) }}:
  - stage: PerfTest
    displayName: Performance Test
    dependsOn: Build
    jobs:
    - job: PerfTest
      steps:
      - script: echo running PerfTest


- stage: Deploy
  displayName: Deploy
  dependsOn: UnitTest
  jobs:
  - job: Deploy
    steps:
    - script: echo running UnitTest

Exécuter en boucle des paramètres

Vous pouvez également exécuter en boucle vos paramètres de chaîne, de nombre et booléens.

Script
PowerShell

Dans cet exemple, vous exécutez en boucle des paramètres et imprimez le nom et la valeur de chaque paramètre. Il existe quatre paramètres différents et chacun représente un type différent. myStringName est une chaîne à une seule ligne. myMultiString est une chaîne à plusieurs lignes. myNumber is a number. myBoolean est une valeur booléenne. Dans la section des étapes, les tâches de script génèrent la clé et la valeur de chaque paramètre.

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true

steps: 
- ${{ each parameter in parameters }}:
  - script: echo ${{ parameter.Key }} 
  - script: echo ${{ parameter.Value }}

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

Dans cet exemple, vous exécutez en boucle des paramètres et imprimez le nom et la valeur de chaque paramètre. Il existe quatre paramètres différents et chacun représente un type différent. myStringName est une chaîne à une seule ligne. myMultiString est une chaîne à plusieurs lignes. myNumber is a number. myBoolean est une valeur booléenne. Dans la section des étapes, vous exécutez en boucle les paramètres d’une tâche PowerShell et définissez chaque paramètre en tant que variable d’environnement.

# start.yaml

parameters:
- name: myStringName
  type: string
  default: a string value
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true

steps: 
  - task: PowerShell@2
    env:
      ${{ each parameter in parameters }}:
        ${{ parameter.Key }}: ${{ parameter.Value }}
    inputs:
      filePath: test_script.ps1
      pwsh: true

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

# test_script.ps1

Write-Host "Hello, World!"
Write-Host $env:myStringName

Rechercher un objet de paramètre vide

Vous pouvez utiliser l’expression length() pour vérifier si un paramètre d’objet n’a pas de valeur.

parameters:
- name: foo
  type: object
  default: []

steps:
- checkout: none
- ${{ if eq(length(parameters.foo), 0) }}:
  - script: echo Foo is empty
    displayName: Foo is empty

Inclure dynamiquement une liste d’étapes avec le paramètre stepList

Dans cet exemple, le type de paramètre stepList est utilisé pour inclure dynamiquement une liste d’étapes dans le processus de génération.

Le pipeline principal (azure-pipelines.yml) définit deux travaux : générer et déployer.
Le travail de génération utilise un modèle (build.yml) et transmet une liste de tâches de génération à l’aide du paramètres stepList.
Le modèle build.yml inclut dynamiquement les étapes définies dans le paramètre build_tasks.

#azure-pipelines.yml

trigger:
- main

jobs:
  - job: build
    displayName: 'Build .NET Core Application'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - checkout: self

      - template: build.yml
        parameters:
          build_tasks:
            - task: DotNetCoreCLI@2
              displayName: 'Restore'
              inputs:
                command: 'restore'
                projects: '**/*.csproj'  

            - task: DotNetCoreCLI@2
              displayName: 'Build'
              inputs:
                command: 'build'
                arguments: '--no-restore'
                projects: '**/*.csproj' 

  - job: deploy
    displayName: 'Pack for Azure App Service deployment'
    dependsOn: build
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - download: current
        artifact: drop

Le modèle build.yml :

Définit le paramètre build_tasks avec le type stepList et une liste vide par défaut.
Définit le SDK .NET Core sur 6.x.
Itère chaque étape dans le paramètre build_tasks.
Exécute chaque étape définie dans la liste build_tasks.

#build.yml

parameters:
  - name: build_tasks
    type: stepList
    default: []

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '6.x'

  - ${{ each step in parameters.build_tasks }}:
      - ${{ step }}

  - task: DotNetCoreCLI@2
    displayName: 'Publish'
    inputs:
      command: 'publish'
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
      projects: '**/*.csproj'

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Artifact'
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'

Types de données de paramètre

Type de données	Notes
`string`	string
`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`	un seul travail de déploiement
`deploymentList`	séquence de travaux de déploiement
`stage`	une seule phase
`stageList`	séquence d’index

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

Partager via

Paramètres de runtime

Utiliser des paramètres dans les pipelines

Utiliser des conditions avec des paramètres

Utiliser des paramètres pour déterminer les étapes qui s’exécutent

Utiliser des paramètres pour définir la configuration utilisée

Exclure un index de manière sélective

Exécuter en boucle des paramètres

Rechercher un objet de paramètre vide

Inclure dynamiquement une liste d’étapes avec le paramètre stepList

Types de données de paramètre

Commentaires

Ressources supplémentaires