執行階段參數

發行項
08/07/2024

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

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

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

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

參數僅適用於範本剖析時間。在管線執行之前，會展開參數，讓所包圍 ${{ }} 的值取代為參數值。如果您需要在管線執行期間更廣泛地使用值，請使用變數。

注意

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

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

使用 templateContext 將額外的屬性傳遞至範本中做為參數的階段、步驟和作業。

在管線中使用參數

在 YAML 開頭設定運行時間參數。

此範例管線包含具有三個 image 裝載代理程式做為 string 選項的參數。在 [作業] 區段中， 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

循環通過參數

您也可以循環執行字串、數位和布爾參數。

指令碼
PowerShell

在此範例中，您會迴圈查看參數，並列印每個參數的名稱和值。有四個不同的參數，每個參數都代表不同的類型。 myStringName 是單行字串。 myMultiString 是多行字串。 myNumber 是數字。 myBoolean 是布爾值。在步驟區段中，腳本工作會輸出每個參數的索引鍵和值。

# 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

在此範例中，您會迴圈查看參數，並列印每個參數的名稱和值。有四個不同的參數，每個參數都代表不同的類型。 myStringName 是單行字串。 myMultiString 是多行字串。 myNumber 是數字。 myBoolean 是布爾值。在步驟區段中，您會在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

使用 stepList 參數動態包含步驟清單

在此範例中 stepList ，參數類型是用來動態包含建置程式中的步驟清單。

主要管線（azure-pipelines.yml）定義兩個作業：建置和部署。
建置作業會使用範本（build.yml），並使用參數傳遞建置工作 stepList 清單。
範本會 build.yml 動態包含參數中 build_tasks 定義的步驟。

#azure-pipelines.yml

trigger:
- main

jobs:
  - job: build
    displayName: 'Build .NET Core Application'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - checkout: self

      - template: build.yml
        parameters:
          build_tasks:
            - task: DotNetCoreCLI@2
              displayName: 'Restore'
              inputs:
                command: 'restore'
                projects: '**/*.csproj'  

            - task: DotNetCoreCLI@2
              displayName: 'Build'
              inputs:
                command: 'build'
                arguments: '--no-restore'
                projects: '**/*.csproj' 

  - job: deploy
    displayName: 'Pack for Azure App Service deployment'
    dependsOn: build
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - download: current
        artifact: drop

build.yml 範本：

使用 stepList 類型和預設空白清單來定義參數 build_tasks 。
將 .NET Core SDK 設定為 6.x。
逐一查看參數中的每個 build_tasks 步驟。
執行清單中定義的 build_tasks 每個步驟。

#build.yml

parameters:
  - name: build_tasks
    type: stepList
    default: []

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '6.x'

  - ${{ each step in parameters.build_tasks }}:
      - ${{ step }}

  - task: DotNetCoreCLI@2
    displayName: 'Publish'
    inputs:
      command: 'publish'
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
      projects: '**/*.csproj'

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Artifact'
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'

參數數據類型

資料類型	備註
`string`	字串
`number`	可能限制為 `values:`，否則接受任何類似數位的字串
`boolean`	`true` 或 `false`
`object`	任何 YAML 結構
`step`	單一步驟
`stepList`	步驟順序
`job`	單一作業
`jobList`	作業順序
`deployment`	單一部署作業
`deploymentList`	部署作業順序
`stage`	單一階段
`stageList`	階段序列

步驟、stepList、job、jobList、deployment、deploymentList、stage 和 stageList 數據類型全都使用標準 YAML 架構格式。此範例包含字串、數位、布爾值、物件、步驟和 stepList。

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'
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- 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

共用方式為