运行时参数

Azure DevOps Services |Azure DevOps Server 2022 |Azure DevOps Server 2020

运行时参数使你可以更好地控制哪些值可以传递给管道。 使用运行时参数，可以：

• 在运行时为脚本和任务提供不同的值
• 控制参数类型、允许的范围和默认值
• 使用模板表达式动态选择作业和阶段

可以在模板和管道 中指定参数 。 参数具有数字和字符串等数据类型，并且可以限制为值的子集。 parameters YAML 中的部分定义哪些参数可用。

参数仅在模板分析时可用。 参数在管道运行之前展开，以便用参数值替换周围 ${{ }} 值。 如果需要在管道运行期间将值更广泛地使用，请使用变量。

备注

本指南不适用于经典管道。 有关经典管道中的参数，请参阅经典) (进程参数 。

参数必须包含名称和数据类型。 参数不能是可选的。 需要在 YAML 文件中或运行管道时分配默认值。 如果未分配默认值或设置为defaultfalse默认值，将使用第一个可用值。

在管道中使用参数

在 YAML 的开头设置运行时参数。 此示例管道接受作业中的值 image ，然后输出该值。 设置为 trigger “无”，以便可以在手动触发管道运行时选择该值 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 。

将条件与参数配合使用

还可以将参数用作条件逻辑的一部分。 使用条件时，仅当 YAML 满足 if 条件时，YAML 的一部分才会运行。

使用参数确定运行的步骤

此管道仅在布尔参数 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运行。

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，则性能测试阶段将运行。

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

循环访问参数

还可以循环访问字符串、数字和布尔参数。

脚本

在此示例中，将循环访问参数并输出每个参数名称和值。

# 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

PowerShell

可以在 PowerShell 任务中循环访问参数，并将每个参数设置为环境变量。

# 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: 
  - task: PowerShell@2
    env:
      ${{ each parameter in parameters }}:
        ${{ parameter.Key }}: ${{ parameter.Value }}
    inputs:
      filePath: test_script.ps1
      pwsh: true

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

# test_script.ps1

Write-Host "Hello, World!"
Write-Host $env:myStringName

检查空参数对象

可以使用 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	阶段序列

步骤、stepList、jobList、jobList、deployment、deploymentList、stage 和 stageList 数据类型都使用标准 YAML 架构格式。 此示例包括字符串、数字、布尔值、对象、步骤和 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 }}

常见问题解答

如何在模板中使用变量？

有时，根据变量将参数设置为值可能很有用。 在处理 管道运行 时，会提前扩展参数，因此并非所有变量都可用。 若要查看模板中可用的预定义变量，请参阅 “使用预定义变量”。

在此示例中，预定义变量Build.SourceBranchBuild.Reason并在 template.yml 中的条件中使用。

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: template.yml

# File: template.yml
steps:
- script: echo Build.SourceBranch = $(Build.SourceBranch) # outputs refs/heads/main
- script: echo Build.Reason = $(Build.Reason) # outputs IndividualCI
- ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}: 
  - script: echo I run only if Build.SourceBranch = refs/heads/main 
- ${{ if eq(variables['Build.Reason'], 'IndividualCI') }}: 
  - script: echo I run only if Build.Reason = IndividualCI 
- script: echo I run after the conditions