运行时参数
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020
利用运行时参数,能够更好地控制可以传递给管道的值。 使用运行时参数可以实现以下功能:
- 在运行时为脚本和任务提供不同的值
- 控制参数类型、允许的范围和默认值
- 使用模板表达式动态选择作业和阶段
可以在模板中和管道中指定参数。 参数具有数字和字符串等数据类型,可以限制为值的子集。 YAML 中的 parameters
部分定义了可用的参数。
参数仅在模板解析时可用。 在管道运行之前展开参数,以便用参数值替换用 ${{ }}
包围的值。 如果需要在管道运行期间在更大范围内使用你的值,请使用变量。
注意
本指南不适用于经典管道。 有关经典管道中的参数,请参阅流程参数(经典)。
参数必须包含名称和数据类型。 参数是必需的。 需要在 YAML 文件中或运行管道时分配默认值。 如果未指定默认值或将 default
设置为 false
,则系统使用第一个可用值。
使用 templateContext 将额外的属性传递给在模板中用作参数的阶段、步骤和作业。
在管道中使用参数
在 YAML 的开头设置运行时参数。
此示例管道包括一个 image
参数,其中有三个托管代理作为 string
选项。 在 job 部分中,pool
值指定用于运行作业的参数中的代理。 trigger
设置为 none,以便在手动触发管道运行时可以选择 image
值。
parameters:
- name: image
displayName: Pool Image
type: string
default: ubuntu-latest
values:
- windows-latest
- ubuntu-latest
- macOS-latest
trigger: none
jobs:
- job: build
displayName: build
pool:
vmImage: ${{ parameters.image }}
steps:
- script: echo building $(Build.BuildNumber) with ${{ parameters.image }}
当管道运行时,你将选择池映像。 如果不进行选择,系统使用默认选项 ubuntu-latest
。
将条件与参数一起使用
还可以将参数用作条件逻辑的一部分。 通过条件式,满足 if
条件的 YAML 部分将会运行。
使用参数确定运行的步骤
此管道添加了第二个布尔参数 test
,可用于控制是否在管道中运行测试。 当 test
的值为 true 时,输出“运行所有测试”的步骤将运行。
parameters:
- name: image
displayName: Pool Image
values:
- windows-latest
- ubuntu-latest
- macOS-latest
- name: test
displayName: Run Tests?
type: boolean
default: false
trigger: none
jobs:
- job: build
displayName: Build and Test
pool:
vmImage: ${{ parameters.image }}
steps:
- script: echo building $(Build.BuildNumber)
- ${{ if eq(parameters.test, true) }}:
- script: echo "Running all the tests"
使用参数设置所使用的配置
还可以使用参数来设置运行哪些作业。 在此示例中,不同的体系结构根据 config
参数的值(也就是 string
类型)进行构建。 默认情况下,x86
和 x64
体系结构都会生成。
parameters:
- name: configs
type: string
default: 'x86,x64'
trigger: none
jobs:
- ${{ if contains(parameters.configs, 'x86') }}:
- job: x86
steps:
- script: echo Building x86...
- ${{ if contains(parameters.configs, 'x64') }}:
- job: x64
steps:
- script: echo Building x64...
- ${{ if contains(parameters.configs, 'arm') }}:
- job: arm
steps:
- script: echo Building arm...
有选择地排除阶段
还可以使用参数来设置阶段是否运行。 在此示例中,有一个包含四个阶段的管道,每个阶段都有不同的作业。 如果 runPerfTests
参数为 true,则运行性能测试阶段。 runPerfTests
的默认值为 false,因此在没有任何更新的情况下,只会运行四个阶段中的三个。
parameters:
- name: runPerfTests
type: boolean
default: false
trigger: none
stages:
- stage: Build
displayName: Build
jobs:
- job: Build
steps:
- script: echo running Build
- stage: UnitTest
displayName: Unit Test
dependsOn: Build
jobs:
- job: UnitTest
steps:
- script: echo running UnitTest
- ${{ if eq(parameters.runPerfTests, true) }}:
- stage: PerfTest
displayName: Performance Test
dependsOn: Build
jobs:
- job: PerfTest
steps:
- script: echo running PerfTest
- stage: Deploy
displayName: Deploy
dependsOn: UnitTest
jobs:
- job: Deploy
steps:
- script: echo running UnitTest
循环访问参数
还可以循环访问字符串、数字和布尔参数。
在此示例中,将循环访问参数并输出每个参数的名称和值。 有四个不同的参数,每个参数代表不同的类型。 myStringName
是单行字符串。 myMultiString
是一个多行字符串。 myNumber
is a number. myBoolean
不是布尔值。 在 steps 部分中,脚本任务输出每个参数的键和值。
# start.yaml
parameters:
- name: myStringName
type: string
default: a string value
- 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
steps:
- ${{ each parameter in parameters }}:
- script: echo ${{ parameter.Key }}
- script: echo ${{ parameter.Value }}
# azure-pipeline.yaml
trigger: none
extends:
template: start.yaml
检查空参数对象
可以使用length()
表达式检查对象参数是否没有值。
parameters:
- name: foo
type: object
default: []
steps:
- checkout: none
- ${{ if eq(length(parameters.foo), 0) }}:
- script: echo Foo is empty
displayName: Foo is empty
参数数据类型
数据类型 | 说明 |
---|---|
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 }}
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈