Expressões de modelo

Artigo
10/25/2024

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

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

Nota

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

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ê referencia o modelo e passa-lhe o parâmetro opcional solution :

# File: azure-pipelines.yml

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

Contexto

Dentro de uma expressão de modelo, você tem acesso ao parameters contexto que contém os valores dos parâmetros passados. Além disso, você tem acesso ao variables contexto que contém todas as variáveis especificadas no arquivo YAML mais muitas das variáveis predefinidas (anotadas em cada variável nesse artigo). É importante ressaltar que ele não tem variáveis de tempo de execução, como aquelas armazenadas no pipeline ou fornecidas quando você inicia uma execução. A expansão do modelo acontece 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

Avalia 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 numa 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 é achatada.

Para inserir em um mapeamento, use a propriedade ${{ insert }}special .

# 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 um mapeamento em um modelo, use inserções e avaliação de expressão. Você também pode usar if instruções fora dos modelos , desde que use a sintaxe do 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 só imprime quando a variável é testigual a foo .

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 each diretiva permite a inserção iterativa com base em uma sequência YAML (matriz) ou mapeamento (pares chave-valor).

Por exemplo, você pode envolver as etapas de cada trabalho com outras etapas pré e 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!

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 literalmente contém ${{, envolva o valor em uma cadeia de caracteres de expressão. Por exemplo, ${{ 'my${{value' }} ou ${{ 'my${{value with a '' single quote too' }}

Partilhar via