Parámetros en tiempo de ejecución

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

Los parámetros en tiempo de ejecución permiten tener más control sobre qué valores se pueden pasar a una canalización. Con los parámetros en tiempo de ejecución puede:

• Proporcionar valores diferentes en scripts y tareas en tiempo de ejecución
• Controlar los tipos de parámetros, los rangos permitidos y los valores predeterminados
• Seleccionar de forma dinámica trabajos y fases con expresiones de plantilla

Puede especificar parámetros en plantillas y en la canalización. Los parámetros tienen tipos de datos, como number y string, y se pueden restringir a un subconjunto de valores. La sección parameters de un YAML define qué parámetros están disponibles.

Los parámetros solo están disponibles en el tiempo de análisis de las plantillas. Los parámetros se expanden justo antes de que se ejecute la canalización para que los valores rodeados por ${{ }} se reemplacen por valores de parámetro. Use variables si necesita que los valores estén más disponibles durante la ejecución de la canalización.

Nota:

Esta guía no se aplica a las canalizaciones clásicas. Para conocer los parámetros de las canalizaciones clásicas, consulte Parámetros de proceso (clásico).

Los parámetros deben contener un nombre y un tipo de datos. Los parámetros no pueden ser opcionales. Se debe asignar un valor predeterminado en el archivo YAML o al ejecutar la canalización. Si no asigna ningún valor predeterminado o establece default en false, se usará el primer valor disponible.

Use templateContext para pasar propiedades adicionales a fases, pasos y trabajos que se usan como parámetros en una plantilla.

Uso de parámetros en las canalizaciones

Establezca los parámetros en tiempo de ejecución al principio de un YAML.

Esta canalización de ejemplo incluye un parámetro image con tres agentes hospedados como opciones string. En la sección Trabajos, el valor pool especifica el agente del parámetro usado para ejecutar el trabajo. trigger se establece en Ninguno para poder seleccionar el valor de image cuando desencadene manualmente la canalización para ejecutarla.

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 }}

En la página ejecuciones de canalización, seleccione Ejecutar canalización para ejecutar la canalización. Verá la opción para seleccionar la imagen de grupo. Si no realiza ninguna selección, se usará la opción predeterminada, ubuntu-latest. No tendrá la opción de seleccionar una imagen de grupo si ejecuta la canalización desde el editor de YAML.

Uso de condicionales con parámetros

También puede usar parámetros como parte de la lógica condicional. Con los condicionales, parte de un YAML se ejecuta si cumple los criterios if.

Uso de parámetros para determinar qué pasos se ejecutan

Esta canalización agrega un segundo parámetro booleano, test, que se puede usar para controlar si se deben ejecutar o no pruebas en la canalización. Cuando el valor de test es true, se ejecuta el paso que genera Ejecutando todas las pruebas.

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"

Uso de parámetros para establecer qué configuración se va a usar

También puede usar parámetros para establecer qué trabajo se va a ejecutar. En este ejemplo, las distintas arquitecturas se basan en el valor del parámetro config, que es un tipo string. De forma predeterminada, las arquitecturas x86 y x64 se compilan.

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...

Excluir una fase selectivamente

También puede usar parámetros para establecer si se ejecuta una fase. En este ejemplo, hay una canalización con cuatro fases y trabajos diferentes para cada fase. La fase Prueba de rendimiento se ejecuta si el parámetro runPerfTests es true. El valor predeterminado de runPerfTests es false, por lo que, sin actualizaciones, solo se ejecutarán tres de las cuatro fases.

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

Recorrer parámetros en bucle

También puede recorrer en bucle los parámetros de cadena, número y booleano.

Script

En este ejemplo recorrerá los parámetros e imprimirá el nombre y el valor de cada parámetro. Hay cuatro parámetros diferentes y cada uno representa un tipo diferente. myStringName es una cadena de una sola línea. myMultiString es una cadena multilínea. myNumber is a number. myBoolean es un valor booleano. En la sección Pasos, las tareas de script generan la clave y el valor de cada parámetro.

# 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

PowerShell

En este ejemplo recorrerá los parámetros e imprimirá el nombre y el valor de cada parámetro. Hay cuatro parámetros diferentes y cada uno representa un tipo diferente. myStringName es una cadena de una sola línea. myMultiString es una cadena multilínea. myNumber is a number. myBoolean es un valor booleano. En la sección Pasos recorrerá en bucle los parámetros de una tarea de PowerShell y establecerá cada parámetro como una variable de entorno.

# 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

Buscar un objeto de parámetro vacío

Puede usar la expresión length() para comprobar si un parámetro de objeto no tiene ningún valor.

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

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

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 6.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: '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'

Tipos de datos de parámetro

Tipo de datos	Notas
string	string
number	se puede restringir a values:; de lo contrario, se aceptará cualquier cadena de tipo numérico.
boolean	true o false
object	cualquier estructura YAML
step	un solo paso
stepList	secuencia de pasos
job	un solo trabajo
jobList	secuencia de trabajos
deployment	un único trabajo de implementación
deploymentList	secuencia de trabajos de implementación
stage	una sola fase
stageList	la secuencia de fases

Los tipos de datos stepList, job, jobList, deployment, deploymentList, stage 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'
  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