Parámetros en tiempo de ejecución

Artículo
07/03/2023

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
Tipos de parámetros de control, intervalos permitidos y valores predeterminados
Selección dinámica de 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 }}

Cuando se ejecute la canalización, seleccione la imagen de grupo. Si no realiza ninguna selección, se usará la opción predeterminada, ubuntu-latest.

parámetros en tiempo de ejecución

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

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ónlength() 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

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`	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
  type: string
  default: a string
- 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
- name: myObject
  type: object
  default:
    foo: FOO
    bar: BAR
    things:
    - one
    - two
    - three
    nested:
      one: apple
      two: pear
      count: 3
- name: myStep
  type: step
  default:
    script: echo my step
- name: mySteplist
  type: stepList
  default:
    - script: echo step one
    - script: echo step two

trigger: none

jobs: 
- job: stepList
  steps: ${{ parameters.mySteplist }}
- job: myStep
  steps:
    - ${{ parameters.myStep }}