Выражения шаблона

  • Статья

Используйте выражения шаблона, чтобы указать, как значения динамически разрешаются во время инициализации конвейера. Обтекайте выражение шаблона в этом синтаксисе: ${{ }}

Выражения шаблонов могут расширять параметры шаблона, а также переменные. Параметры можно использовать для влияния на развертывание шаблона. Объект parameters работает как variables объект в выражении. В выражениях шаблона можно использовать только предопределенные переменные.

Примечание.

Выражения развертываются только для stages, jobsи containerssteps(внутриresources). Например, нельзя использовать выражение внутри trigger или ресурс, например repositories. Кроме того, в Azure DevOps 2020 RTW нельзя использовать выражения шаблонов внутри containers.

Например, вы определяете шаблон:

# 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

Затем вы ссылаетесь на шаблон и передайте его необязательный solution параметр:

# File: azure-pipelines.yml

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

Контекст

В выражении шаблона у вас есть доступ к parameters контексту, который содержит значения параметров, переданных в. Кроме того, у вас есть доступ к variables контексту, который содержит все переменные, указанные в YAML-файле, плюс многие предопределенные переменные (отмеченные для каждой переменной в этой статье). Важно, что при запуске запуска переменные среды выполнения не имеют таких переменных, как те, которые хранятся в конвейере или даны при запуске. Расширение шаблона происходит в начале выполнения, поэтому эти переменные недоступны.

Функции выражения шаблона

Общие функции можно использовать в шаблонах. Можно также использовать несколько функций выражения шаблона.

format

  • Простая замена токена строки
  • Минимальные параметры: 2. Максимальные параметры: N
  • Пример: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

  • Вычисляет первый непустый, непустый строковый аргумент
  • Минимальные параметры: 2. Максимальные параметры: N
  • Пример:
parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

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

Вставка

Выражения шаблонов можно использовать для изменения структуры конвейера YAML. Например, чтобы вставить в последовательность:

# 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

Если массив вставляется в массив, вложенный массив неструктурирован.

Чтобы вставить в сопоставление, используйте специальное свойство ${{ 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

Условное вставка

Если вы хотите условно вставить последовательность или сопоставление в шаблоне, используйте вставки и оценку выражений. Вы также можете использовать if инструкции за пределами шаблонов, если используется синтаксис шаблона.

Например, чтобы вставить в последовательность в шаблоне:

# 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

Например, чтобы вставить сопоставление в шаблон:

# 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

Можно также использовать условное вставка для переменных. В этом примере всегда печатается и this is a test печатается только в том случае, start если foo переменная равна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

Итеративная вставка

Директива each разрешает итеративную вставку на основе последовательности YAML (массива) или сопоставления (пар "ключ-значение").

Например, можно упаковать шаги каждого задания с другими предварительными и пост-шагами:

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

Вы также можете управлять свойствами того, что вы выполняете итерацию. Например, чтобы добавить дополнительные зависимости:

# 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-значение

Если необходимо экранировать значение, которое буквально содержится ${{, то обтекайте значение в строке выражения. Например, ${{ 'my${{value' }} или ${{ 'my${{value with a '' single quote too' }}.