模板参数
你可以在模板中指定参数及其数据类型,然后在管道中引用这些参数。 使用 templateContext,还可以将属性传递给模板中用作参数的阶段、步骤和作业。
还可以在模板外部使用参数。 参数默认值只能使用文本。 详细了解 YAML 架构中的参数。
快速参考
参数必须包含名称和数据类型。 在 azure-pipelines.yml
中,当参数 yesNo
设置为布尔值时,生成会成功。 当 yesNo
设置为 apples
之类的字符串时,生成将失败。
# File: simple-param.yml
parameters:
- name: yesNo # name of the parameter; required
type: boolean # data type of the parameter; required
default: false
steps:
- script: echo ${{ parameters.yesNo }}
# File: azure-pipelines.yml
trigger:
- main
extends:
template: simple-param.yml
parameters:
yesNo: false # set to a non-boolean value to have the build fail
使用 templateContext 将属性传递给模板
可以使用 templateContext
将更多属性传递给在模板中用作参数的暂存、步骤和作业。 具体而言,可以在 jobList
、deploymentList
或 stageList
参数数据类型中指定 templateContext
。
可以使用 templateContext
在处理每个作业时更轻松地设置环境。 通过将作业及其环境属性对象捆绑在一起,templateContext
可帮助你更轻松地进行维护和理解 YAML。
在此示例中,testing-template.yml
中的 testSet
参数的数据类型为 jobList
。 testing-template.yml
模板使用每个关键字创建新变量 testJob
。 然后,模板会引用 testJob.templateContext.expectedHTTPResponseCode
,它会在 azure-pipeline.yml
中设置并传递给模板。
当响应代码为 200 时,模板会发出 REST 请求。 当响应代码为 500 时,模板将输出所有环境变量以供调试。
templateContext
可以包含属性。
#testing-template.yml
parameters:
- name: testSet
type: jobList
jobs:
- ${{ each testJob in parameters.testSet }}:
- ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}:
- job:
steps:
- powershell: 'Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ | Format-Table -Property Title, pubDate'
- ${{ testJob.steps }}
- ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}:
- job:
steps:
- powershell: 'Get-ChildItem -Path Env:\'
- ${{ testJob.steps }}
#azure-pipeline.yml
trigger: none
pool:
vmImage: ubuntu-latest
extends:
template: testing-template.yml
parameters:
testSet:
- job: positive_test
templateContext:
expectedHTTPResponseCode: 200
steps:
- script: echo "Run positive test"
- job: negative_test
templateContext:
expectedHTTPResponseCode: 500
steps:
- script: echo "Run negative test"
用于在运行时选择模板的参数
可以根据条件从管道 YAML 调用不同的模板。 在此示例中,当参数 experimentalTemplate
为 true 时,experimental.yml
YAML 将会运行。
#azure-pipeline.yml
parameters:
- name: experimentalTemplate
displayName: 'Use experimental build process?'
type: boolean
default: false
steps:
- ${{ if eq(parameters.experimentalTemplate, true) }}:
- template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:
- template: stable.yml
参数数据类型
数据类型 | 说明 |
---|---|
string |
字符串 |
number |
可能限制为 values: ,否则接受任何类似于数字的字符串 |
boolean |
true 或 false |
object |
任何 YAML 结构 |
step |
一个步骤 |
stepList |
步骤序列 |
job |
单个作业 |
jobList |
作业序列 |
deployment |
单个部署作业 |
deploymentList |
部署作业序列 |
stage |
单个阶段 |
stageList |
阶段序列 |
step、stepList、job、jobList、deployment、deploymentList、stage 和 stageList 数据类型都使用标准 YAML 架构格式。 此示例包括字 string、number、boolean、object、step 和 stepList。
parameters:
- name: myString
type: string
default: a string
- name: myMultiString
type: string
default: default
values:
- default
- ubuntu
- name: myNumber
type: number
default: 2
values:
- 1
- 2
- 4
- 8
- 16
- name: myBoolean
type: boolean
default: true
- name: myObject
type: object
default:
foo: FOO
bar: BAR
things:
- one
- two
- three
nested:
one: apple
two: pear
count: 3
- name: myStep
type: step
default:
script: echo my step
- name: mySteplist
type: stepList
default:
- script: echo step one
- script: echo step two
trigger: none
jobs:
- job: stepList
steps: ${{ parameters.mySteplist }}
- job: myStep
steps:
- ${{ parameters.myStep }}
可以循环访问对象并输出对象中的每个字符串。
parameters:
- name: listOfStrings
type: object
default:
- one
- two
steps:
- ${{ each value in parameters.listOfStrings }}:
- script: echo ${{ value }}
此外,还可以循环访问对象中的嵌套元素。
parameters:
- name: listOfFruits
type: object
default:
- fruitName: 'apple'
colors: ['red','green']
- fruitName: 'lemon'
colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
- ${{ each fruitColor in fruit.colors}} :
- script: echo ${{ fruit.fruitName}} ${{ fruitColor }}
必需的参数
可以在模板的开头添加验证步骤,已检查有没有所需的参数。
以下示例使用 Bash 检查是否有 solution
参数(Bahs 使其可以在任何平台上使用):
# File: steps/msbuild.yml
parameters:
- name: 'solution'
default: ''
type: string
steps:
- bash: |
if [ -z "$SOLUTION" ]; then
echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
echo "##vso[task.complete result=Failed;]"
fi
env:
SOLUTION: ${{ parameters.solution }}
displayName: Check for required parameters
- task: msbuild@1
inputs:
solution: ${{ parameters.solution }}
- task: vstest@2
inputs:
solution: ${{ parameters.solution }}
要显示模板在缺少所需的参数时失败,请执行以下操作:
# File: azure-pipelines.yml
# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml
可以向模板传递参数。
parameters
部分定义模板中可用的参数及其默认值。
模板在管道运行前进行扩展,以便用 ${{ }}
括起的值替换为它从封闭管道接收的参数。 因此,参数中只能使用预定义变量。
要跨多个管道使用参数,请参阅如何创建变量组。
带参数的作业、阶段和步骤模板
# File: templates/npm-with-params.yml
parameters:
name: '' # defaults for any parameters that aren't specified
vmImage: ''
jobs:
- job: ${{ parameters.name }}
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: npm install
- script: npm test
在管道中使用模板时,请指定模板参数的值。
# File: azure-pipelines.yml
jobs:
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Linux
vmImage: 'ubuntu-latest'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: macOS
vmImage: 'macOS-10.13'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Windows
vmImage: 'windows-latest'
还可以将参数与步骤模板或阶段模板一起使用。 例如,带参数的步骤:
# File: templates/steps-with-params.yml
parameters:
runExtendedTests: 'false' # defaults for any parameters that aren't specified
steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, 'true') }}:
- script: npm test --extended
在管道中使用模板时,请指定模板参数的值。
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
注意
标量参数始终作为字符串处理。
例如,eq(parameters['myparam'], true)
几乎总是返回 true
,即使 myparam
参数是单词 false
。
非空字符串在布尔上下文中强制转换为 true
。
可以重写该表达式以显式比较字符串:eq(parameters['myparam'], 'true')
。
参数不限于标量字符串。 只要参数展开的位置需要映射,参数就可以是映射。 同样,可以在需要序列的位置传递序列。 例如:
# azure-pipelines.yml
jobs:
- template: process.yml
parameters:
pool: # this parameter is called `pool`
vmImage: ubuntu-latest # and it's a mapping rather than a string
# process.yml
parameters:
pool: {}
jobs:
- job: build
pool: ${{ parameters.pool }}