Parametri del modello

È possibile specificare i parametri e i relativi tipi di dati in un modello e fare riferimento a tali parametri in una pipeline. Con templateContext è anche possibile passare proprietà a fasi, passaggi e processi usati come parametri in un modello.

È anche possibile usare parametri esterni ai modelli. È possibile usare valori letterali solo per i valori predefiniti dei parametri. Altre informazioni sui parametri nello schema YAML.

Passaggio dei parametri

I parametri devono includere un nome e un tipo di dati. In azure-pipelines.yml, se il parametro yesNo è impostato su un valore booleano, la compilazione ha esito positivo. Se yesNo è impostato su una stringa come apples, la compilazione non riesce.

# 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

Usare templateContext per passare le proprietà ai modelli

È possibile usare templateContext per passare più proprietà a fasi, passaggi e processi usati come parametri in un modello. In particolare, è possibile specificare templateContext all'interno del tipo di dati del parametro jobList, deploymentList o stageList.

templateContext semplifica la configurazione degli ambienti durante l'elaborazione di ogni processo. Raggruppando un processo e l'oggetto proprietà dell'ambiente, templateContext è possibile creare un file YAML più gestibile e più facile da comprendere.

In questo esempio il parametro testSet in testing-template.yml ha il tipo di jobListdati . Il modello testing-template.yml crea una nuova variabile testJob usando la parola chiave each. Il modello fa quindi riferimento a testJob.templateContext.expectedHTTPResponseCode, che viene impostato in azure-pipeline.yml e passato al modello.

Quando il codice di risposta è 200, il modello effettua una richiesta REST. Quando il codice di risposta è 500, il modello restituisce tutte le variabili di ambiente per il debug.

templateContext può contenere proprietà.

#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" 

Parametri per selezionare un modello in fase di esecuzione

È possibile chiamare modelli diversi da un YAML della pipeline a seconda di una condizione. In questo esempio, YAML experimental.yml viene eseguito quando il parametro experimentalTemplate è 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

Tipi di dati dei parametri

I steptipi di dati , stepListjob, jobListdeploymentdeploymentListstagestringListe stageList usano tutti il formato di schema YAML standard. Questo esempio include string, number, booleanobject, step, e 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', 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}}

Iterazione dei parametri e dei relativi tipi di dati

Azure Pipelines consente di scorrere i parametri di vari tipi di dati, ad esempio stringhe, oggetti, numeri e valori booleani. Questa flessibilità consente il comportamento della pipeline dinamica in base ai valori dei parametri. Di seguito sono riportati esempi che illustrano come scorrere i parametri e gestire tipi di dati diversi.

Iterazione tramite parametri semplici

È possibile scorrere in ciclo parametri semplici come stringhe, numeri e booleani. In questo esempio la pipeline scorre un elenco di parametri e stampa i relativi nomi e valori.

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- name: myNumber
  type: number
  default: 2
- 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

Iterazione degli oggetti

Gli oggetti consentono di definire strutture di parametri complesse, ad esempio elementi annidati. È possibile scorrere gli oggetti per accedere alle chiavi e ai valori o alle proprietà annidate.

Esempio: Iterazione tra chiavi oggetto e valori

Il file di modello seguente definisce il myObject parametro come oggetto con coppie chiave-valore predefinite. Il processo scorre le chiavi e ne stampa i valori.

# object-keys-template.yml

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'

La pipeline esegue l'override dei valori predefiniti di myObject con valori personalizzati.

# azure-pipelines.yml

trigger:
- main

extends:
  template: object-keys-template.yml
  parameters:
    myObject:
      key1: 'customValue1'
      key2: 'customValue2'
      key3: 'customValue3'

Esempio: Iterazione tramite oggetti annidati

Il modello definisce un listOfFruits parametro contenente oggetti con matrici annidate, quindi usa cicli annidati per elaborare ogni frutto e i relativi colori associati.

# File: nested-objects-template.yml

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

Il file della pipeline mostra come eseguire l'override dei valori predefiniti con dati di frutta personalizzati.

# File: azure-pipelines.yml

trigger:
- main

extends:
  template: nested-objects-template.yml
  parameters:
    listOfFruits:
    - fruitName: 'banana'
      colors: ['yellow']
    - fruitName: 'grape'
      colors: ['purple', 'green']

Includere in modo dinamico un elenco di passaggi con il parametro stepList

In questo esempio, il stepList tipo di parametro viene usato per includere in modo dinamico un elenco di passaggi nel processo di compilazione.

• La pipeline principale (azure-pipelines.yml) definisce due processi: compilazione e distribuzione.
• Il processo di compilazione usa un modello (build.yml) e passa un elenco di attività di compilazione usando il stepList parametro .
• Il build.yml modello include dinamicamente i passaggi definiti nel build_tasks parametro .

#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

Il build.yml modello:

• Definisce il parametro build_tasks con il tipo stepList e un elenco vuoto predefinito.
• Imposta .NET Core SDK su 8.x.
• Scorre ogni fase del parametro build_tasks.
• Esegue ogni passaggio definito nell'elenco build_tasks .

#build.yml

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

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '8.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'