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 contener un nombre y un tipo de datos. En azure-pipelines.yml
, cuando el parámetro yesNo
se establece en un valor booleano, la compilación se realiza correctamente. Cuando 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
, deploymentList
o stageList
.
Puede usar templateContext
para facilitar la configuración de entornos al procesar cada trabajo. Al agrupar un trabajo y su objeto de propiedades de entorno, templateContext
puede ayudarle a tener más fácil de mantener y comprender el YAML.
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 }}:
- ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 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) }}:
- job:
steps:
- powershell: 'Get-ChildItem -Path Env:\'
- ${{ testJob.steps }}
#azure-pipeline.yml
trigger: none
pool:
vmImage: ubuntu-latest
extends:
template: testing-template.yml
parameters:
testSet:
- job: positive_test
templateContext:
expectedHTTPResponseCode: 200
steps:
- script: echo "Run positive test"
- job: negative_test
templateContext:
expectedHTTPResponseCode: 500
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) }}:
- template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:
- template: stable.yml
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
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 }}
Puede recorrer en iteración un objeto e imprimir cada cadena del objeto .
parameters:
- name: listOfStrings
type: object
default:
- one
- two
steps:
- ${{ each value in parameters.listOfStrings }}:
- script: echo ${{ value }}
Además, puede recorrer en iteración los elementos anidados dentro de un objeto.
parameters:
- name: listOfFruits
type: object
default:
- fruitName: 'apple'
colors: ['red','green']
- fruitName: 'lemon'
colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
- ${{ each fruitColor in fruit.colors}} :
- script: echo ${{ fruit.fruitName}} ${{ fruitColor }}
Parámetros obligatorios
Puede agregar un paso de validación al principio de la plantilla para comprobar los parámetros que necesita.
Este es un ejemplo que comprueba el parámetro solution
mediante Bash (lo que permite que funcione en cualquier plataforma):
# File: steps/msbuild.yml
parameters:
- name: 'solution'
default: ''
type: string
steps:
- bash: |
if [ -z "$SOLUTION" ]; then
echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
echo "##vso[task.complete result=Failed;]"
fi
env:
SOLUTION: ${{ parameters.solution }}
displayName: Check for required parameters
- task: msbuild@1
inputs:
solution: ${{ parameters.solution }}
- task: vstest@2
inputs:
solution: ${{ parameters.solution }}
Para mostrar que se produce un error en la plantilla si falta el parámetro necesario:
# File: azure-pipelines.yml
# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml
Puede pasar parámetros a plantillas.
La sección parameters
define qué parámetros están disponibles en la plantilla y sus valores predeterminados.
Las plantillas se expanden justo antes de que se ejecute la canalización para que los valores rodeados por ${{ }}
se reemplacen por los parámetros que recibe de la canalización envolvente. Como resultado, solo se pueden usar variables predefinidas en parámetros.
Para usar parámetros en varias canalizaciones, consulte cómo crear un grupo de variables.
Plantillas de trabajo, fases y pasos con parámetros
# File: templates/npm-with-params.yml
parameters:
name: '' # defaults for any parameters that aren't specified
vmImage: ''
jobs:
- job: ${{ parameters.name }}
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: npm install
- script: npm test
Al consumir la plantilla en la canalización, especifique valores para los parámetros de plantilla.
# File: azure-pipelines.yml
jobs:
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Linux
vmImage: 'ubuntu-latest'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: macOS
vmImage: 'macOS-10.13'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Windows
vmImage: 'windows-latest'
También puede usar parámetros con plantillas de paso o fase. Por ejemplo, pasos con parámetros:
# File: templates/steps-with-params.yml
parameters:
runExtendedTests: 'false' # defaults for any parameters that aren't specified
steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, 'true') }}:
- script: npm test --extended
Al consumir la plantilla en la canalización, especifique valores para los parámetros de plantilla.
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
Nota:
Los parámetros escalares siempre se tratan como cadenas.
Por ejemplo, eq(parameters['myparam'], true)
casi siempre devolverá true
, incluso si el parámetro myparam
es la palabra false
.
Las cadenas no vacías se convierten en true
en un contexto booleano.
Esa expresión se podría reescribir para comparar explícitamente cadenas: eq(parameters['myparam'], 'true')
.
Los parámetros no se limitan a las cadenas escalares. Siempre que el lugar donde se expanda el parámetro espera una asignación, el parámetro puede ser una asignación. Del mismo modo, se pueden pasar secuencias en las que se esperan secuencias. Por ejemplo:
# azure-pipelines.yml
jobs:
- template: process.yml
parameters:
pool: # this parameter is called `pool`
vmImage: ubuntu-latest # and it's a mapping rather than a string
# process.yml
parameters:
pool: {}
jobs:
- job: build
pool: ${{ parameters.pool }}