Sablon használati referenciája

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

A sablonok lehetővé teszik az újrafelhasználható tartalom, logika és paraméterek meghatározását a YAML-folyamatokban. A sablonok hatékony használatához alapvető ismeretekkel kell rendelkeznie az Azure Pipelines kulcsfontosságú fogalmairól , például a szakaszokról, a lépésekről és a feladatokról.

A sablonok segíthetnek a fejlesztés felgyorsításában. Előfordulhat például, hogy ugyanazon feladatok sorozata szerepel egy sablonban, majd többször is belefoglalja a sablont a YAML-folyamat különböző szakaszaiba.

A sablonok segíthetnek a folyamat biztonságossá tételében is. Amikor egy sablon szabályozza, hogy mi engedélyezett egy folyamatban, a sablon olyan logikát határoz meg, amelyet egy másik fájlnak követnie kell. Előfordulhat például, hogy korlátozni szeretné, hogy mely tevékenységek fussanak. Ehhez a forgatókönyvhöz sablon használatával megakadályozhatja, hogy valaki sikeresen futtasson egy olyan feladatot, amely megsérti a szervezet biztonsági szabályzatait.

Kétféle sablon létezik: tartalmazza és bővíti a sablonokat.

• A sablonokkal újrahasználható tartalmakat szúrhat be sablonnal. Ha egy sablont tartalom belefoglalására használnak, az úgy működik, mint egy belefoglalási irányelv számos programozási nyelven. Az egyik fájl tartalma egy másik fájlba lesz beszúrva.
• Kibővíti a sablonvezérlőt , hogy mi engedélyezett egy folyamatban. Ha egy kiterjesztésű sablon szabályozza, hogy mi engedélyezett egy folyamatban, a sablon olyan logikát határoz meg, amelyet egy másik fájlnak követnie kell.

A sablonok teljes kihasználásához sablonkifejezéseket és sablonparamétereket is használnia kell.

Kiszabott korlátok

A sablonok és sablonkifejezések robbanásszerű növekedést okozhatnak a folyamat méretét és összetettségét illetően. Az Elszabadult növekedés megakadályozása érdekében az Azure Pipelines a következő korlátokat szabja meg:

• Legfeljebb 100 különálló YAML-fájl vehető fel (közvetlenül vagy közvetve)
• A sablonbeágyazás (más sablonokat tartalmazó sablonok) esetében legfeljebb 20 szint engedélyezett
• A YAML elemzése során legfeljebb 10 megabájtnyi memóriát használnak fel (a gyakorlatban ez általában 600 KB – 2 MB lemezen lévő YAML között van, a használt funkcióktól függően)

Kiterjesztés sablonból

A biztonság növelése érdekében kényszerítheti, hogy egy folyamat egy adott sablonból terjedjen ki. A fájl start.yml határozza meg a paramétert buildSteps, amelyet aztán a folyamat azure-pipelines.ymlhasznál. Ebben start.ymlaz esetben, ha egy szkriptlépéssel átad egy buildStep parancsprogramot, a rendszer elutasítja, és a folyamat összeállítása meghiúsul. Ha sablonból bővít, a szükséges sablon-jóváhagyás hozzáadásával növelheti a biztonságot.

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

Kiterjeszthető erőforrásokat tartalmazó sablonból

Az Azure-folyamat erőforrásait tartalmazó sablonból is extends kiterjeszthető.

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

Sablon beszúrása

Egy YAML-ből másolhat tartalmat, és felhasználhatja azt egy másik YAML-ben. Ha tartalmat másol egy YAML-ből egy másikba, azzal nem kell manuálisan belefoglalnia ugyanazt a logikát több helyen. A include-npm-steps.yml fájlsablon olyan lépéseket tartalmaz, amelyek újra felhasználhatók a fájlban azure-pipelines.yml.

Feljegyzés

A sablonfájloknak a folyamatfuttatás kezdetén létezniük kell a fájlrendszerben. Összetevők sablonjaira nem hivatkozhat.

# 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

Lépés újrafelhasználása

Sablon beszúrása több feladat egy vagy több lépésének újrafelhasználásához. A sablon lépésein kívül minden feladat további lépéseket is meghatározhat.

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

Feladat újrafelhasználása

A lépésekhez hasonlóan a feladatok is újra felhasználhatók sablonokkal.

# 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

Ha több feladattal dolgozik, ne felejtse el eltávolítani a feladat nevét a sablonfájlból, hogy elkerülje az ütközést

# 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

Szakasz újrafelhasználása

A szakaszok sablonokkal is újra felhasználhatók.

# 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

Feladat-, szakasz- és lépéssablonok paraméterekkel

# 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

Amikor felhasználja a sablont a folyamatban, adja meg a sablon paramétereinek értékeit.

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

A paramétereket lépés- vagy szakaszsablonokkal is használhatja. Például a paraméterekkel rendelkező lépések:

# 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

Amikor felhasználja a sablont a folyamatban, adja meg a sablon paramétereinek értékeit.

# File: azure-pipelines.yml

steps:
- script: npm install

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

Feljegyzés

A megadott típus nélküli skaláris paraméterek sztringekként vannak kezelve. Például akkor is visszaadja truea függvényt , eq(true, parameters['myparam']) ha a myparam paraméter a szó false, ha myparam nincs explicit módon megadva boolean. A nem üres sztringek logikai környezetbe kerülnek true . A kifejezés átírható a sztringek explicit összehasonlítása érdekében: eq(parameters['myparam'], 'true').

A paraméterek nem korlátozódnak skaláris sztringekre. Tekintse meg az adattípusok listáját. Például a object következő típust használva:

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

Változók újrafelhasználása

A változók definiálhatók egy YAML-ben, és egy másik sablonban is megtalálhatók. Ez akkor lehet hasznos, ha az összes változót egy fájlban szeretné tárolni. Ha egy sablont használ változók folyamatba való belefoglalásához, a belefoglalt sablon csak változók definiálására használható. A sablonból való kibővítéskor lépések és összetettebb logika is használható. A típus korlátozásához használjon paramétereket változók helyett.

Ebben a példában a változó favoriteVeggie szerepel a .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 }}.

Változósablonok paraméterrel

Paramétereket adhat át a változóknak sablonokkal. Ebben a példában a DIRECTORY paramétert egy RELEASE_COMMAND változónak adja át.

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

Amikor felhasználja a sablont a folyamatban, adja meg a sablon paramétereinek értékeit.

# 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

Referenciasablon elérési útjai

A sablon elérési útja lehet abszolút elérési út az adattárban, vagy a benne lévő fájlhoz viszonyítva.

Abszolút elérési út használatához a sablon elérési útjának egy /. Az összes többi elérési út relatívnek minősül.

Íme egy példa beágyazott hierarchiára.

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

Ezután hivatkozhatfileB.yml, fileA.yml és fileC.yml ehhez hasonló.

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

Ha fileC.yml ez a kiindulási pont, akkor ezt is belefoglalhatja fileA.yml , és fileB.yml így is használhatja.

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

Amikor fileB.yml a kiindulási pont, belefoglalhatja fileA.yml és fileC.yml így is használhatja.

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

Alternatív megoldásként fileB.yml hivatkozhat és fileA.ymlfileC.yml használhat ilyen abszolút elérési utakat.

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

Egyéb adattárak használata

A sablonokat más adattárakban is megtarthatja. Tegyük fel például, hogy rendelkezik egy alapfolyamatgal, amelyet az összes alkalmazásfolyamatot használni szeretne. A sablont elhelyezheti egy központi adattárban, majd az egyes alkalmazás-adattárakból is hivatkozhat rá:

# 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

Most már több folyamatban is felhasználhatja ezt a sablont. A specifikáció segítségével resources adja meg a központi adattár helyét. Amikor az alapvető adattárra hivatkozik, használja @ és adja meg resourcesa nevet.

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

Mert type: github, name mint <identity>/<repo> a fenti példákban. Az (Azure Repos) name a type: git következő<project>/<repo>: . Ha a projekt egy külön Azure DevOps-szervezetben található, konfigurálnia kell egy típusú szolgáltatáskapcsolatotAzure Repos/Team Foundation Server a projekthez való hozzáféréssel, és tartalmaznia kell azt a YAML-ben:

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

Az adattárak csak egyszer lesznek feloldva, amikor a folyamat elindul. Ezt követően ugyanazt az erőforrást használja a folyamat időtartamára. A rendszer csak a sablonfájlokat használja. A sablonok teljes kibontása után a végső folyamat úgy fut, mintha teljes egészében a forrásadattárban lett volna definiálva. Ez azt jelenti, hogy nem használhat szkripteket a folyamat sablon-adattárából.

Ha a sablon egy adott, rögzített verzióját szeretné használni, ügyeljen arra, hogy rögzítsen egy ref. Ezek refs vagy ágak (refs/heads/<name>) vagy címkék (refs/tags/<name>). Ha egy adott véglegesítést szeretne rögzíteni, először hozzon létre egy, a véglegesítésre mutató címkét, majd rögzítse a címkét.

Feljegyzés

Ha nincs ref megadva, a folyamat alapértelmezés szerint a következőt használja refs/heads/main: .

Egy adott véglegesítést a Gitben is rögzíthet egy adattárerőforrás SHA-értékével. Az SHA-érték egy 40 karakteres ellenőrzőösszeg kivonat, amely egyedileg azonosítja a véglegesítést.

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

Arra az adattárra is @self hivatkozhat, ahol az eredeti folyamat található. Ez akkor használható a sablonokban extends , ha vissza szeretne hivatkozni a kiterjesztett folyamat adattárában lévő tartalmakra. Példa:

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

GYIK

Hogyan használhatok változókat a sablonokon belül?

Vannak esetek, amikor hasznos lehet a paraméterek beállítása változókon alapuló értékekre. A paraméterek már a folyamatfuttatás feldolgozásakor ki vannak bontva, így nem minden változó érhető el. A sablonokban elérhető előre meghatározott változók megtekintéséhez lásd Az előre meghatározott változók használata című szakaszt.

Ebben a példában az előre definiált változók Build.SourceBranchBuild.Reason szerepelnek a template.yml feltételeiben.

# 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