執行時間參數

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

執行時間參數可讓您更充分掌控哪些值可以傳遞至管線。 使用執行時間參數，您可以：

• 在執行時間為腳本和工作提供不同的值
• 控制參數類型、允許的範圍和預設值
• 使用範本運算式動態選取作業和階段

您可以在範本和管線中指定 參數 。 參數具有數位和字串等資料類型，而且可以限制為值的子集。 YAML 中的 區 parameters 段會定義可用的參數。

參數只能在範本剖析時間使用。 參數會在管線執行之前展開，以便以參數值取代所 ${{ }} 括住的值。 如果您需要在管線執行期間更廣泛地使用值，請使用變數。

注意

本指南不適用於傳統管線。 如需傳統管線中的參數，請參閱 處理傳統) (參數 。

參數必須包含名稱和資料類型。 參數不可為選擇性。 您必須在 YAML 檔案中或當您執行管線時指派預設值。 如果您未指派預設值或設定 default 為 false ，則會使用第一個可用的值。

在管線中使用參數

在 YAML 開頭設定執行時間參數。 此範例管線會接受 的值 image ，然後輸出作業中的值。 設定 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 符合準則時，才會執行 YAML 的 if 一部分。

使用參數來判斷執行的步驟

此管線只會在布林參數 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、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.SourceBranch 和 Build.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