Naslaginformatie over sjabloongebruik

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

Met sjablonen kunt u herbruikbare inhoud, logica en parameters definiëren in YAML-pijplijnen. Als u effectief met sjablonen wilt werken, moet u basiskennis hebben van de belangrijkste concepten van Azure Pipelines, zoals fasen, stappen en taken.

Sjablonen kunnen u helpen bij het versnellen van de ontwikkeling. U kunt bijvoorbeeld een reeks van dezelfde taken in een sjabloon hebben en vervolgens de sjabloon meerdere keren opnemen in verschillende fasen van uw YAML-pijplijn.

Sjablonen kunnen u ook helpen uw pijplijn te beveiligen. Wanneer een sjabloon bepaalt wat is toegestaan in een pijplijn, definieert de sjabloon logica die een ander bestand moet volgen. U kunt bijvoorbeeld beperken welke taken mogen worden uitgevoerd. Voor dat scenario kunt u een sjabloon gebruiken om te voorkomen dat iemand een taak uitvoert die in strijd is met het beveiligingsbeleid van uw organisatie.

Er zijn twee typen sjablonen: bevat en breidt uit.

• Met sjablonen kunt u herbruikbare inhoud invoegen met een sjabloon. Als een sjabloon wordt gebruikt om inhoud op te nemen, werkt deze als een insluitingsrichtlijn in veel programmeertalen. Inhoud van het ene bestand wordt ingevoegd in een ander bestand.
• Breidt sjabloonbeheer uit wat is toegestaan in een pijplijn. Wanneer een breidt sjabloon bepaalt wat is toegestaan in een pijplijn, definieert de sjabloon logica die een ander bestand moet volgen.

Als u optimaal gebruik wilt maken van sjablonen, moet u ook sjabloonexpressies en sjabloonparameters gebruiken.

Opgelegde limieten

Sjablonen en sjabloonexpressies kunnen een explosieve groei van de grootte en complexiteit van een pijplijn veroorzaken. Azure Pipelines legt de volgende limieten op om te voorkomen dat de groei van de runaway wordt voorkomen:

• Er mogen niet meer dan 100 afzonderlijke YAML-bestanden worden opgenomen (direct of indirect)
• Niet meer dan 20 niveaus van sjabloonnesting (sjablonen die andere bevatten)
• Niet meer dan 10 megabytes geheugen verbruikt tijdens het parseren van de YAML (in de praktijk is dit meestal tussen 600 kB - 2 MB aan YAML op schijf, afhankelijk van de specifieke functies die worden gebruikt)

Uitbreiden vanaf een sjabloon

Als u de beveiliging wilt vergroten, kunt u afdwingen dat een pijplijn van een bepaalde sjabloon wordt uitgebreid. Het bestand start.yml definieert de parameter buildSteps, die vervolgens in de pijplijn azure-pipelines.ymlwordt gebruikt. Als start.ymleen buildStep scriptstap wordt doorgegeven, wordt deze geweigerd en mislukt de pijplijnbuild. Wanneer u een sjabloon uitbreidt, kunt u de beveiliging verhogen door een vereiste sjabloongoedkeuring toe te voegen.

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

Uitbreiden van een sjabloon met resources

U kunt ook gebruikmaken extends van een sjabloon in uw Azure-pijplijn die resources bevat.

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

Een sjabloon invoegen

U kunt inhoud van één YAML kopiëren en opnieuw gebruiken in een andere YAML. Als u inhoud van de ene YAML naar een andere kopieert, hoeft u niet handmatig dezelfde logica op meerdere plaatsen op te nemen. De include-npm-steps.yml bestandssjabloon bevat stappen die opnieuw worden gebruikt in azure-pipelines.yml.

Notitie

Sjabloonbestanden moeten aanwezig zijn op uw bestandssysteem aan het begin van een pijplijnuitvoering. U kunt geen sjablonen in een artefact raadplegen.

# 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

Stap opnieuw gebruiken

U kunt een sjabloon invoegen om een of meer stappen in verschillende taken opnieuw te gebruiken. Naast de stappen van de sjabloon kan elke taak meer stappen definiëren.

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

Opnieuw gebruiken van taak

Taken kunnen net als bij stappen opnieuw worden gebruikt met sjablonen.

# 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

Wanneer u met meerdere taken werkt, moet u de naam van de taak in het sjabloonbestand verwijderen om conflicten te voorkomen

# 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

Fasehergebruik

Fasen kunnen ook opnieuw worden gebruikt met sjablonen.

# 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

Taak-, fase- en stapsjablonen met parameters

# 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

Wanneer u de sjabloon in uw pijplijn gebruikt, geeft u waarden op voor de sjabloonparameters.

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

U kunt ook parameters gebruiken met stap- of fasesjablonen. Bijvoorbeeld stappen met parameters:

# 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

Wanneer u de sjabloon in uw pijplijn gebruikt, geeft u waarden op voor de sjabloonparameters.

# File: azure-pipelines.yml

steps:
- script: npm install

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

Notitie

Scalaire parameters zonder een opgegeven type worden behandeld als tekenreeksen. Retourneert bijvoorbeeld eq(true, parameters['myparam']) , zelfs als de myparam parameter het woord falseis , als myparam deze niet expliciet wordt gemaakt boolean.true Niet-lege tekenreeksen worden omgezet true in een Booleaanse context. Deze expressie kan opnieuw worden geschreven om tekenreeksen expliciet te vergelijken: eq(parameters['myparam'], 'true').

Parameters zijn niet beperkt tot scalaire tekenreeksen. Bekijk de lijst met gegevenstypen. Gebruik bijvoorbeeld het object volgende type:

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

Variabele hergebruik

Variabelen kunnen worden gedefinieerd in de ene YAML en worden opgenomen in een andere sjabloon. Dit kan handig zijn als u al uw variabelen in één bestand wilt opslaan. Als u een sjabloon gebruikt om variabelen in een pijplijn op te nemen, kan de opgenomen sjabloon alleen worden gebruikt om variabelen te definiëren. U kunt stappen en complexere logica gebruiken wanneer u uitbreidt vanuit een sjabloon. Gebruik parameters in plaats van variabelen wanneer u het type wilt beperken.

In dit voorbeeld is de variabele favoriteVeggie opgenomen in 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 }}.

Variabelesjablonen met parameter

U kunt parameters doorgeven aan variabelen met sjablonen. In dit voorbeeld geeft u de DIRECTORY parameter door aan een RELEASE_COMMAND variabele.

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

Wanneer u de sjabloon in uw pijplijn gebruikt, geeft u waarden op voor de sjabloonparameters.

# 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

Referentiesjabloonpaden

Sjabloonpaden kunnen een absoluut pad binnen de opslagplaats zijn of ten opzichte van het bestand dat het opnemen doet.

Als u een absoluut pad wilt gebruiken, moet het sjabloonpad beginnen met een /. Alle andere paden worden als relatief beschouwd.

Hier volgt een voorbeeld van een geneste hiërarchie.

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

Vervolgens kunt u hier fileA.yml naar verwijzen fileB.yml en fileC.yml dit leuk vinden.

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

Als fileC.yml dit het uitgangspunt is, kunt u dit opnemen en fileB.yml leuk vindenfileA.yml.

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

Wanneer fileB.yml is uw uitgangspunt, kunt u dit opnemen fileA.yml en fileC.yml leuk vinden.

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

U kunt ook fileB.yml verwijzen naar fileA.yml en fileC.yml gebruiken van absolute paden zoals deze.

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

Andere opslagplaatsen gebruiken

U kunt uw sjablonen in andere opslagplaatsen bewaren. Stel dat u een kernpijplijn hebt die u al uw app-pijplijnen wilt gebruiken. U kunt de sjabloon in een kernopslagplaats plaatsen en hiernaar verwijzen vanuit elk van uw app-opslagplaatsen:

# 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

U kunt deze sjabloon nu opnieuw gebruiken in meerdere pijplijnen. Gebruik de resources specificatie om de locatie van de kernopslagplaats op te geven. Wanneer u naar de kernopslagplaats verwijst, gebruikt @ u en de naam waarin u deze resourceshebt opgegeven.

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

Voor type: github, name is <identity>/<repo> zoals in de bovenstaande voorbeelden. Voor type: git (Azure-opslagplaatsen) name is <project>/<repo>. Als dat project zich in een afzonderlijke Azure DevOps-organisatie bevindt, moet u een serviceverbinding van het type Azure Repos/Team Foundation Server configureren met toegang tot het project en die opnemen in YAML:

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

Opslagplaatsen worden slechts eenmaal opgelost wanneer de pijplijn wordt gestart. Daarna wordt dezelfde resource gebruikt voor de duur van de pijplijn. Alleen de sjabloonbestanden worden gebruikt. Zodra de sjablonen volledig zijn uitgevouwen, wordt de uiteindelijke pijplijn uitgevoerd alsof deze volledig is gedefinieerd in de bronopslagplaats. Dit betekent dat u geen scripts uit de sjabloonopslagplaats in uw pijplijn kunt gebruiken.

Als u een bepaalde, vaste versie van de sjabloon wilt gebruiken, moet u deze vastmaken aan een ref. Dit refs zijn vertakkingen (refs/heads/<name>) of tags (refs/tags/<name>). Als u een specifieke doorvoering wilt vastmaken, maakt u eerst een tag die naar die doorvoering wijst en maakt u deze vast aan die tag.

Notitie

Als er geen ref is opgegeven, wordt de pijplijn standaard gebruikt refs/heads/main.

U kunt ook vastmaken aan een specifieke doorvoering in Git met de SHA-waarde voor een opslagplaatsresource. De SHA-waarde is een controlesomhash van 40 tekens waarmee de doorvoer uniek wordt geïdentificeerd.

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

U kunt ook verwijzen @self naar de opslagplaats waar de oorspronkelijke pijplijn is gevonden. Dit is handig voor gebruik in extends sjablonen als u wilt teruggaan naar de inhoud in de opslagplaats van de uitbreidingspijplijn. Voorbeeld:

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

Veelgestelde vragen

Hoe kan ik variabelen gebruiken in sjablonen?

Soms kan het handig zijn parameters in te stellen op waarden op basis van variabelen. Parameters worden vroeg uitgebreid bij het verwerken van een pijplijnuitvoering , zodat niet alle variabelen beschikbaar zijn. Zie Vooraf gedefinieerde variabelen gebruiken om te zien welke vooraf gedefinieerde variabelen beschikbaar zijn in sjablonen.

In dit voorbeeld worden de vooraf gedefinieerde variabelen Build.SourceBranch gebruikt in Build.Reason voorwaarden in 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