Referenz zur Vorlageverwendung

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

Mithilfe von Vorlagen können Sie wiederverwendbare Inhalte, Logik und Parameter in YAML Pipelines definieren. Um effektiv mit Vorlagen zu arbeiten, müssen Sie ein grundlegendes Verständnis der wichtigsten Konzepte von Azure Pipelines wie Phasen, Schritten und Aufträgen haben.

Vorlagen können Ihnen helfen, die Entwicklung zu beschleunigen. Beispielsweise können Sie eine Reihe der gleichen Aufgaben in einer Vorlage haben und dann die Vorlage mehrmals in verschiedene Phasen Ihrer YAML-Pipeline einschließen.

Vorlagen können Ihnen auch dabei helfen, Ihre Pipeline zu sichern. Wenn eine Vorlage steuert, was in einer Pipeline zulässig ist, definiert sie Logik, der andere Dateien folgen müssen. Sie können z. B. einschränken, welche Aufgaben ausgeführt werden dürfen. In diesem Szenario können Sie die Vorlage verwenden, um zu verhindern, dass jemand erfolgreich eine Aufgabe ausführt, die gegen die Sicherheitsrichtlinien Ihres Unternehmens verstößt.

Es gibt zwei Arten von Vorlagen: enthält und erweitert.

• Mit Vorlagen können Sie wiederverwendbare Inhalte mit einer Vorlage einfügen. Wenn eine Vorlage zum Einschließen von Inhalten verwendet wird, funktioniert sie in vielen Programmiersprachen wie eine Include-Direktive. Inhalte aus einer Datei werden in eine andere Datei eingefügt.
• Erweitert die Vorlagenkontrolle , was in einer Pipeline zulässig ist. Wenn eine erweiterte Vorlage steuert, was in einer Pipeline zulässig ist, definiert die Vorlage Logik, der eine andere Datei folgen muss.

Um Vorlagen vollständig zu nutzen, sollten Sie auch Vorlagenausdrücke und Vorlagenparameter verwenden.

Festgelegte Grenzwerte

Vorlagen und Vorlagenausdrücke können Größe und Komplexität einer Pipeline explosionsartig erhöhen. Um ein ausuferndes Wachstum zu verhindern, legt Azure Pipelines die folgenden Grenzwerte fest:

• Nicht mehr als 100 separate YAML-Dateien dürfen (direkt oder indirekt) enthalten sein.
• Nicht mehr als 20 Ebenen der Vorlagenschachtelung (Vorlagen einschließlich anderer Vorlagen)
• Nicht mehr als 10 MB belegter Arbeitsspeicher beim Analysieren des YAML-Codes (In der Praxis sind das je nach verwendeten Funktionen zwischen 600 KB und 2 MB YAML-Code auf der Festplatte.)

Erweitern aus einer Vorlage

Um die Sicherheit zu erhöhen, können Sie die Erweiterung einer Pipeline aus einer bestimmten Vorlage erzwingen. In der Datei start.yml wird der Parameter buildSteps definiert, der dann in der Pipeline azure-pipelines.yml verwendet wird. Wenn in start.yml ein buildStep in einem Skriptschritt übergeben wird, wird er abgelehnt, und beim Pipelinebuild tritt ein Fehler auf. Bei der Erweiterung aus einer Vorlage können Sie die Sicherheit erhöhen, indem Sie eine erforderliche Vorlagengenehmigung hinzufügen.

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

Erweitern aus einer Vorlage mit Ressourcen

Sie können die Erweiterung aus einer Vorlage auch über extends in Ihrer Azure-Pipeline mit Ressourcen erweitern.

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

Einfügen einer Vorlage

Sie können Inhalte aus YAML-Code kopieren und in einer anderen YAML-Datei wiederverwenden. Durch das Kopieren von Inhalten aus einer YAML-Datei in eine andere müssen Sie nicht die gleiche Logik manuell mehrmals einfügen. Die Dateivorlage include-npm-steps.yml enthält Schritte, die in azure-pipelines.yml wiederverwendet werden.

Hinweis

Vorlagendateien müssen zu Beginn einer Pipelineausführung in Ihrem Dateisystem vorhanden sein. Sie können nicht in einem Artefakt auf Vorlagen verweisen.

# 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

Wiederverwenden von Schritten

Sie können eine Vorlage einfügen, um Schritte für mehrere Aufträge wiederzuverwenden. Zusätzlich zu den Schritten aus der Vorlage kann jeder Auftrag weitere Schritte definieren.

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

Wiederverwenden von Aufträgen

Ähnlich wie bei Schritten können Aufträge mit Vorlagen wiederverwendet werden.

# 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

Denken Sie beim Arbeiten mit mehreren Aufträgen daran, den Namen des Auftrags in der Vorlagendatei zu entfernen, um Konflikte zu vermeiden.

# 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

Wiederverwenden von Stages

Auch Stages können mit Vorlagen wiederverwendet werden.

# 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

Auftrags-, Stage- und Schrittvorlagen mit Parametern

# 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

Wenn Sie die Vorlage in Ihrer Pipeline nutzen, geben Sie Werte für die Vorlagenparameter an.

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

Sie können auch Parameter mit Schritt- oder Stagevorlagen verwenden. Beispiel für Schritte mit Parametern:

# 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

Wenn Sie die Vorlage in Ihrer Pipeline nutzen, geben Sie Werte für die Vorlagenparameter an.

# File: azure-pipelines.yml

steps:
- script: npm install

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

Hinweis

Skalare Parameter ohne angegebenen Typ werden als Zeichenfolgen behandelt. Beispielsweise gibt eq(true, parameters['myparam'])true zurück, auch wenn der Parameter myparam das Wort false ist, sofern myparam nicht explizit als boolean festgelegt ist. Nicht leere Zeichenfolgen werden in einen booleschen Kontext in true umgewandelt. Dieser Ausdruck kann umgeschrieben werden, um Zeichenfolgen explizit zu vergleichen: eq(parameters['myparam'], 'true').

Parameter sind nicht auf skalare Zeichenfolgen beschränkt. Weitere Informationen finden Sie in der Liste der Datentypen. Beispiel mit dem Typ 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 }}

Wiederverwenden von Variablen

Variablen können in YAML-Code definiert und in eine andere Vorlage eingefügt werden. Dies kann nützlich sein, wenn Sie alle Variablen in einer Datei speichern möchten. Wenn Sie eine Vorlage verwenden, um Variablen in eine Pipeline einschließen, kann die enthaltene Vorlage nur zum Definieren von Variablen verwendet werden. Sie können Schritte und komplexere Logik verwenden, wenn Sie aus einer Vorlage erweitern. Verwenden Sie Parameter anstelle von Variablen, wenn Sie den Typ einschränken möchten.

In diesem Beispiel ist die Variable favoriteVeggie in azure-pipelines.yml enthalten.

# 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 }}.

Variablenvorlagen mit Parameter

Sie können Parameter mit Vorlagen an Variablen übergeben. In diesem Beispiel übergeben Sie den Parameter DIRECTORY an die Variable 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}'  

Wenn Sie die Vorlage in Ihrer Pipeline nutzen, geben Sie Werte für die Vorlagenparameter an.

# 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

Referenzvorlagenpfade

Vorlagenpfade können ein absoluter Pfad innerhalb des Repository oder relativ zu der Datei sein, die das Einschließen ausführt.

Um einen absoluten Pfad zu verwenden, muss der Vorlagenpfad mit einem / starten. Alle anderen Pfade werden als relativ betrachtet.

Hier sehen Sie ein Beispiel für eine geschachtelte Hierarchie.

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

Anschließend können Sie in fileA.yml auf fileB.yml und fileC.yml wie folgt verweisen.

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

Wenn fileC.yml Ihr Ausgangspunkt ist, können Sie fileA.yml und fileB.yml wie folgt einschließen.

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

Wenn fileB.yml Ihr Ausgangspunkt ist, können Sie fileA.yml und fileC.yml wie folgt einschließen.

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

fileB.yml Alternativ können Sie auf absolute Pfade wie diese verweisen fileA.yml und fileC.yml diese verwenden.

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

Verwenden anderer Repositorys

Sie können Ihre Vorlagen in anderen Repositorys aufbewahren. Angenommen, Sie verfügen über eine Kernpipeline, die alle Ihre App-Pipelines verwenden sollen. Sie können die Vorlage in einem Kernrepository speichern und dann in jedem Ihrer App-Repositorys darauf verweisen:

# 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

Jetzt können Sie diese Vorlage in mehreren Pipelines wiederverwenden. Verwenden Sie die Spezifikation resources, um den Speicherort des Kernrepositorys anzugeben. Wenn Sie auf das Kernrepository verweisen, verwenden Sie @ und den Namen, den Sie in resources dafür angegeben haben.

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

Für type: github lautet name wie in den obigen Beispielen <identity>/<repo>. Für type: git (Azure Repos) lautet name<project>/<repo>. Wenn sich dieses Projekt in einer separaten Azure DevOps-Organisation befindet, müssen Sie eine Dienstverbindung vom Typ Azure Repos/Team Foundation Server mit Zugriff auf das Projekt konfigurieren und in den YAML-Code einschließen:

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

Repositorys werden nur einmal aufgelöst, wenn die Pipeline gestartet wird. Anschließend wird für die Dauer der Pipeline dieselbe Ressource verwendet. Es werden nur die Vorlagendateien verwendet. Nachdem die Vorlagen vollständig erweitert wurden, wird die endgültige Pipeline so ausgeführt, als wäre sie vollständig im Quellrepository definiert. Das bedeutet, dass Sie keine Skripts aus dem Vorlagenrepository in Ihrer Pipeline verwenden können.

Wenn Sie eine bestimmte feste Version der Vorlage verwenden möchten, stellen Sie sicher, dass Sie sie an eine ref anheften. refs sind entweder Branches (refs/heads/<name>) oder Tags (refs/tags/<name>). Wenn Sie einen bestimmten Commit anheften möchten, erstellen Sie zuerst ein Tag, das auf diesen Commit weist, und heften Sie dann dieses Tag an.

Hinweis

Wenn ref nicht angegeben ist, verwendet die Pipeline standardmäßig refs/heads/main.

Sie können auch an einen bestimmten Commit in Git mit dem SHA-Wert für eine Repositoryressource anheften. Der SHA-Wert ist ein 40-stelliger Checksumhash, der den Commit eindeutig identifiziert.

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

Sie können auch @self verwenden, um auf das Repository zu verweisen, in dem die ursprüngliche Pipeline gefunden wurde. Dies ist für die Verwendung in extends-Vorlagen geeignet, wenn Sie auf Inhalte im Repository der erweiternden Pipeline verweisen möchten. Beispiel:

# 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: []

Häufig gestellte Fragen

Wie kann ich Variablen in Vorlagen verwenden?

Es gibt Zeiten, in denen es nützlich sein kann, Parameter auf Werte festzulegen, die auf Variablen basieren. Parameter werden frühzeitig bei der Verarbeitung einer Pipelineausführung erweitert, sodass nicht alle Variablen verfügbar sind. Informationen dazu, welche vordefinierten Variablen in Vorlagen verfügbar sind, finden Sie unter Verwenden vordefinierter Variablen.

In diesem Beispiel werden die vordefinierten Variablen Build.SourceBranch und Build.Reason in Bedingungen in „template.yml“ verwendet.

# 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