Expressões de modelo

  • Artigo

Use expressões de modelo para especificar como os valores são resolvidos dinamicamente durante a inicialização do pipeline. Encapsule sua expressão de modelo dentro desta sintaxe: ${{ }}.

As expressões de modelo podem expandir parâmetros de modelo e também variáveis. Você pode usar parâmetros para influenciar como um modelo é expandido. O objeto parameters funciona como o objeto variables em uma expressão. Somente variáveis predefinidas podem ser usadas em expressões de modelo.

Observação

As expressões são expandidas apenas para stages, jobs, steps e containers (dentro de resources). Você não pode, por exemplo, usar uma expressão dentro de trigger ou um recurso como repositories. Além disso, no Azure DevOps 2020 RTW, você não pode usar expressões de modelo dentro de containers.

Por exemplo, você define um modelo:

# 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

Em seguida, você faz referência ao modelo e passa o parâmetro opcional solution para ele:

# File: azure-pipelines.yml

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

Contexto

Em uma expressão de modelo, você tem acesso ao contexto parameters que contém os valores dos parâmetros passados. Além disso, você tem acesso ao contexto variables que contém todas as variáveis especificadas no arquivo YAML, além de muitas das variáveis predefinidas (indicadas em cada variável nesse artigo). É importante ressaltar que ele não tem variáveis de runtime, como aquelas armazenadas no pipeline ou fornecidas quando você inicia uma execução. A expansão do modelo ocorre no início da execução, portanto, essas variáveis não estão disponíveis.

Funções de expressão de modelo

Você pode usar funções gerais em seus modelos. Você também pode usar algumas funções de expressão de modelo.

format

  • Substituição de token de cadeia de caracteres simples
  • Parâmetros mínimos: 2. Parâmetros máximos: N
  • Exemplo: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

  • É avaliado como o primeiro argumento de cadeia de caracteres não vazia e não nula
  • Parâmetros mínimos: 2. Parâmetros máximos: N
  • Exemplo:
parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

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

Inserção

Você pode usar expressões de modelo para alterar a estrutura de um pipeline YAML. Por exemplo, para inserir em uma sequência:

# 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

Quando uma matriz é inserida em uma matriz, a matriz aninhada é nivelada.

Para inserir em um mapeamento, use a propriedade 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

Inserção condicional

Se você quiser inserir condicionalmente em uma sequência ou mapeamento em um modelo, use inserções e avaliação de expressão. Você também pode usar instruções iffora dos modelos, desde que use a sintaxe de modelo.

Por exemplo, para inserir em uma sequência em um modelo:

# 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 exemplo, para inserir em um mapeamento em um modelo:

# 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

Você também pode usar a inserção condicional para variáveis. Neste exemplo, start sempre imprime e this is a test apenas imprime quando a variável foo é 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

Inserção iterativa

A diretiva each permite a inserção iterativa com base em uma sequência YAML (matriz) ou mapeamento (pares chave-valor).

Por exemplo, você pode encapsular as etapas de cada trabalho com outras pré e pós-etapas:

# 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!

Você também pode manipular as propriedades do que estiver iterando. Por exemplo, para adicionar mais dependências:

# 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 um valor

Se você precisar escapar de um valor que contém literalmente ${{, encapsule o valor em uma cadeia de caracteres de expressão. Por exemplo, ${{ 'my${{value' }} ou ${{ 'my${{value with a '' single quote too' }}