Expressões de modelo

As expressões de modelo tornam seus modelos do Azure Pipelines mais dinâmicos e reutilizáveis. Usando expressões de modelo, você pode:

• Modelos parametrizados: passe valores para modelos para personalizar seu comportamento sem duplicar código.
• Incluir conteúdo condicionalmente: adicionar ou excluir dinamicamente etapas de pipeline, trabalhos ou estágios com base em valores de parâmetro.
• Inserir e iterar em coleções: gere vários elementos de pipeline de matrizes ou pares chave-valor.
• Reduzir a repetição: crie modelos flexíveis e reutilizáveis que funcionam em diferentes cenários e equipes.

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 e variáveis de modelo. Use 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.

Por exemplo, você define um modelo:

# File: steps/vsbuild.yml

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

steps:
- task: VSBuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: VSTest@3
  inputs:
    testSelector: 'testAssemblies' 
    testAssemblyVer2: ${{ parameters.solution }} # property dereference syntax
    searchFolder: '$(System.DefaultWorkingDirectory)' 

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

# File: azure-pipelines.yml

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

Contexto

Dentro de uma expressão de modelo, você tem acesso ao parameters contexto (o conjunto de dados disponíveis dentro da expressão, como parâmetros e variáveis passados para o modelo) 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.

formato

• 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'

unir

• É 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: 'customVersion'
  type: string
  default: ''
- name: 'defaultVersion'
  type: string
  default: '1.0.0'

steps:
- script: echo Version is ${{ coalesce(parameters.customVersion, parameters.defaultVersion) }}

Inserção

Use expressões de modelo para alterar a estrutura de um pipeline YAML. Por exemplo, use a seguinte expressão 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: VSBuild@1
  - ${{ parameters.preTest }}
  - task: VSTest@3
  - ${{ 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

Ao inserir uma matriz em uma matriz, você nivela a matriz aninhada.

Para inserir em um mapeamento (uma coleção de pares chave-valor, semelhante a um dicionário ou objeto no YAML), 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: VSBuild@1
  - task: VSTest@3

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: vsbuild
  type: string
  values:
  - vsbuild
  - dotnet

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

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: UseDotNet@2
    inputs:
      command: build
  - task: UseDotNet@2
    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

Você também pode definir variáveis com base nos valores de outras variáveis. No pipeline a seguir, myVar é usado para definir o valor de conditionalVar.

trigger:
- main

pool: 
   vmImage: 'ubuntu-latest' 

variables:
  - name: myVar
    value: 'baz'

  - name: conditionalVar
    ${{ if eq(variables['myVar'], 'foo') }}:
      value: 'bar'
    ${{ elseif eq(variables['myVar'], 'baz') }}:
      value: 'qux'
    ${{ else }}:
      value: 'default'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.conditionalVar, 'bar') }}:
  - script: echo "the value of myVar is set in the if condition" # runs when myVar=foo
- ${{ if eq(variables.conditionalVar, 'qux') }}:
  - script: echo "the value of myVar is set in the elseif condition" # runs when myVar=baz

Inserção iterativa

A diretiva each habilita 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 usar stringList para definir e iterar sobre parâmetros que contêm uma lista de itens.

parameters:
- name: regions
  type: stringList
  displayName: Regions
  values:
    - WUS
    - CUS
    - EUS
  default: 
    - WUS
    - EUS 

stages:
- ${{ each stage in parameters.regions}}:
  - stage: ${{stage}}
    displayName: Deploy to ${{stage}}
    jobs:
    - job:
      steps:
      - script: ./deploy ${{stage}}

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, coloque o valor em uma string de expressão. Por exemplo, use ${{ 'my${{value' }} ou ${{ 'my${{value with a '' single quote too' }}.