範本表達式
使用範本 表示式 來指定如何在管線初始化期間動態解析值。
將此語法中的範本運算式包裝起來: ${{ }}
。
範本運算式可以展開範本參數,也可以展開變數。
您可以使用參數來影響範本的展開方式。
對象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
上下文
在範本運算式中,您可以存取 parameters
包含傳入之參數值的內容。
此外,您可以存取 variables
內容,其中包含 YAML 檔案中指定的所有變數,以及許多 預先定義的變數 (在該文章中的每個變數上註明)。
重要的是,它不會有運行時間變數,例如儲存在管線上的變數,或在啟動執行時提供。
範本擴充會在執行初期發生,因此這些變數無法使用。
範本表示式函式
您可以在樣本中使用 一般函式 。 您也可以使用一些範本運算式函式。
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
一律會在變數等於 test
時foo
列印,而且this is a 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
您也可以根據其他變數的值來設定變數。 在下列管線中, myVar
用來設定的值 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
反覆插入
指示 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' }}