Expresiones de plantilla

  • Artículo

Use expresionesde 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 objeto parameters funciona como el variables objeto en una expresión. Solo se pueden usar variables predefinidas en expresiones de plantilla.

Nota:

Las expresiones solo se expanden para stages, jobs, steps y containers (dentro de resources). Por ejemplo, no puede usar una expresión dentro de trigger o un recurso como repositories. Además, en Azure DevOps 2020 RTW, no puede usar expresiones de plantilla dentro de containers.

Por ejemplo, define 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ásela el parámetro opcional solution:

# File: azure-pipelines.yml

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

Context

Dentro de una expresión de plantilla, tiene acceso al contexto parameters que contiene los valores de los parámetros pasados. Además, tiene acceso al contexto variables que contiene todas las variables especificadas en el archivo YAML más muchas de las variables predefinidas (indicadas en cada variable de ese artículo). Es importante destacar 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 la ejecución, por lo que esas variables no están disponibles.

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 tokens 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 que no está vacío y no es Null
  • 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 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 iffuera de las plantillas siempre que use la sintaxis de plantilla.

Por ejemplo, para insertar en una secuencia de 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 variables. En este ejemplo, start siempre imprime y this is a test solo imprime cuando la variable foo es igual a test.

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 directiva each 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 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 de un valor que literalmente contiene ${{, ajuste el valor en una cadena de expresión. Por ejemplo, ${{ 'my${{value' }} o ${{ 'my${{value with a '' single quote too' }}.