Ekspresi templat

Artikel
10/25/2024

Gunakan ekspresi templat untuk menentukan bagaimana nilai diselesaikan secara dinamis selama inisialisasi alur. Bungkus ekspresi templat Anda di dalam sintaks ini: ${{ }}.

Ekspresi templat dapat memperluas parameter templat, dan juga variabel. Anda dapat menggunakan parameter untuk memengaruhi cara templat diperluas. Objek parameters berfungsi seperti variables objek dalam ekspresi. Hanya variabel yang telah ditentukan sebelumnya yang dapat digunakan dalam ekspresi templat.

Catatan

Ekspresi hanya diperluas untuk stages, jobs, steps, dan containers (di dalam resources). Anda tidak dapat, misalnya, menggunakan ekspresi di dalam trigger atau sumber daya seperti repositories. Selain itu, pada Azure DevOps 2020 RTW, Anda tidak dapat menggunakan ekspresi templat di dalam containers.

Misalnya, Anda menentukan templat:

# 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

Kemudian Anda mereferensikan templat dan meneruskannya parameter opsional solution :

# File: azure-pipelines.yml

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

Konteks

Dalam ekspresi templat, Anda memiliki akses ke parameters konteks yang berisi nilai parameter yang diteruskan. Selain itu, Anda memiliki akses ke variables konteks yang berisi semua variabel yang ditentukan dalam file YAML ditambah banyak variabel yang telah ditentukan sebelumnya (dicatat pada setiap variabel dalam artikel tersebut). Yang penting, itu tidak memiliki variabel runtime seperti yang disimpan di alur atau diberikan saat Anda memulai eksekusi. Ekspansi templat terjadi di awal proses, sehingga variabel tersebut tidak tersedia.

Fungsi ekspresi templat

Anda dapat menggunakan fungsi umum dalam templat Anda. Anda juga dapat menggunakan beberapa fungsi ekspresi templat.

format

Penggantian token string sederhana
Parameter min: 2. Parameter maks: N
Contoh: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

gabungkan

Mengevaluasi ke argumen untai (karakter) pertama yang tidak kosong dan bukan null
Parameter min: 2. Parameter maks: N
Contoh:

parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

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

Penyisipan

Anda dapat menggunakan ekspresi templat untuk mengubah struktur alur YAML. Misalnya, untuk menyisipkan ke dalam urutan:

# 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

Saat array disisipkan ke dalam array, array berlapis diratakan.

Untuk menyisipkan ke dalam pemetaan, gunakan properti ${{ insert }}khusus .

# 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

Penyisipan bersyarah

Jika Anda ingin menyisipkan secara kondisional ke dalam urutan atau pemetaan dalam templat, gunakan penyisipan dan evaluasi ekspresi. Anda juga dapat menggunakan if pernyataan di luar templat selama Anda menggunakan sintaks templat.

Misalnya, untuk menyisipkan ke dalam urutan dalam templat:

# 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

Misalnya, untuk menyisipkan ke dalam pemetaan dalam templat:

# 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

Anda juga dapat menggunakan penyisipan kondisi untuk variabel. Dalam contoh ini, start selalu mencetak dan this is a test hanya mencetak ketika foo variabel sama dengan 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

Anda juga dapat mengatur variabel berdasarkan nilai variabel lain. Dalam alur berikut, myVar digunakan untuk mengatur nilai 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

Penyisipan berulang

Direktif each memungkinkan penyisipan berulang berdasarkan urutan YAML (array) atau pemetaan (pasangan kunci-nilai).

Misalnya, Anda dapat membungkus langkah-langkah setiap pekerjaan dengan pra-dan pasca-langkah lainnya:

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

Anda juga dapat memanipulasi properti apa pun yang Anda iterasi. Misalnya, untuk menambahkan lebih banyak dependensi:

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

Lolos dari nilai

Jika Anda perlu melepaskan nilai yang secara harfiah berisi ${{, maka bungkus nilai dalam string ekspresi. Misalnya, ${{ 'my${{value' }} atau ${{ 'my${{value with a '' single quote too' }}

Bagikan melalui