Uso de tipos de & plantilla

Las plantillas permiten definir contenido reutilizable, lógica y parámetros. Las plantillas funcionan de dos maneras. Puede insertar contenido reutilizable con una plantilla o puede usar una plantilla para controlar lo que se permite en una canalización. El segundo enfoque es útil para crear canalizaciones seguras con plantillas.

Si se usa una plantilla para incluir contenido, funciona como una directiva include en muchos lenguajes de programación. El contenido de un archivo se inserta en otro archivo. Cuando una plantilla controla lo que se permite en una canalización, la plantilla define la lógica que debe seguir otro archivo.

Use plantillas para definir la lógica una vez y volver a usarla varias veces. Combinan el contenido de varios archivos YAML en una sola canalización. Puede pasar parámetros a una plantilla desde la canalización primaria.

Parámetros

Puede especificar parámetros y sus tipos de datos en una plantilla y pasar esos parámetros a una canalización. También puede usar parámetros fuera de las plantillas. Solo puede usar literales para los valores predeterminados de parámetro.

Pasar parámetros

Los parámetros deben contener un nombre y un tipo de datos. En azure-pipelines.yml , cuando el parámetro se establece en un valor yesNo booleano, la compilación se realiza correctamente. Cuando yesNo se establece en una cadena como , se produce un error en la apples 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:
- master

extends:
  template: simple-param.yml
  parameters:
      yesNo: false # set to a non-boolean value to have the build fail

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

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

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

Extensión desde una plantilla

Para aumentar la seguridad, puede aplicar que una canalización se extienda desde una plantilla determinada. El archivo start.yml define el parámetro , que se usa en la canalización buildStepsazure-pipelines.yml . En , si se pasa un elemento con un paso de script, se rechaza y start.yml se produce un error en la buildStep compilación de la canalización. Al extender desde una plantilla, puede aumentar la seguridad agregando una aprobación de plantilla necesaria.

# File: start.yml
parameters:
- name: buildSteps # the name of the parameter is buildSteps
  type: stepList # data type is StepList
  default: [] # default value of buildSteps
stages:
- stage: secure_buildstage
  pool:
    vmImage: vs2017-win2016
  jobs:
  - job: secure_buildjob
    steps:
    - script: echo This happens before code 
      displayName: 'Base: Pre-build'
    - script: echo Building
      displayName: 'Base: Build'

    - ${{ each step in parameters.buildSteps }}:
      - ${{ each pair in step }}:
          ${{ if ne(pair.value, 'CmdLine@2') }}:
            ${{ pair.key }}: ${{ pair.value }}       
          ${{ if eq(pair.value, 'CmdLine@2') }}: 
            '${{ pair.value }}': error         

    - script: echo This happens after code
      displayName: 'Base: Signing'

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

extends:
  template: start.yml
  parameters:
    buildSteps:  
      - bash: echo Test #Passes
        displayName: succeed
      - bash: echo "Test"
        displayName: succeed
      - task: CmdLine@2
        displayName: Test 3 - Will Fail
        inputs:
          script: echo "Script Test"

Extensión desde una plantilla con recursos

También puede usar para extends extender desde una plantilla de la canalización de Azure que contiene recursos.

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

extends:
  template: resource-template.yml

# File: resource-template.yml
resources:
  pipelines:
  - pipeline: my-pipeline 
    source: sourcePipeline

steps:
 - script: echo "Testing resource template"

Inserción de una plantilla

Puede copiar contenido de un YAML y reutilizarlo en otro YAML. Copiar contenido de un YAML a otro le ahorra tener que incluir manualmente la misma lógica en varios lugares. La include-npm-steps.yml plantilla de archivo contiene pasos que se reutilizan en azure-pipelines.yml .

Los archivos de plantilla deben existir en el sistema de archivos al principio de una ejecución de canalización. No se puede hacer referencia a plantillas en un artefacto.

# File: templates/include-npm-steps.yml

steps:
- script: npm install
- script: yarn install
- script: npm run compile

# File: azure-pipelines.yml

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - template: templates/include-npm-steps.yml  # Template reference
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - template: templates/include-npm-steps.yml  # Template reference

Reutilización de pasos

Puede insertar una plantilla para reutilizar uno o varios pasos en varios trabajos. Además de los pasos de la plantilla, cada trabajo puede definir más pasos.

# File: templates/npm-steps.yml
steps:
- script: npm install
- script: npm test

# File: azure-pipelines.yml

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - template: templates/npm-steps.yml  # Template reference

- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - template: templates/npm-steps.yml  # Template reference

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo This script runs before the template's steps, only on Windows.
  - template: templates/npm-steps.yml  # Template reference
  - script: echo This step runs after the template's steps.

Reutilización de trabajos

Al igual que los pasos, los trabajos se pueden reutilizar con plantillas.

# File: templates/jobs.yml
jobs:
- job: Ubuntu
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello Ubuntu"

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - bash: echo "Hello Windows"

# File: azure-pipelines.yml

jobs:
- template: templates/jobs.yml  # Template reference

Cuando trabaje con varios trabajos, recuerde quitar el nombre del trabajo en el archivo de plantilla para evitar conflictos.

# File: templates/jobs.yml
jobs:
- job: 
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello Ubuntu"

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - bash: echo "Hello Windows"

# File: azure-pipelines.yml

jobs:
- template: templates/jobs.yml  # Template reference
- template: templates/jobs.yml  # Template reference
- template: templates/jobs.yml  # Template reference

Reutilización de fases

Las fases también se pueden reutilizar con plantillas.

# File: templates/stages1.yml
stages:
- stage: Angular
  jobs:
  - job: angularinstall
    steps:
    - script: npm install angular

# File: templates/stages2.yml
stages:
- stage: Build
  jobs:
  - job: build
    steps:
    - script: npm run build

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

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: Install
  jobs: 
  - job: npminstall
    steps:
    - task: Npm@1
      inputs:
        command: 'install'
- template: templates/stages1.yml
- template: templates/stages2.yml

Plantillas de trabajo, fase y paso con parámetros

# File: templates/npm-with-params.yml

parameters:
- name: name  # defaults for any parameters that aren't specified
  default: ''
- name: vmImage
  default: ''

jobs:
- job: ${{ parameters.name }}
  pool: 
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

Cuando consuma 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-latest'

- 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:
- name: 'runExtendedTests'  # defaults for any parameters that aren't specified
  type: boolean
  default: false

steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, true) }}:
  - script: npm test --extended

Cuando consuma 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'

Los parámetros no se limitan a cadenas escalares. Vea la lista de tipos de datos. Por ejemplo, con el object tipo :

# 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:
- name: 'pool'
  type: object
  default: {}

jobs:
- job: build
  pool: ${{ parameters.pool }}

Reutilización de variables

Las variables se pueden definir en un YAML e incluirse en otra plantilla. Esto podría ser útil si desea almacenar todas las variables en un archivo. Si usa una plantilla para incluir variables en una canalización, la plantilla incluida solo se puede usar para definir variables. Puede usar pasos y una lógica más compleja al extender desde una plantilla. Use parámetros en lugar de variables cuando desee restringir el tipo.

En este ejemplo, la variable favoriteVeggie se incluye en azure-pipelines.yml .

# File: vars.yml
variables:
  favoriteVeggie: 'brussels sprouts'

# File: azure-pipelines.yml

variables:
- template: vars.yml  # Template reference

steps:
- script: echo My favorite vegetable is ${{ variables.favoriteVeggie }}.

Rutas de acceso de plantilla de referencia

Las rutas de acceso de plantilla deben ser relativas al archivo que realiza la inclusión. Este es un ejemplo de jerarquía anidada.

|
+-- fileA.yml
|
+-- dir1/
     |
     +-- fileB.yml
     |
     +-- dir2/
          |
          +-- fileC.yml

A continuación, fileA.yml en puede hacer referencia a y de esta fileB.ymlfileC.yml forma.

steps:
- template: dir1/fileB.yml
- template: dir1/dir2/fileC.yml

Si fileC.yml es el punto de partida, puede incluir y de esta fileA.ymlfileB.yml forma.

steps:
- template: ../../fileA.yml
- template: ../fileB.yml

Cuando fileB.yml es el punto de partida, puede incluir y de esta fileA.ymlfileC.yml forma.

steps:
- template: ../fileA.yml
- template: dir2/fileC.yml

Uso de otros repositorios

Puede mantener las plantillas en otros repositorios. Por ejemplo, supongamos que tiene una canalización principal que quiere que usen todas las canalizaciones de la aplicación. Puede colocar la plantilla en un repositorio principal y, a continuación, hacer referencia a ella desde cada uno de los repositorios de la aplicación:

# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
- name: 'vmImage'
  default: 'ubuntu 16.04'
  type: string

jobs:
- job: Build
  pool:
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

Ahora puede reutilizar esta plantilla en varias canalizaciones. Use la resources especificación para proporcionar la ubicación del repositorio principal. Cuando haga referencia al repositorio principal, use @ y el nombre que le agregó en resources .

# Repo: Contoso/LinuxProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates

jobs:
- template: common.yml@templates  # Template reference

# Repo: Contoso/WindowsProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates
      ref: refs/tags/v1.0 # optional ref to pin to

jobs:
- template: common.yml@templates  # Template reference
  parameters:
    vmImage: 'windows-latest'

Para type: github , es como en los ejemplos name<identity>/<repo> anteriores. Para type: git (Azure Repos), name es <project>/<repo> . Si ese proyecto está en una organización Azure DevOps independiente, deberá configurar una conexión de servicio de tipo con acceso al proyecto e incluirla en YAML:

resources:
  repositories:
  - repository: templates
    name: Contoso/BuildTemplates
    endpoint: myServiceConnection # Azure DevOps service connection
jobs:
- template: common.yml@templates

Los repositorios se resuelven solo una vez, cuando se inicia la canalización. Después de eso, se usa el mismo recurso mientras dure la canalización. Solo se usan los archivos de plantilla. Una vez que las plantillas se expanden por completo, la canalización final se ejecuta como si se hubiera definido completamente en el repositorio de origen. Esto significa que no puede usar scripts del repositorio de plantillas en la canalización.

Si desea usar una versión determinada y fija de la plantilla, asegúrese de anclar a ref . son refs ramas ( refs/heads/<name> ) o etiquetas ( refs/tags/<name> ). Si desea anclar una confirmación específica, cree primero una etiqueta que apunte a esa confirmación y, a continuación, anclarla a esa etiqueta.

También puede usar para hacer referencia al repositorio donde se encontró @self la canalización principal. Esto es conveniente para su uso en plantillas si desea volver a hacer referencia al contenido en el repositorio de la canalización extends de extensión. Por ejemplo:

# Repo: Contoso/Central
# File: template.yml
jobs:
- job: PreBuild
  steps: []

  # Template reference to the repo where this template was
  # included from - consumers of the template are expected
  # to provide a "BuildJobs.yml"
- template: BuildJobs.yml@self

- job: PostBuild
  steps: []

# Repo: Contoso/MyProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: git
      name: Contoso/Central

extends:
  template: template.yml@templates

# Repo: Contoso/MyProduct
# File: BuildJobs.yml
jobs:
- job: Build
  steps: []

Expresiones de plantilla

Use expresiones de plantilla para especificar cómo se resuelven dinámicamente los valores durante la inicialización de la canalización. Ajuste la expresión de plantilla dentro de esta sintaxis: ${{ }} .

Las expresiones de plantilla pueden expandir los parámetros de plantilla y también las variables. Puede usar parámetros para influir en cómo se expande una plantilla. El parameters objeto funciona como el objeto parameters una expresión. Solo se pueden usar variables predefinidas en expresiones de plantilla.

Por ejemplo, defina una plantilla:

# File: steps/msbuild.yml

parameters:
- name: 'solution'
  default: '**/*.sln'
  type: string

steps:
- task: msbuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}  # property dereference syntax

A continuación, haga referencia a la plantilla y pásese el parámetro solution opcional:

# File: azure-pipelines.yml

steps:
- template: steps/msbuild.yml
  parameters:
    solution: my.sln

Contexto

Dentro de una expresión de plantilla, tiene acceso al parameters contexto que contiene los valores de los parámetros pasados. Además, tiene acceso al contexto que contiene todas las variables especificadas en el archivo YAML más muchas de las variables predefinidas (anotadas en cada variables variable de ese tema). variables Lo más importante es que no tiene variables en tiempo de ejecución como las almacenadas en la canalización o dadas al iniciar una ejecución. La expansión de plantillas se produce muy pronto en la ejecución,por lo que esas variables no están disponibles.

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 mediante Bash (que le permite solution trabajar 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

Funciones de expresión de plantilla

Puede usar funciones generales en las plantillas. También puede usar algunas funciones de expresión de plantilla.

format

• Reemplazo de token de cadena simple
• Parámetros mínimos: 2. Parámetros máximos: N
• Ejemplo: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

• Se evalúa como el primer argumento de cadena no vacío y no nulo
• Parámetros mínimos: 2. Parámetros máximos: N
• Ejemplo:

parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

steps:
- script: echo ${{ coalesce(parameters.foo, parameters.bar, 'Nothing to see') }}

Inserción

Puede usar expresiones de plantilla para modificar la estructura de una canalización de YAML. Por ejemplo, para insertar en una secuencia:

# File: jobs/build.yml

parameters:
- name: 'preBuild'
  type: stepList
  default: []
- name: 'preTest'
  type: stepList
  default: []
- name: 'preSign'
  type: stepList
  default: []

jobs:
- job: Build
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: cred-scan
  - ${{ parameters.preBuild }}
  - task: msbuild@1
  - ${{ parameters.preTest }}
  - task: vstest@2
  - ${{ parameters.preSign }}
  - script: sign

# File: .vsts.ci.yml

jobs:
- template: jobs/build.yml
  parameters:
    preBuild:
    - script: echo hello from pre-build
    preTest:
    - script: echo hello from pre-test

Cuando se inserta una matriz en una matriz, la matriz anidada se aplana.

Para insertar en una asignación, use la propiedad especial ${{ insert }} .

# Default values
parameters:
- name: 'additionalVariables'
  type: object
  default: {}

jobs:
- job: build
  variables:
    configuration: debug
    arch: x86
    ${{ insert }}: ${{ parameters.additionalVariables }}
  steps:
  - task: msbuild@1
  - task: vstest@2

jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

Inserción condicional

Si desea insertar condicionalmente en una secuencia o una asignación en una plantilla, use inserciones y evaluación de expresiones. También puede usar instrucciones if fuera de las if siempre que use la sintaxis de plantilla.

Por ejemplo, para insertar en una secuencia en una plantilla:

# File: steps/build.yml

parameters:
- name: 'toolset'
  default: msbuild
  type: string
  values:
  - msbuild
  - dotnet

steps:
# msbuild
- ${{ if eq(parameters.toolset, 'msbuild') }}:
  - task: msbuild@1
  - task: vstest@2

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: dotnet@1
    inputs:
      command: build
  - task: dotnet@1
    inputs:
      command: test

# File: azure-pipelines.yml

steps:
- template: steps/build.yml
  parameters:
    toolset: dotnet

Por ejemplo, para insertar en una asignación en una plantilla:

# File: steps/build.yml

parameters:
- name: 'debug'
  type: boolean
  default: false

steps:
- script: tool
  env:
    ${{ if eq(parameters.debug, true) }}:
      TOOL_DEBUG: true
      TOOL_DEBUG_DIR: _dbg

steps:
- template: steps/build.yml
  parameters:
    debug: true

También puede usar la inserción condicional para las variables. En este ejemplo, start siempre imprime y solo imprime cuando la variable es igual a this is a testfootest .

variables:
  - name: foo
    value: test

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.foo, 'test') }}:
  - script: echo "this is a test" # runs when foo=test

Inserción iterativa

La each directiva permite la inserción iterativa basada en una secuencia YAML (matriz) o asignación (pares clave-valor).

Por ejemplo, puede encapsular los pasos de cada trabajo con otros pasos previos y posteriores:

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This will get sandwiched between SetupMyBuildTools and PublishMyTelemetry.
    - job: B
      steps:
      - script: echo So will this!

También puede manipular las propiedades de lo que está iterando. Por ejemplo, para agregar más dependencias:

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- job: SomeSpecialTool                # Run your special tool in its own job first
  steps:
  - task: RunSpecialTool@1
- ${{ each job in parameters.jobs }}: # Then do each job
  - ${{ each pair in job }}:          # Insert all properties other than "dependsOn"
      ${{ if ne(pair.key, 'dependsOn') }}:
        ${{ pair.key }}: ${{ pair.value }}
    dependsOn:                        # Inject dependency
    - SomeSpecialTool
    - ${{ if job.dependsOn }}:
      - ${{ job.dependsOn }}

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This job depends on SomeSpecialTool, even though it's not explicitly shown here.
    - job: B
      dependsOn:
      - A
      steps:
      - script: echo This job depends on both Job A and on SomeSpecialTool.

Escape de un valor

Si necesita escapar un valor que literalmente contiene ${{ , envolver el valor en una cadena de expresión. Por ejemplo, ${{ 'my${{value' }} o ${{ 'my${{value with a '' single quote too' }}.

Límites impuestos

Las plantillas y las expresiones de plantilla pueden provocar un crecimiento exponencial del tamaño y la complejidad de una canalización. Para ayudar a evitar el crecimiento en desuso, Azure Pipelines impone los límites siguientes:

• No se pueden incluir más de 100 archivos YAML independientes (directa o indirectamente)
• No más de 20 niveles de anidamiento de plantillas (plantillas incluidas otras plantillas)
• No se consumen más de 10 megabytes de memoria al analizar el YAML (en la práctica, suele estar entre 600 KB y 2 MB de YAML en disco, dependiendo de las características específicas usadas).

Parámetros de plantilla

Puede pasar parámetros a plantillas. La parameters sección 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 reemplace por los parámetros que recibe de la ${{ }} canalización de entrada. Como resultado, solo se pueden usar variables predefinidas en los parámetros.

Para usar parámetros en varias canalizaciones, vea cómo crear un grupo de variables.

Plantillas de trabajo, fase y paso 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

Cuando consuma 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

Cuando consuma 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'

Los parámetros no se limitan a cadenas escalares. Siempre que el lugar donde se expanda el parámetro espere una asignación, el parámetro puede ser una asignación. Del mismo modo, se pueden pasar secuencias donde 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 }}

Uso de otros repositorios

Puede mantener las plantillas en otros repositorios. Por ejemplo, supongamos que tiene una canalización principal que quiere que usen todas las canalizaciones de aplicaciones. Puede colocar la plantilla en un repositorio principal y, a continuación, hacer referencia a ella desde cada uno de los repositorios de aplicaciones:

# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
  vmImage: 'ubuntu 16.04'

jobs:
- job: Build
  pool:
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

Ahora puede reutilizar esta plantilla en varias canalizaciones. Use la resources especificación para proporcionar la ubicación del repositorio principal. Cuando haga referencia al repositorio principal, use @ y el nombre que le agregó en resources .

# Repo: Contoso/LinuxProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates

jobs:
- template: common.yml@templates  # Template reference

# Repo: Contoso/WindowsProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates
      ref: refs/tags/v1.0 # optional ref to pin to

jobs:
- template: common.yml@templates  # Template reference
  parameters:
    vmImage: 'windows-latest'

Para type: github , es como en los ejemplos name<identity>/<repo> anteriores. Para type: git (Azure Repos), name es <project>/<repo> . El proyecto debe estar en la misma organización; No se admiten referencias entre organizaciones.

Los repositorios se resuelven solo una vez, cuando se inicia la canalización. Después, se usa el mismo recurso durante la canalización. Solo se usan los archivos de plantilla. Una vez que las plantillas se expanden por completo, la canalización final se ejecuta como si se hubiera definido completamente en el repositorio de origen. Esto significa que no puede usar scripts del repositorio de plantillas en la canalización.

Si desea usar una versión determinada y fija de la plantilla, asegúrese de anclar a una referencia. Las referencias son ramas ( refs/heads/<name> ) o etiquetas ( refs/tags/<name> ). Si desea anclar una confirmación específica, cree primero una etiqueta que apunte a esa confirmación y, a continuación, anclar a esa etiqueta.

Expresiones

Use expresiones de plantilla para especificar cómo se resuelven dinámicamente los valores durante la inicialización de la canalización. Ajuste la expresión de plantilla dentro de esta sintaxis: ${{ }} .

Las expresiones de plantilla pueden expandir parámetros de plantilla y también variables. Puede usar parámetros para influir en cómo se expande una plantilla. El parameters objeto funciona como el objeto parameters una expresión.

Por ejemplo, defina una plantilla:

# File: steps/msbuild.yml

parameters:
  solution: '**/*.sln'

steps:
- task: msbuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}  # property dereference syntax

A continuación, haga referencia a la plantilla y pásala el parámetro solution opcional:

# File: azure-pipelines.yml

steps:
- template: steps/msbuild.yml
  parameters:
    solution: my.sln

Contexto

Dentro de una expresión de plantilla, tiene acceso al parameters contexto , que contiene los valores de los parámetros pasados. Además, tiene acceso al contexto , que contiene todas las variables especificadas en el archivo YAML más variables las variables del variables. Lo importante es que no tiene variables en tiempo de ejecución como las almacenadas en la canalización o dadas al iniciar una ejecución. La expansión de plantillas se produce al principio de laejecución, por lo que esas variables no están disponibles.

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 mediante Bash (que le permite solution trabajar en cualquier plataforma):

# File: steps/msbuild.yml

parameters:
  solution: ''

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

Funciones de expresión de plantilla

Puede usar funciones generales en las plantillas. También puede usar algunas funciones de expresión de plantilla.

format

• Reemplazo de token de cadena simple
• Parámetros mínimos: 2. Parámetros máximos: N
• Ejemplo: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

• Se evalúa como el primer argumento de cadena no vacío y no nulo
• Parámetros mínimos: 2. Parámetros máximos: N
• Ejemplo:

parameters:
  restoreProjects: ''
  buildProjects: ''

steps:
- script: echo ${{ coalesce(parameters.foo, parameters.bar, 'Nothing to see') }}

Inserción

Puede usar expresiones de plantilla para modificar la estructura de una canalización de YAML. Por ejemplo, para insertar en una secuencia:

# File: jobs/build.yml

parameters:
  preBuild: []
  preTest: []
  preSign: []

jobs:
- job: Build
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: cred-scan
  - ${{ parameters.preBuild }}
  - task: msbuild@1
  - ${{ parameters.preTest }}
  - task: vstest@2
  - ${{ parameters.preSign }}
  - script: sign

# File: .vsts.ci.yml

jobs:
- template: jobs/build.yml
  parameters:
    preBuild:
    - script: echo hello from pre-build
    preTest:
    - script: echo hello from pre-test

Cuando se inserta una matriz en una matriz, la matriz anidada se aplana.

Para insertar en una asignación, use la propiedad especial ${{ insert }} .

# Default values
parameters:
  additionalVariables: {}

jobs:
- job: build
  variables:
    configuration: debug
    arch: x86
    ${{ insert }}: ${{ parameters.additionalVariables }}
  steps:
  - task: msbuild@1
  - task: vstest@2

jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

Inserción condicional

Si desea insertar condicionalmente en una secuencia o una asignación, use inserciones y evaluación de expresiones.

Por ejemplo, para insertar en una secuencia:

# File: steps/build.yml

parameters:
  toolset: msbuild

steps:
# msbuild
- ${{ if eq(parameters.toolset, 'msbuild') }}:
  - task: msbuild@1
  - task: vstest@2

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: dotnet@1
    inputs:
      command: build
  - task: dotnet@1
    inputs:
      command: test

# File: azure-pipelines.yml

steps:
- template: steps/build.yml
  parameters:
    toolset: dotnet

Por ejemplo, para insertar en una asignación:

# File: steps/build.yml

parameters:
  debug: false

steps:
- script: tool
  env:
    ${{ if eq(parameters.debug, 'true') }}:
      TOOL_DEBUG: true
      TOOL_DEBUG_DIR: _dbg

steps:
- template: steps/build.yml
  parameters:
    debug: true

Inserción iterativa

La each directiva permite la inserción iterativa basada en una secuencia YAML (matriz) o asignación (pares clave-valor).

Por ejemplo, puede ajustar los pasos de cada trabajo con pasos adicionales previos y posteriores:

# job.yml
parameters:
  jobs: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This will get sandwiched between SetupMyBuildTools and PublishMyTelemetry.
    - job: B
      steps:
      - script: echo So will this!

También puede manipular las propiedades de todo lo que se está iterando. Por ejemplo, para agregar más dependencias:

# job.yml
parameters:
  jobs: []

jobs:
- job: SomeSpecialTool                # Run your special tool in its own job first
  steps:
  - task: RunSpecialTool@1
- ${{ each job in parameters.jobs }}: # Then do each job
  - ${{ each pair in job }}:          # Insert all properties other than "dependsOn"
      ${{ if ne(pair.key, 'dependsOn') }}:
        ${{ pair.key }}: ${{ pair.value }}
    dependsOn:                        # Inject dependency
    - SomeSpecialTool
    - ${{ if job.dependsOn }}:
      - ${{ job.dependsOn }}

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This job depends on SomeSpecialTool, even though it's not explicitly shown here.
    - job: B
      dependsOn:
      - A
      steps:
      - script: echo This job depends on both Job A and on SomeSpecialTool.

Escapar

Si necesita escapar un valor que contiene literalmente , ajuste ${{ el valor en una cadena de expresión. Por ejemplo, ${{ 'my${{value' }} o ${{ 'my${{value with a '' single quote too' }}.

Límites

Las plantillas y las expresiones de plantilla pueden provocar un crecimiento exponencial del tamaño y la complejidad de una canalización. Para ayudar a evitar el crecimiento desmesado, Azure Pipelines impone los límites siguientes:

• No se pueden incluir más de 50 archivos YAML independientes (directa o indirectamente)
• No se consumen más de 10 megabytes de memoria al analizar el YAML (en la práctica, suele estar entre 600 KB y 2 MB de YAML en disco, dependiendo de las características específicas usadas).
• No se permiten más de 2000 caracteres por expresión de plantilla