テンプレート式

[アーティクル]
10/25/2024

テンプレート式を使用して、パイプラインの初期化中に値が動的に解決される方法を指定します。 ${{ }} 構文内でテンプレート式をラップします。

テンプレート式では、テンプレートパラメーターと変数を展開できます。パラメーターを使用して、テンプレートの展開方法に影響を与えることができます。 parameters オブジェクトは、式の variables オブジェクトのように機能します。テンプレート式では、定義済みの変数のみを使用できます。

注意

式は、stages、jobs、steps、containers (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

Context

テンプレート式の中では、渡されたパラメーターの値を含む parameters コンテキストにアクセスできます。さらに、YAML ファイルで指定されたすべての変数に加えて、定義済みの変数 (そのアーティクルの各変数に記載されている) の多くを含む variables コンテキストにアクセスできます。重要なのは、パイプラインに格納されているランタイム変数や、実行の開始時に指定されたランタイム変数が含まれていない点です。テンプレートの展開は実行の早い段階で行われるため、これらの変数は使用できません。

テンプレート式の関数

テンプレートでは、一般的な関数を使用できます。いくつかのテンプレート式の関数を使用することもできます。

format

シンプルな文字列トークンの置換
最小パラメーター: 2。最大パラメーター: N
例: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

最初の空でない null 以外の文字列引数に評価されます
最小パラメーター: 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

また、変数に対して条件付き挿入を使用することもできます。この例では、start は常に出力され、this is a test は 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

他の変数の値に基づいて変数を設定することもできます。次のパイプラインでは、conditionalVar の値を設定するために myVar が使用されています。

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

反復の挿入

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.

値をエスケープする

リテラルに ${{ を含む値をエスケープする必要がある場合は、その値を式文字列でラップします。たとえば、${{ 'my${{value' }} や ${{ 'my${{value with a '' single quote too' }} のようにします。

次の方法で共有