範本使用方式參考

發行項
10/16/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

範本可讓您在 YAML 管線中定義可重複使用的內容、邏輯和參數。若要有效地使用範本，您必須對 Azure Pipelines 重要概念有基本瞭解，例如階段、步驟和作業。

範本可協助您加速開發。例如，您可以在範本中擁有一系列相同的工作，然後在 YAML 管線的不同階段中多次包含範本。

範本也可以協助您保護管線的安全。當範本控制管線中允許的專案時，範本會定義另一個檔案必須遵循的邏輯。例如，您可能想要限制允許執行哪些工作。在該案例中，您可以使用範本來防止某人成功執行違反組織安全策略的工作。

範本有兩種類型：包括和擴充。

包含範本 可讓您使用範本插入可重複使用的內容。如果範本是用來包含內容，它就如同許多程式設計語言中的 include 指示詞。一個檔案的內容會插入另一個檔案中。
延伸範本 控制管線中允許的專案。當擴充範本控制管線中允許的專案時，範本會定義另一個檔案必須遵循的邏輯。

若要充分利用範本，您也應該使用範本運算式和範本參數。

強制限制

範本和範本運算式可能會導致管線的大小和複雜度增加。為了協助防止失控的成長，Azure Pipelines 會施加下列限制：

不加入超過 100 個個別 YAML 檔案 (直接或間接)
不超過 20 個範本巢狀 (範本包括其他範本) 層級
剖析 YAML 時耗用的記憶體不超過 10 MB（實際上，這通常介於 600 KB - 2 MB 的磁碟 YAML 之間，視所使用的特定功能而定）

使用範本定義邏輯一次，然後重複使用數次。範本會將多個 YAML 檔案的內容合併為單一管線。您可以從父管線將參數傳遞至範本。

從範本擴充

若要提高安全性，您可以強制執行管線從特定範本延伸。檔案 start.yml 會定義參數 buildSteps，然後用於管線 azure-pipelines.yml。在中 start.yml，如果使用 buildStep 腳本步驟傳遞，則會遭到拒絕，且管線組建失敗。從範本擴充時，您可以藉由新增必要的範本核准來增加安全性。

# File: start.yml
parameters:
- name: buildSteps # the name of the parameter is buildSteps
  type: stepList # data type is StepList
  default: [] # default value of buildSteps
stages:
- stage: secure_buildstage
  pool:
    vmImage: windows-latest
  jobs:
  - job: secure_buildjob
    steps:
    - script: echo This happens before code 
      displayName: 'Base: Pre-build'
    - script: echo Building
      displayName: 'Base: Build'

    - ${{ each step in parameters.buildSteps }}:
      - ${{ each pair in step }}:
          ${{ if ne(pair.value, 'CmdLine@2') }}:
            ${{ pair.key }}: ${{ pair.value }}       
          ${{ if eq(pair.value, 'CmdLine@2') }}: 
            # Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
            '${{ pair.value }}': error         

    - script: echo This happens after code
      displayName: 'Base: Signing'

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

extends:
  template: start.yml
  parameters:
    buildSteps:  
      - bash: echo Test #Passes
        displayName: succeed
      - bash: echo "Test"
        displayName: succeed
      # Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
      - task: CmdLine@2
        inputs:
          script: echo "Script Test"
      # Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
      - script: echo "Script Test"

從具有資源的範本擴充

您也可以使用 extends ，從包含資源的 Azure 管線中的範本擴充。

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

extends:
  template: resource-template.yml

# File: resource-template.yml
resources:
  pipelines:
  - pipeline: my-pipeline 
    source: sourcePipeline

steps:
- script: echo "Testing resource template"

插入範本

您可以從一個 YAML 複製內容，並在不同的 YAML 中重複使用。將內容從一個 YAML 複製到另一個 YAML，可讓您不必在多個位置手動包含相同的邏輯。檔案 include-npm-steps.yml 範本包含中 azure-pipelines.yml重複使用的步驟。

注意

範本檔案必須在管線執行開始時存在於文件系統上。您無法參考成品中的範本。

# File: templates/include-npm-steps.yml

steps:
- script: npm install
- script: yarn install
- script: npm run compile

# File: azure-pipelines.yml

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - template: templates/include-npm-steps.yml  # Template reference
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - template: templates/include-npm-steps.yml  # Template reference

步驟重複使用

您可以插入範本，以在數個作業之間重複使用一或多個步驟。除了範本中的步驟之外，每個作業都可以定義更多步驟。

# File: templates/npm-steps.yml
steps:
- script: npm install
- script: npm test

# File: azure-pipelines.yml

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - template: templates/npm-steps.yml  # Template reference

- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - template: templates/npm-steps.yml  # Template reference

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo This script runs before the template's steps, only on Windows.
  - template: templates/npm-steps.yml  # Template reference
  - script: echo This step runs after the template's steps.

作業重複使用

就像步驟一樣，工作可以重複使用範本。

# File: templates/jobs.yml
jobs:
- job: Ubuntu
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello Ubuntu"

- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - bash: echo "Hello Windows"

# File: azure-pipelines.yml

jobs:
- template: templates/jobs.yml  # Template reference

使用多個作業時，請記得移除範本檔案中的作業名稱，以避免衝突

# File: templates/jobs.yml
jobs:
- job: 
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello Ubuntu"

- job:
  pool:
    vmImage: 'windows-latest'
  steps:
  - bash: echo "Hello Windows"

# File: azure-pipelines.yml

jobs:
- template: templates/jobs.yml  # Template reference
- template: templates/jobs.yml  # Template reference
- template: templates/jobs.yml  # Template reference

階段重複使用

階段也可以重複使用範本。

# File: templates/stages1.yml
stages:
- stage: Angular
  jobs:
  - job: angularinstall
    steps:
    - script: npm install angular

# File: templates/stages2.yml
stages:
- stage: Build
  jobs:
  - job: build
    steps:
    - script: npm run build

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

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: Install
  jobs: 
  - job: npminstall
    steps:
    - task: Npm@1
      inputs:
        command: 'install'
- template: templates/stages1.yml # Template reference
- template: templates/stages2.yml # Template reference

具有參數的作業、階段和步驟範本

在下列範本中：

templates/npm-with-params.yml 定義兩個參數： name 和 vmImage ，並使用作業名稱的名稱參數和 VM 映射的 vmImage 參數來建立作業。
管線（azure-pipelines.yml）會參考範本三次，每個範本都有參考作業系統和 VM 映像名稱的不同參數值。
建置的管線會在不同的 VM 映像上執行，並根據指定的 OS 命名。每個作業都會執行 npm 安裝和 npm 測試步驟。

# File: templates/npm-with-params.yml

parameters:
- name: name  # defaults for any parameters that aren't specified
  default: ''
- name: vmImage
  default: ''

jobs:
- job: ${{ parameters.name }}
  pool: 
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

當您在管線中使用範本時，請指定範本參數的值。

# File: azure-pipelines.yml

jobs:
- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: Linux
    vmImage: 'ubuntu-latest'

- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: macOS
    vmImage: 'macOS-latest'

- template: templates/npm-with-params.yml  # Template reference
  parameters:
    name: Windows
    vmImage: 'windows-latest'

具有多個參數的階段範本

在下列範本中：

範本 stage-template.yml 會定義四個參數： stageName、 jobName、 vmImage、和 scriptPath，所有型別字串。此範本會使用 stageName 參數建立階段，以設定階段名稱、使用定義作業 jobName，並包含執行腳本的步驟。
然後，管線 azure-pipeline.yml會使用參數動態定義階段和作業，並執行執行腳本 build-script.sh的作業。

# stage-template.yml

parameters:
  - name: stageName
    type: string
  - name: jobName
    type: string
  - name: vmImage
    type: string
  - name: scriptPath
    type: string

stages:
  - stage: ${{ parameters.stageName }}
    jobs:
      - job: ${{ parameters.jobName }}
        pool:
          vmImage: ${{ parameters.vmImage }}
        steps:
          - script: ./${{ parameters.scriptPath }}

# azure-pipelines.yml
trigger:
- main

stages:
- template: stage-template.yml
  parameters:
    stageName: 'BuildStage'
    jobName: 'BuildJob'
    scriptPath: 'build-script.sh' # replace with script in your repository
    vmImage: 'ubuntu-latest'

具有步驟和參數的範本

您也可以搭配步驟或階段範本使用參數。

在下列範本中：

範本（templates/steps-with-params.yml）會定義名為 runExtendedTests 的參數，其預設值為 false。
管線（azure-pipelines.yml）會執行 npm test ， npm test --extended 因為 runExtendedTests 參數為 true。

# File: templates/steps-with-params.yml

parameters:
- name: 'runExtendedTests'  # defaults for any parameters that aren't specified
  type: boolean
  default: false

steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, true) }}:
  - script: npm test --extended

當您在管線中使用範本時，請指定範本參數的值。

# File: azure-pipelines.yml

steps:
- script: npm install

- template: templates/steps-with-params.yml  # Template reference
  parameters:
    runExtendedTests: 'true'

注意

沒有指定類型的純量參數會被視為字串。例如， eq(true, parameters['myparam']) 會傳回，即使 myparam 參數是一個字false，如果未明確提出，也會myparam傳boolean回 true。非空白字串會在布林值內容中轉換成 true 。可以重寫該表達式以明確比較字串： eq(parameters['myparam'], 'true')。

參數不限於純量字串。請參閱數據類型清單。例如，使用 object 類型：

# azure-pipelines.yml
jobs:
- template: process.yml
  parameters:
    pool:   # this parameter is called `pool`
      vmImage: ubuntu-latest  # and it's a mapping rather than a string


# process.yml
parameters:
- name: 'pool'
  type: object
  default: {}

jobs:
- job: build
  pool: ${{ parameters.pool }}

變數重複使用

變數可以在一個 YAML 中定義，並包含在另一個範本中。如果您想要將所有變數儲存在一個檔案中，這會很有用。如果您使用範本在管線中包含變數，則包含的範本只能用來定義變數。當您從範本擴充時，可以使用步驟和更複雜的邏輯。當您想要限制類型時，請使用參數，而不是變數。

在此範例中，變數 favoriteVeggie 會包含在中 azure-pipelines.yml。

# File: vars.yml
variables:
  favoriteVeggie: 'brussels sprouts'

# File: azure-pipelines.yml

variables:
- template: vars.yml  # Template reference

steps:
- script: echo My favorite vegetable is ${{ variables.favoriteVeggie }}.

具有參數的變數範本

您可以使用範本將參數傳遞至變數。在此範例中，您會將 DIRECTORY 參數傳遞至 RELEASE_COMMAND 變數。

# File: templates/package-release-with-params.yml

parameters:
- name: DIRECTORY 
  type: string
  default: "." # defaults for any parameters that specified with "." (current directory)

variables:
- name: RELEASE_COMMAND
  value: grep version ${{ parameters.DIRECTORY }}/package.json | awk -F \" '{print $4}'

當您在管線中使用範本時，請指定範本參數的值。

# File: azure-pipelines.yml

variables: # Global variables
  - template: package-release-with-params.yml # Template reference
    parameters:
      DIRECTORY: "azure/checker"

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: Release_Stage 
  displayName: Release Version
  variables: # Stage variables
  - template: package-release-with-params.yml  # Template reference
    parameters:
      DIRECTORY: "azure/todo-list"
  jobs: 
  - job: A
    steps: 
    - bash: $(RELEASE_COMMAND) #output release command

從範本延伸，並使用包含範本搭配變數

其中一個常見案例是具有開發、測試和生產階段的管線，該管線會針對變數使用範本，以及階段或作業的擴充範本。

在下列範例中， variables-template.yml 定義一組虛擬機變數，然後用於 azure-pipeline.yml。

# variables-template.yml

variables:
- name: devVmImage
  value: 'ubuntu-latest'
- name: testVmImage
  value: 'ubuntu-latest'
- name: prodVmImage
  value: 'ubuntu-latest'

下列檔案會stage-template.yml定義可重複使用的階段組態，其中包含三個參數（name、 vmImagesteps、）和名為Build的作業。

# stage-template.yml
parameters:
- name: name
  type: string
  default: ''
- name: vmImage
  type: string
  default: ''
- name: steps
  type: stepList
  default: []

stages:
- stage: ${{ parameters.name }}
  jobs:
  - job: Build
    pool:
      vmImage: ${{ parameters.vmImage }}
    steps: ${{ parameters.steps }}

下列管線 azure-pipelines.yml會從 variables-template.yml匯入變數，然後針對每個階段使用 stage-template.yml 範本。每個階段（開發、測試、Prod）都會以相同的範本定義，但具有不同的參數，導致階段之間的一致性，同時允許自定義。 Prod 階段包含環境變數，作為您可能用於驗證的範例。若要深入瞭解如何定義參數，請參閱範本參數。

# azure-pipelines.yml
trigger:
- main

variables:
- template: variables-template.yml

stages:
- template: stage-template.yml
  parameters:
    name: Dev
    vmImage: ${{ variables.devVmImage }}
    steps:
      - script: echo "Building in Dev"
- template: stage-template.yml
  parameters:
    name: Test
    vmImage: ${{ variables.testVmImage }}
    steps:
      - script: echo "Testing in Test"
- template: stage-template.yml
  parameters:
    name: Prod
    vmImage: ${{ variables.prodVmImage }}
    steps:
      - script: echo "Deploying to Prod"
        env:
          SYSTEM_ACCESSTOKEN: $(System.AccessToken)

參考範本路徑

範本路徑可以是存放庫內的絕對路徑，或相對於包含的檔案。

若要使用絕對路徑，範本路徑必須以開頭 /。所有其他路徑都會視為相對路徑。

以下是巢狀階層範例。

|
+-- fileA.yml
|
+-- dir1/
     |
     +-- fileB.yml
     |
     +-- dir2/
          |
          +-- fileC.yml

然後，您可以在中 fileA.yml 參考 fileB.yml ， fileC.yml 如下所示。

steps:
- template: dir1/fileB.yml
- template: dir1/dir2/fileC.yml

如果 fileC.yml 是起點，您可以包含 fileA.yml 並 fileB.yml 像這樣。

steps:
- template: ../../fileA.yml
- template: ../fileB.yml

當您 fileB.yml 的起點是時，您可以包含 fileA.yml 並 fileC.yml 像這樣。

steps:
- template: ../fileA.yml
- template: dir2/fileC.yml

或者， fileB.yml 可以參考 fileA.yml 及 fileC.yml 使用這類絕對路徑。

steps:
- template: /fileA.yml
- template: /dir1/dir2/fileC.yml

使用其他存放庫

您可以將範本保留在其他存放庫中。例如，假設您有一個核心管線，您希望所有應用程式管線都使用。您可以將樣本放在核心存放庫中，然後從每個應用程式存放庫加以參考：

# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
- name: 'vmImage'
  default: 'ubuntu-22.04'
  type: string

jobs:
- job: Build
  pool:
    vmImage: ${{ parameters.vmImage }}
  steps:
  - script: npm install
  - script: npm test

現在您可以在多個管線中重複使用此範本。 resources使用規格來提供核心存放庫的位置。當您參考核心存放庫時，請使用 @ ，以及您在中 resources提供的名稱。

# Repo: Contoso/LinuxProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates

jobs:
- template: common.yml@templates  # Template reference

# Repo: Contoso/WindowsProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: github
      name: Contoso/BuildTemplates
      ref: refs/tags/v1.0 # optional ref to pin to

jobs:
- template: common.yml@templates  # Template reference
  parameters:
    vmImage: 'windows-latest'

針對 type: github， name 如 <identity>/<repo> 上述範例所示。針對 type: git （Azure Repos）， name 是 <project>/<repo>。如果該專案位於個別的 Azure DevOps 組織中，您必須設定類型Azure Repos/Team Foundation Server為的服務連線，並存取專案並包含在 YAML 中：

resources:
  repositories:
  - repository: templates
    name: Contoso/BuildTemplates
    endpoint: myServiceConnection # Azure DevOps service connection
jobs:
- template: common.yml@templates

當管線啟動時，存放庫只會解析一次。之後，管線的持續時間會使用相同的資源。只會使用範本檔案。一旦範本完全展開，最終管線就會執行，就像是在來源存放庫中完全定義一樣。這表示您無法從管線中的範本存放庫使用腳本。

如果您要使用特定固定版本的樣本，請務必釘選到 ref。 refs是分支（refs/heads/<name>）或標記（refs/tags/<name>）。如果您想要釘選特定的認可，請先建立指向該認可的標記，然後釘選到該標記。

注意

ref如果未指定，管線會預設為使用 refs/heads/main。

您也可以使用存放庫資源的SHA值，釘選到 Git 中的特定認可。 SHA 值是 40 個字元的總和檢查碼哈希，可唯一識別認可。

resources:
  repositories:
    - repository: templates
      type: git
      name: Contoso/BuildTemplates
      ref: 1234567890abcdef1234567890abcdef12345678

您也可以使用 @self 來參考找到原始管線的存放庫。如果您想要回頭參考擴充管線存放庫中的內容，這會方便在範本中使用 extends 。例如：

# Repo: Contoso/Central
# File: template.yml
jobs:
- job: PreBuild
  steps: []

  # Template reference to the repo where this template was
  # included from - consumers of the template are expected
  # to provide a "BuildJobs.yml"
- template: BuildJobs.yml@self

- job: PostBuild
  steps: []

# Repo: Contoso/MyProduct
# File: azure-pipelines.yml
resources:
  repositories:
    - repository: templates
      type: git
      name: Contoso/Central

extends:
  template: template.yml@templates

# Repo: Contoso/MyProduct
# File: BuildJobs.yml
jobs:
- job: Build
  steps: []

常見問題集

如何在範本內使用變數？

有時候，根據變數將參數設定為值可能會很有用。參數會在處理管線執行初期展開，因此並非所有變數都可供使用。若要查看範本中有哪些預先定義的變數可供使用，請參閱使用預先定義的變數。

在此範例中，預先定義的變數 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

共用方式為

範本使用方式參考

強制限制

從範本擴充

從具有資源的範本擴充

插入範本

步驟重複使用

作業重複使用

階段重複使用

具有參數的作業、階段和步驟範本

變數重複使用

具有參數的變數範本

從範本延伸，並使用包含範本搭配變數

參考範本路徑

使用其他存放庫

常見問題集

如何在範本內使用變數？

意見反應

其他資源