範本使用方式參考

  • 發行項

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

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

# 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'

您也可以搭配步驟或階段範本使用參數。 例如，具有參數的步驟：

# 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

參考範本路徑

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

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

以下是巢狀階層範例。

|
+-- 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