Parámetros de plantilla

Puede especificar parámetros y sus tipos de datos en una plantilla y hacer referencia a esos parámetros en una canalización. Con templateContext, también puede pasar propiedades a fases, pasos y trabajos que se usan como parámetros en una plantilla.

También puede usar parámetros fuera de las plantillas. Solo puede usar literales para los valores predeterminados del parámetro. Más información sobre los parámetros del esquema de YAML.

Pasar parámetros

Los parámetros deben incluir un nombre y un tipo de datos. En azure-pipelines.yml, si el parámetro yesNo se establece en un valor booleano, la compilación se realiza correctamente. Si yesNo se establece en una cadena como apples, se produce un error en la compilación.

# 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

Uso de templateContext para pasar propiedades a plantillas

Puede usar templateContext para pasar más propiedades a fases, pasos y trabajos que se usan como parámetros en una plantilla. En concreto, puede especificar templateContext dentro del tipo de datos de parámetro jobList, deploymentListo stageList.

templateContext facilita la configuración de entornos al procesar cada trabajo. Al agrupar un trabajo y su objeto de propiedades de entorno, templateContext ayuda a crear yaML más fácil de mantener y comprender.

En este ejemplo, el parámetro testSet de testing-template.yml tiene el tipo jobList de datos. La plantilla testing-template.yml crea una variable testJob con la palabra clave each. A continuación, la plantilla hace referencia a testJob.templateContext.expectedHTTPResponseCode, que se establece en azure-pipeline.yml y se pasa a la plantilla.

Cuando el código de respuesta es 200, la plantilla realiza una solicitud REST. Cuando el código de respuesta es 500, la plantilla genera todas las variables de entorno para la depuración.

templateContext puede contener propiedades.

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

Parámetros para seleccionar una plantilla en tiempo de ejecución

Puede llamar a diferentes plantillas de una canalización YAML en función de una condición. En este ejemplo, el YAML experimental.yml se ejecuta cuando el parámetro experimentalTemplate es 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

Tipos de datos de parámetro

Los steptipos de datos , stepList, jobjobList, deploymentdeploymentListstage, stringList, y stageList usan el formato de esquema YAML estándar. En este ejemplo se incluyen string, number, boolean, object, step y 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}}

Iteración a través de parámetros y sus tipos de datos

Azure Pipelines permite recorrer en iteración parámetros de varios tipos de datos, como cadenas, objetos, números y booleanos. Esta flexibilidad permite el comportamiento dinámico de la canalización en función de los valores de parámetro. A continuación se muestran ejemplos que muestran cómo recorrer en iteración parámetros y controlar diferentes tipos de datos.

Iteración mediante parámetros simples

Puede recorrer parámetros simples como cadenas, números y booleanos. En este ejemplo, la canalización recorre en iteración una lista de parámetros e imprime sus nombres y valores.

# 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

Iteración a través de objetos

Los objetos permiten definir estructuras de parámetro complejas, como elementos anidados. Puede recorrer en iteración los objetos para acceder a sus claves y valores o propiedades anidadas.

Ejemplo: Iteración mediante claves de objeto y valores

El siguiente archivo de plantilla define el myObject parámetro como un objeto con pares clave-valor predeterminados. El trabajo recorre en iteración las claves e imprime sus valores.

# 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 canalización invalida los valores predeterminados de myObject con valores personalizados.

# azure-pipelines.yml

trigger:
- main

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

Ejemplo: Iteración a través de objetos anidados

La plantilla define un listOfFruits parámetro que contiene objetos con matrices anidadas y, a continuación, usa bucles anidados para procesar cada fruta y sus colores asociados.

# 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

El archivo de canalización muestra cómo invalidar los valores predeterminados con datos de fruta personalizados.

# File: azure-pipelines.yml

trigger:
- main

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

Incluir dinámicamente una lista de pasos con el parámetro stepList

En este ejemplo, el tipo de parámetro stepList se usa para incluir dinámicamente una lista de pasos en el proceso de compilación.

• La canalización principal (azure-pipelines.yml) define dos trabajos: compilación e implementación.
• El trabajo de compilación usa una plantilla (build.yml) y pasa una lista de tareas de compilación mediante el parámetro stepList.
• La plantilla build.yml incluye dinámicamente los pasos definidos en el parámetro 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

La plantilla build.yml:

• Define el parámetro build_tasks con el tipo stepList y una lista vacía predeterminada.
• Establece el SDK de .NET Core en 8.x.
• Recorre en iteración cada paso del parámetro build_tasks.
• Ejecuta cada paso definido en la lista 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'