Dela via

Referens för mallanvändning

  • Artikel

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

Med mallar kan du definiera återanvändbart innehåll, logik och parametrar i YAML-pipelines. För att kunna arbeta effektivt med mallar måste du ha en grundläggande förståelse för viktiga begrepp i Azure Pipelines, till exempel steg, steg och jobb.

Mallar kan hjälpa dig att påskynda utvecklingen. Du kan till exempel ha en serie med samma uppgifter i en mall och sedan inkludera mallen flera gånger i olika steg i YAML-pipelinen.

Mallar kan också hjälpa dig att skydda din pipeline. När en mall styr vad som tillåts i en pipeline definierar mallen logik som en annan fil måste följa. Du kanske till exempel vill begränsa vilka aktiviteter som tillåts köras. I det scenariot kan du använda mallen för att förhindra att någon kör en uppgift som bryter mot organisationens säkerhetsprinciper.

Det finns två typer av mallar: inkluderar och utökar.

  • Med mallar kan du infoga återanvändbart innehåll med en mall. Om en mall används för att inkludera innehåll fungerar den som ett inkluderingsdirektiv på många programmeringsspråk. Innehåll från en fil infogas i en annan fil.
  • Utökar mallkontrollen vad som tillåts i en pipeline. När en utökad mall styr vad som tillåts i en pipeline definierar mallen logik som en annan fil måste följa.

Om du vill dra full nytta av mallar bör du också använda malluttryck och mallparametrar.

Införda gränser

Mallar och malluttryck kan ge en explosiv ökning av pipelinens storlek och komplexitet. För att förhindra skenande tillväxt inför Azure Pipelines följande gränser:

  • Högst 100 separata YAML-filer får ingå (direkt eller indirekt)
  • Högst 20 nivåer av mallkapsling (mallar som inkluderar andra mallar)
  • Högst 10 mb minne förbrukas vid parsning av YAML (i praktiken är detta vanligtvis mellan 600 KB och 2 MB YAML på disk, beroende på vilka funktioner som används)

Använd mallar för att definiera logiken en gång och sedan återanvända den flera gånger. Mallar kombinera innehållet i flera YAML-filer i en enda pipeline. Du kan skicka parametrar till en mall från den överordnade pipelinen.

Utöka från en mall

För att öka säkerheten kan du framtvinga att en pipeline utökas från en viss mall. Filen start.yml definierar parametern buildSteps, som sedan används i pipelinen azure-pipelines.yml. I start.yml, om en buildStep skickas med ett skriptsteg, avvisas den och pipeline-versionen misslyckas. När du utökar från en mall kan du öka säkerheten genom att lägga till ett obligatoriskt mallgodkännande.

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

Utöka från en mall med resurser

Du kan också använda extends för att utöka från en mall i din Azure-pipeline som innehåller resurser.

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

Infoga en mall

Du kan kopiera innehåll från en YAML och återanvända det i en annan YAML. Om du kopierar innehåll från en YAML till en annan kan du inte behöva inkludera samma logik manuellt på flera platser. Filmallen include-npm-steps.yml innehåller steg som återanvänds i azure-pipelines.yml.

Kommentar

Mallfiler måste finnas i filsystemet i början av en pipelinekörning. Du kan inte referera till mallar i en artefakt.

# 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

Steg för återanvändning

Du kan infoga en mall för att återanvända ett eller flera steg i flera jobb. Förutom stegen från mallen kan varje jobb definiera fler steg.

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

Återanvändning av jobb

Precis som med steg kan jobb återanvändas med mallar.

# 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

När du arbetar med flera jobb bör du komma ihåg att ta bort namnet på jobbet i mallfilen för att undvika konflikter

# 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

Återanvändning av steg

Steg kan också återanvändas med mallar.

# 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

Jobb-, fas- och stegmallar med parametrar

I följande mallar:

  • templates/npm-with-params.yml definierar två parametrar: name och vmImage skapar ett jobb med namnparametern för jobbnamnet och parametern vmImage för VM-avbildningen.
  • Pipelinen (azure-pipelines.yml) refererar till mallen tre gånger, var och en med olika parametervärden som refererar till operativsystem- och VM-avbildningsnamnen.
  • Den byggda pipelinen körs på en annan VM-avbildning och namnges enligt det angivna operativsystemet. Varje jobb utför npm-installations- och npm-teststeg.
# 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

När du använder mallen i pipelinen anger du värden för mallparametrarna.

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

Mellanlagra mallar med flera parametrar

I följande mallar:

  • Mallen stage-template.yml definierar fyra parametrar: stageName, jobName, vmImageoch scriptPath, alla av typen sträng. Mallen skapar en fas med parametern stageName för att ange fasnamnet, definierar ett jobb med jobNameoch innehåller ett steg för att köra ett skript.
  • Pipelinen , azure-pipeline.yml, definierar sedan steg och jobb dynamiskt med hjälp av parametrar och kör ett jobb som kör ett skript, 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'

Mallar med steg och parametrar

Du kan också använda parametrar med steg- eller stegmallar.

I följande mallar:

  • Mallen (templates/steps-with-params.yml) definierar en parameter med namnet runExtendedTests med standardvärdet false.
  • Pipelinen (azure-pipelines.yml) körs npm test och npm test --extended eftersom parametern runExtendedTests är sann.
# 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

När du använder mallen i pipelinen anger du värden för mallparametrarna.

# File: azure-pipelines.yml

steps:
- script: npm install

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

Kommentar

Skalära parametrar utan en angiven typ behandlas som strängar. Till exempel eq(true, parameters['myparam']) returnerar true, även om parametern myparam är ordet false, om myparam inte uttryckligen görs boolean. Icke-tomma strängar gjuts till true i en boolesk kontext. Uttrycket kan skrivas om för att explicit jämföra strängar: eq(parameters['myparam'], 'true').

Parametrar är inte begränsade till skalärsträngar. Se listan över datatyper. Du kan till exempel använda typen 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 }}

Återanvändning av variabel

Variabler kan definieras i en YAML och ingå i en annan mall. Detta kan vara användbart om du vill lagra alla dina variabler i en fil. Om du använder en mall för att inkludera variabler i en pipeline kan den inkluderade mallen endast användas för att definiera variabler. Du kan använda steg och mer komplex logik när du utökar från en mall. Använd parametrar i stället för variabler när du vill begränsa typen.

I det här exemplet ingår variabeln favoriteVeggie i 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 }}.

Variabelmallar med parameter

Du kan skicka parametrar till variabler med mallar. I det här exemplet skickar du parametern DIRECTORY till en RELEASE_COMMAND variabel.

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

När du använder mallen i pipelinen anger du värden för mallparametrarna.

# 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

Utöka från en mall och använd en inkluderingsmall med variabler

Ett vanligt scenario är att ha en pipeline med faser för utveckling, testning och produktion som använder både en mall för variabler och en utökad mall för steg eller jobb.

I följande exempel variables-template.yml definierar en uppsättning variabler för virtuella datorer som sedan används i azure-pipeline.yml.

# variables-template.yml

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

Följande fil stage-template.yml definierar en återanvändbar faskonfiguration med tre parametrar (name, vmImage, steps) och ett jobb med namnet 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 }}

Följande pipeline, azure-pipelines.yml, importerar variabler från variables-template.ymloch använder sedan mallen stage-template.yml för varje steg. Varje steg (Dev, Test, Prod) definieras med samma mall men med olika parametrar, vilket leder till konsekvens mellan olika steg samtidigt som anpassning möjliggörs. Prod-fasen innehåller en miljövariabel som ett exempel på något du kan använda för autentisering.

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

Sökvägar för referensmallar

Mallsökvägar kan vara en absolut sökväg i lagringsplatsen eller i förhållande till den fil som ingår.

Om du vill använda en absolut sökväg måste mallsökvägen börja med ./ Alla andra sökvägar anses vara relativa.

Här är ett exempel på en kapslad hierarki.

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

Sedan kan du referera fileA.yml till fileB.yml och fileC.yml så här.

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

Om fileC.yml är din startpunkt kan du inkludera fileA.yml och fileB.yml så här.

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

När fileB.yml är din startpunkt kan du inkludera fileA.yml och fileC.yml så här.

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

fileB.yml Du kan också referera till fileA.yml och fileC.yml använda absoluta sökvägar som den här.

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

Använda andra lagringsplatser

Du kan behålla dina mallar på andra lagringsplatser. Anta till exempel att du har en kärnpipeline som du vill att alla dina apppipelines ska använda. Du kan placera mallen i en kärnlagringsplats och sedan referera till den från var och en av applagringsplatserna:

# 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

Nu kan du återanvända den här mallen i flera pipelines. Använd specifikationen resources för att ange platsen för kärnrepoen. När du refererar till kärndatabasen använder @ du och namnet du gav den i 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'

För type: githubär name <identity>/<repo> som i exemplen ovan. För type: git (Azure Repos) name är <project>/<repo>. Om projektet finns i en separat Azure DevOps-organisation måste du konfigurera en tjänstanslutning av typen Azure Repos/Team Foundation Server med åtkomst till projektet och inkludera den i YAML:

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

Lagringsplatser matchas bara en gång när pipelinen startas. Därefter används samma resurs under pipelinens varaktighet. Endast mallfilerna används. När mallarna har expanderats fullständigt körs den slutliga pipelinen som om den hade definierats helt i källdatabasen. Det innebär att du inte kan använda skript från mallens lagringsplats i pipelinen.

Om du vill använda en viss, fast version av mallen måste du fästa på en ref. är refs antingen grenar (refs/heads/<name>) eller taggar (refs/tags/<name>). Om du vill fästa en specifik incheckning skapar du först en tagg som pekar på incheckningen och fäster sedan på taggen.

Kommentar

Om inget ref anges används pipelinen som standard refs/heads/main.

Du kan också fästa en specifik incheckning i Git med SHA-värdet för en lagringsplatsresurs. SHA-värdet är en hash med 40 teckens kontrollsumma som unikt identifierar incheckningen.

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

Du kan också använda @self för att referera till lagringsplatsen där den ursprungliga pipelinen hittades. Det här är praktiskt att använda i extends mallar om du vill referera tillbaka till innehållet i den utökade pipelinens lagringsplats. Till exempel:

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

Vanliga frågor

Hur kan jag använda variabler i mallar?

Det finns tillfällen då det kan vara användbart att ange parametrar till värden baserat på variabler. Parametrarna expanderas tidigt när en pipelinekörning bearbetas , så alla variabler är inte tillgängliga. Information om vilka fördefinierade variabler som är tillgängliga i mallar finns i Använda fördefinierade variabler.

I det här exemplet används de fördefinierade variablerna Build.SourceBranch och Build.Reason i villkor i 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