Sjabloonexpressies

  • Artikel

Gebruik sjabloonexpressies om op te geven hoe waarden dynamisch worden omgezet tijdens de initialisatie van de pijplijn. De sjabloonexpressie in deze syntaxis laten teruglopen: ${{ }}.

Sjabloonexpressies kunnen sjabloonparameters en ook variabelen uitvouwen. U kunt parameters gebruiken om te bepalen hoe een sjabloon wordt uitgebreid. Het parameters object werkt als het variables object in een expressie. Alleen vooraf gedefinieerde variabelen kunnen worden gebruikt in sjabloonexpressies.

Notitie

Expressies worden alleen uitgevouwen voorstages, jobsen stepscontainers (binnenresources). U kunt bijvoorbeeld geen expressie binnen trigger of een resource zoals repositories. Daarnaast kunt u in Azure DevOps 2020 RTW geen sjabloonexpressies binnen gebruiken containers.

U definieert bijvoorbeeld een sjabloon:

# File: steps/msbuild.yml

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

steps:
- task: msbuild@1
  inputs:
    solution: ${{ parameters['solution'] }}  # index syntax
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}  # property dereference syntax

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

# File: azure-pipelines.yml

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

Context

Binnen een sjabloonexpressie hebt u toegang tot de parameters context die de waarden bevat van parameters die zijn doorgegeven. 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 er geen runtimevariabelen zijn, zoals variabelen die zijn opgeslagen in de pijplijn of wanneer u een uitvoering start. Sjabloonuitbreiding vindt vroeg in de uitvoering plaats, zodat deze variabelen niet beschikbaar zijn.

Sjabloonexpressiefuncties

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

indeling

  • Eenvoudige tekenreekstokenvervanging
  • Minimale parameters: 2. Maximum aantal parameters: N
  • Voorbeeld: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

samenvoeging

  • Evalueert naar het eerste niet-lege, niet-null-tekenreeksargument
  • Minimale parameters: 2. Maximum aantal parameters: N
  • Voorbeeld:
parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

steps:
- script: echo ${{ coalesce(parameters.foo, parameters.bar, 'Nothing to see') }}

Invoeging

U kunt sjabloonexpressies gebruiken om de structuur van een YAML-pijplijn te wijzigen. Als u bijvoorbeeld in een reeks wilt invoegen:

# 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: msbuild@1
  - ${{ parameters.preTest }}
  - task: vstest@2
  - ${{ 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 een matrix in een matrix wordt ingevoegd, wordt de geneste matrix afgevlakt.

Als u een toewijzing wilt invoegen, 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: msbuild@1
  - task: vstest@2

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

Voorwaardelijke invoeging

Als u voorwaardelijk wilt invoegen in een reeks of een toewijzing in een sjabloon, gebruikt u invoegingen en expressie-evaluatie. U kunt ook instructies buiten sjablonen gebruiken if 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: msbuild
  type: string
  values:
  - msbuild
  - dotnet

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

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

# File: azure-pipelines.yml

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

Als u bijvoorbeeld wilt invoegen in een toewijzing 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 start wordt altijd afgedrukt en this is a test alleen afgedrukt wanneer de foo variabele gelijk is testaan .

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

Iteratieve invoeging

De each instructie staat iteratieve invoeging toe 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 de eigenschappen bewerken van wat u wilt herhalen. 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. Bijvoorbeeld ${{ 'my${{value' }} of ${{ 'my${{value with a '' single quote too' }}