运行时参数

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

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

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

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

参数仅在模板分析期间可用。 它们在管道运行之前展开，将用参数值替换周围的 ${{ }} 值。 如果需要在整个管道运行中提供值，请使用变量。

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

使用 templateContext 将更多属性传递给模板中用作参数的阶段、步骤和作业。

参数和变量之间的区别是什么？

下表重点介绍了 Azure Pipelines 中的参数和变量之间的主要差异。

在管道中使用参数

在 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 。 如果从 YAML 编辑器运行管道，则无法选择池映像。

将条件与参数一起使用

还可以将参数用作条件逻辑的一部分。 通过条件式，满足 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

检查空参数对象

使用 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

参数数据类型

step、stepList、job、jobList、deploymentdeploymentList、stage、 stringList和stageList数据类型都使用标准 YAML 架构格式。 此示例包括string、number、boolean、object和stepstepList。

parameters:
- name: myString  # Define a parameter named 'myString'
  type: string  # The parameter type is string
  default: a string  # Default value is 'a string'

- name: myMultiString  # Define a parameter named 'myMultiString'
  type: string  # The parameter type is string
  default: default  # Default value is 'default', only one default
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myStringlist # Define a parameter named 'myStringlist'
  type: stringList # The parameter type is stringList
  displayName: Regions
  values: # Allowed values for 'myStringlist'
    - WUS
    - CUS
    - EUS
  default: # Default values
    - WUS
    - CUS
    
- name: myNumber  # Define a parameter named 'myNumber'
  type: number  # The parameter type is number
  default: 2  # Default value is 2
  values:  # Allowed values for 'myNumber'
  - 1  
  - 2  
  - 4  
  - 8  
  - 16  

- name: myBoolean  # Define a parameter named 'myBoolean'
  type: boolean  # The parameter type is boolean
  default: true  # Default value is true

- name: myObject  # Define a parameter named 'myObject'
  type: object  # The parameter type is object
  default:  # Default value is an object with nested properties
    foo: FOO  # Property 'foo' with value 'FOO'
    bar: BAR  # Property 'bar' with value 'BAR'
    things:  # Property 'things' is a list
    - one  
    - two  
    - three  
    nested:  # Property 'nested' is an object
      one: apple  # Property 'one' with value 'apple'
      two: pear  # Property 'two' with value 'pear'
      count: 3  # Property 'count' with value 3

- name: myStep  # Define a parameter named 'myStep'
  type: step  # The parameter type is step
  default:  # Default value is a step
    script: echo my step 

- name: mySteplist  # Define a parameter named 'mySteplist'
  type: stepList  # The parameter type is stepList
  default:  # Default value is a list of steps
    - script: echo step one  
    - script: echo step two  
    
trigger: none  

jobs: 
- job: stepList  # Define a job named 'stepList'
  steps: ${{ parameters.mySteplist }}  # Use the steps from the 'mySteplist' parameter

- job: myStep  # Define a job named 'myStep'
  steps:
    - ${{ parameters.myStep }}  # Use the step from the 'myStep' parameter

- job: stringList  # Define a job named 'stringList'
  steps:
  - ${{ each region in parameters.myStringlist }}:
      - script: echo ${{region}}

参数安全最佳做法

在 Azure Pipelines 中使用运行时参数时，请勿将机密或敏感值作为参数输入传递。 参数值在模板分析时扩展，可能在管道日志或输出中公开。

始终验证和限制允许的参数值，以防止注入意外或不安全的输入。 授予对管道资源的访问权限时，请遵循最低特权原则。

对于凭据、令牌或其他机密数据，请使用标记为机密并存储在 Azure Key Vault、管道 UI 或变量组中的管道变量。 有关详细信息，请参阅 保护 Azure Pipelines 中的机密。