Parámetros en tiempo de ejecución

Artículo
11/30/2021
6 minutos para leer

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

Proporcionar valores diferentes a 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 parameters sección de un YAML define qué parámetros están disponibles.

Los parámetros solo están disponibles en el momento del análisis de plantillas. Los parámetros se expanden justo antes de que se ejecute la canalización para que los valores entre ellos ${{ }} se reemplazan 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 ver 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 un valor predeterminado o se establece en , se usará el defaultfalse primer valor disponible.

Uso de parámetros en canalizaciones

Establezca los parámetros en tiempo de ejecución al principio de un YAML. Esta canalización de ejemplo acepta el valor de image y, a continuación, genera el valor en el trabajo. se establece en none para que pueda seleccionar el valor de triggerimage cuando desencadene manualmente la ejecución de la canalización.

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 una selección, se usa la opción ubuntu-latest predeterminada.

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 solo se ejecutará si cumple los if criterios.

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

Esta canalización solo ejecuta un paso cuando el parámetro test booleano es true.

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 usa

También puede usar parámetros para establecer qué trabajo se ejecuta. En este ejemplo, se ejecuta un trabajo diferente en función del valor de config .

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 selectivamente una fase

También puede usar parámetros para establecer si se ejecuta una fase. En este ejemplo, la fase Prueba de rendimiento se ejecuta si el parámetro runPerfTests es true.

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 en bucle los parámetros

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

Script
PowerShell

En este ejemplo, recorrerá en bucle los parámetros e imprimirá cada nombre y valor de 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

Puede 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()length() 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ámetros

Tipo de datos	Notas
`string`	string
`number`	puede restringirse a ; de lo contrario, se acepta cualquier `values:` cadena de tipo número.
`boolean`	`true` o `false`
`object`	cualquier estructura YAML
`step`	un solo paso
`stepList`	secuencia de pasos
`job`	un único 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 step, 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 }}

Preguntas más frecuentes

¿Cómo puedo usar variables dentro de plantillas?

Hay ocasiones en las que puede ser útil establecer parámetros en valores basados en variables. Los parámetros se expanden al principio del procesamiento de una ejecución de canalización, por lo que no todas las variables estarán disponibles. Para ver qué variables predefinidas están disponibles en las plantillas, vea Usar variables predefinidas.

En este ejemplo, las variables predefinidas Build.SourceBranch y se usan en condiciones en Build.Reason template.yml.

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: template.yml

# File: template.yml
steps:
- script: echo Build.SourceBranch = $(Build.SourceBranch) # outputs refs/heads/main
- script: echo Build.Reason = $(Build.Reason) # outputs IndividualCI
- ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}: 
  - script: echo I run only if Build.SourceBranch = refs/heads/main 
- ${{ if eq(variables['Build.Reason'], 'IndividualCI') }}: 
  - script: echo I run only if Build.Reason = IndividualCI 
- script: echo I run after the conditions