Sjabloonexpressies

Met sjabloonexpressies kunt u uw Azure Pipelines-sjablonen dynamischer en herbruikbaarder maken. Met behulp van sjabloonexpressies kunt u het volgende doen:

• Sjablonen parameteriseren: geef waarden door aan sjablonen om hun gedrag aan te passen zonder code te dupliceren.
• Inhoud voorwaardelijk opnemen: pijplijnstappen, taken of fasen dynamisch toevoegen of uitsluiten op basis van parameterwaarden.
• Verzamelingen invoegen en herhalen: meerdere pijplijnelementen genereren op basis van matrices of sleutel-waardeparen.
• Herhaling verminderen: maak flexibele, herbruikbare sjablonen die in verschillende scenario's en teams werken.

Gebruik sjabloonexpressies om op te geven hoe waarden dynamisch worden omgezet tijdens de initialisatie van de pijplijn. Omsluit je sjabloonexpressie binnen deze syntaxis: ${{ }}.

Sjabloonexpressies kunnen sjabloonparameters en -variabelen uitbreiden. Parameters gebruiken om te bepalen hoe een sjabloon wordt uitgevouwen. Het parameters object werkt als het variables object in een expressie. Alleen vooraf gedefinieerde variabelen kunnen worden gebruikt in sjabloonexpressies.

U definieert bijvoorbeeld een sjabloon:

# File: steps/vsbuild.yml

parameters:
- name: 'solution'
  default: '**/*.sln'
  type: string

steps:
- task: VSBuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: VSTest@3
  inputs:
    testSelector: 'testAssemblies' 
    testAssemblyVer2: ${{ parameters.solution }} # property dereference syntax
    searchFolder: '$(System.DefaultWorkingDirectory)' 

Vervolgens verwijst u naar de sjabloon en geeft u deze door aan de optionele solution parameter:

# File: azure-pipelines.yml

steps:
- template: steps/vsbuild.yml
  parameters:
    solution: my.sln

Context

Binnen een sjabloonexpressie hebt u toegang tot de parameters context (de set gegevens die beschikbaar zijn in de expressie, zoals parameters en variabelen die aan de sjabloon worden doorgegeven) die de waarden van doorgegeven parameters bevat. Daarnaast hebt u toegang tot de variables context die alle variabelen bevat die zijn opgegeven in het YAML-bestand plus veel van de vooraf gedefinieerde variabelen (vermeld op elke variabele in dat artikel). Belangrijk is dat het geen runtimevariabelen heeft, zoals die die zijn opgeslagen in de pijplijn of die worden gegeven wanneer u een uitvoering start. Sjabloonuitbreiding vindt vroeg in de uitvoering plaats, zodat deze variabelen niet beschikbaar zijn.

Sjabloon-expressiefuncties

U kunt algemene functies in uw sjablonen gebruiken. U kunt ook enkele sjabloonexpressiefuncties gebruiken.

formaat

• Eenvoudige vervanging van tekenreekstokens
• Minimum parameters: 2. Maximumparameters: N
• Voorbeeld: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

samensmelten

• Evalueert naar het eerste niet-lege, niet-null-tekenreeksargument
• Minimum parameters: 2. Maximumparameters: N
• Voorbeeld:

parameters:
- name: 'customVersion'
  type: string
  default: ''
- name: 'defaultVersion'
  type: string
  default: '1.0.0'

steps:
- script: echo Version is ${{ coalesce(parameters.customVersion, parameters.defaultVersion) }}

Invoeging

Gebruik sjabloonexpressies om de structuur van een YAML-pijplijn te wijzigen. Gebruik bijvoorbeeld de volgende expressie om in een reeks in te voegen:

# File: jobs/build.yml

parameters:
- name: 'preBuild'
  type: stepList
  default: []
- name: 'preTest'
  type: stepList
  default: []
- name: 'preSign'
  type: stepList
  default: []

jobs:
- job: Build
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: cred-scan
  - ${{ parameters.preBuild }}
  - task: VSBuild@1
  - ${{ parameters.preTest }}
  - task: VSTest@3
  - ${{ parameters.preSign }}
  - script: sign

# File: .vsts.ci.yml

jobs:
- template: jobs/build.yml
  parameters:
    preBuild:
    - script: echo hello from pre-build
    preTest:
    - script: echo hello from pre-test

Wanneer u een matrix invoegt in een matrix, wordt de geneste matrix afgevlakt.

Als u wilt invoegen in een mapping (een verzameling van sleutel-waardeparen, vergelijkbaar met een woordenboek of YAML-object), gebruikt u de speciale eigenschap ${{ insert }}.

# Default values
parameters:
- name: 'additionalVariables'
  type: object
  default: {}

jobs:
- job: build
  variables:
    configuration: debug
    arch: x86
    ${{ insert }}: ${{ parameters.additionalVariables }}
  steps:
  - task: VSBuild@1
  - task: VSTest@3

jobs:
- template: jobs/build.yml
  parameters:
    additionalVariables:
      TEST_SUITE: L0,L1

Voorwaardelijke invoeging

Als u voorwaardelijk wilt invoegen in een sequentie of een mapping in een sjabloon, gebruikt u invoeging en expressie-evaluatie. U kunt ook instructies if gebruiken zolang u de syntaxis van de sjabloon gebruikt.

Als u bijvoorbeeld wilt invoegen in een reeks in een sjabloon:

# File: steps/build.yml

parameters:
- name: 'toolset'
  default: vsbuild
  type: string
  values:
  - vsbuild
  - dotnet

steps:
# msbuild
- ${{ if eq(parameters.toolset, 'msbuild') }}:
  - task: VSBuild@1
  - task: VSTest@3

# dotnet
- ${{ if eq(parameters.toolset, 'dotnet') }}:
  - task: UseDotNet@2
    inputs:
      command: build
  - task: UseDotNet@2
    inputs:
      command: test

# File: azure-pipelines.yml

steps:
- template: steps/build.yml
  parameters:
    toolset: dotnet

Als u bijvoorbeeld wilt invoegen in een koppeling in een sjabloon:

# File: steps/build.yml

parameters:
- name: 'debug'
  type: boolean
  default: false

steps:
- script: tool
  env:
    ${{ if eq(parameters.debug, true) }}:
      TOOL_DEBUG: true
      TOOL_DEBUG_DIR: _dbg

steps:
- template: steps/build.yml
  parameters:
    debug: true

U kunt ook voorwaardelijke invoeging gebruiken voor variabelen. In dit voorbeeld wordt start altijd afgedrukt en this is a test alleen wanneer de variabele foo gelijk is aan de waarde van test.

variables:
  - name: foo
    value: test

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.foo, 'test') }}:
  - script: echo "this is a test" # runs when foo=test

U kunt ook variabelen instellen op basis van de waarden van andere variabelen. In de volgende pijplijn wordt myVar gebruikt om de waarde van conditionalVar in te stellen.

trigger:
- main

pool: 
   vmImage: 'ubuntu-latest' 

variables:
  - name: myVar
    value: 'baz'

  - name: conditionalVar
    ${{ if eq(variables['myVar'], 'foo') }}:
      value: 'bar'
    ${{ elseif eq(variables['myVar'], 'baz') }}:
      value: 'qux'
    ${{ else }}:
      value: 'default'

steps:
- script: echo "start" # always runs
- ${{ if eq(variables.conditionalVar, 'bar') }}:
  - script: echo "the value of myVar is set in the if condition" # runs when myVar=foo
- ${{ if eq(variables.conditionalVar, 'qux') }}:
  - script: echo "the value of myVar is set in the elseif condition" # runs when myVar=baz

Iteratieve invoeging

De each instructie maakt iteratieve invoeging mogelijk op basis van een YAML-reeks (matrix) of toewijzing (sleutel-waardeparen).

U kunt bijvoorbeeld de stappen van elke taak verpakken met andere voor- en nastappen:

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This will get sandwiched between SetupMyBuildTools and PublishMyTelemetry.
    - job: B
      steps:
      - script: echo So will this!

U kunt ook gebruiken stringList om parameters te definiëren en herhalen die een lijst met items bevatten.

parameters:
- name: regions
  type: stringList
  displayName: Regions
  values:
    - WUS
    - CUS
    - EUS
  default: 
    - WUS
    - EUS 

stages:
- ${{ each stage in parameters.regions}}:
  - stage: ${{stage}}
    displayName: Deploy to ${{stage}}
    jobs:
    - job:
      steps:
      - script: ./deploy ${{stage}}

U kunt ook de eigenschappen van alles waar u over itereert bewerken. Als u bijvoorbeeld meer afhankelijkheden wilt toevoegen:

# job.yml
parameters:
- name: 'jobs'
  type: jobList
  default: []

jobs:
- job: SomeSpecialTool                # Run your special tool in its own job first
  steps:
  - task: RunSpecialTool@1
- ${{ each job in parameters.jobs }}: # Then do each job
  - ${{ each pair in job }}:          # Insert all properties other than "dependsOn"
      ${{ if ne(pair.key, 'dependsOn') }}:
        ${{ pair.key }}: ${{ pair.value }}
    dependsOn:                        # Inject dependency
    - SomeSpecialTool
    - ${{ if job.dependsOn }}:
      - ${{ job.dependsOn }}

# azure-pipelines.yml
jobs:
- template: job.yml
  parameters:
    jobs:
    - job: A
      steps:
      - script: echo This job depends on SomeSpecialTool, even though it's not explicitly shown here.
    - job: B
      dependsOn:
      - A
      steps:
      - script: echo This job depends on both Job A and on SomeSpecialTool.

Een waarde escapen

Als u een waarde wilt escapen die letterlijk bevat ${{, verpakt u de waarde in een expressietekenreeks. Gebruik bijvoorbeeld ${{ 'my${{value' }} of ${{ 'my${{value with a '' single quote too' }}.