Ekspresi templat

Ekspresi templat membuat templat Azure Pipelines Anda lebih dinamis dan dapat digunakan kembali. Dengan menggunakan ekspresi templat, Anda dapat:

  • Memparametrisasi templat: Meneruskan nilai ke templat untuk menyesuaikan perilakunya tanpa menduplikasi kode.
  • Konten yang disertakan secara kondisional: Menambahkan atau mengecualikan langkah, pekerjaan, atau tahapan alur secara dinamis berdasarkan nilai parameter.
  • Sisipkan dan ulangi koleksi: Hasilkan beberapa elemen alur dari array atau pasangan kunci-nilai.
  • Kurangi pengulangan: Buat templat yang fleksibel dan dapat digunakan kembali yang berfungsi di berbagai skenario dan tim.

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 dan variabel templat. Gunakan 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.

Misalnya, Anda menentukan templat:

# 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)'

Kemudian Anda mereferensikan templat dan meneruskannya parameter opsional solution :

# File: azure-pipelines.yml

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

Konteks

Dalam ekspresi templat, Anda memiliki akses ke parameters konteks (kumpulan data yang tersedia dalam ekspresi, seperti parameter dan variabel yang diteruskan ke templat) 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.

bentuk

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

gabungkan

  • Menghasilkan argumen string pertama yang tidak kosong dan bukan null
  • Parameter minimal: 2. Parameter maksimum: N
  • Contoh:
parameters:
- name: 'customVersion'
  type: string
  default: ''
- name: 'defaultVersion'
  type: string
  default: '1.0.0'

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

Catatan

Parameter string dengan default: '' (string kosong) ber perilaku berbeda tergantung pada cara Anda memicu alur:

  • Di editor alur: Anda dapat menjalankan alur secara langsung dan default string kosong dihormati, memungkinkan coalesce untuk kembali ke nilai berikutnya.
  • Di panel Jalankan Alur: Azure DevOps mengharuskan Anda untuk memberikan nilai yang tidak kosong untuk parameter yang memiliki string kosong sebagai nilai default, mencegah coalesce untuk kembali ke nilai default tersebut.

Penyisipan

Gunakan ekspresi templat untuk mengubah struktur alur YAML. Misalnya, gunakan ekspresi berikut 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: 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

Saat Anda menyisipkan array ke dalam array, Anda meratakan array berlapis.

Untuk menyisipkan ke dalam pemetaan (kumpulan pasangan kunci-nilai, mirip dengan kamus atau objek di YAML), 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: VSBuild@1
  - task: VSTest@3

jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

Penyisipan kondisional

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 memasukkan ke dalam urutan suatu templat:

# 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

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 menggunakan stringList untuk menentukan dan melakukan iterasi atas parameter yang berisi daftar item.

Catatan

Jenis stringList data tidak tersedia dalam templat. Gunakan jenis data object dalam templat sebagai pengganti.

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}}

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 menghindari nilai yang secara harfiah berisi ${{, bungkus nilai dalam string ekspresi. Misalnya, gunakan ${{ 'my${{value' }} atau ${{ 'my${{value with a '' single quote too' }} .

  • Last updated on