Vorlagenausdrücke

Artikel
10/25/2024

Verwenden Sie Vorlagenausdrücke, um anzugeben, wie Werte bei der Pipelineinitialisierung dynamisch aufgelöst werden. Schließen Sie Ihren Vorlagenausdruck in diese Syntax ein: ${{ }}.

Vorlagenausdrücke können Vorlagenparameter und Variablen erweitern. Sie können Parameter verwenden, um die Erweiterung einer Vorlage zu beeinflussen. Das parameters-Objekt funktioniert in einem Ausdruck wie das variables-Objekt. In Vorlagenausdrücken können nur vordefinierte Variablen verwendet werden.

Hinweis

Ausdrücke werden nur für stages, jobs, steps und containers (in resources) erweitert. Sie können beispielsweise keinen Ausdruck in trigger oder einer Ressource wie repositories verwenden. Darüber hinaus können Sie in Azure DevOps 2020 RTW keine Vorlagenausdrücke in containers verwenden.

Sie definieren beispielsweise eine Vorlage:

# 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

Anschließend verweisen Sie auf die Vorlage und übergeben ihr den optionalen Parameter solution:

# File: azure-pipelines.yml

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

Kontext

In einem Vorlagenausdruck haben Sie Zugriff auf den Kontext parameters, der die Werte der übergebenen Parameter enthält. Darüber hinaus haben Sie Zugriff auf den Kontext variables, der alle in der YAML-Datei angegebenen Variablen enthält sowie viele der vordefinierten Variablen (die für jede Variable in diesem Artikel angegeben sind). Vor allem enthält er keine Laufzeitvariablen wie in der Pipeline gespeicherte oder beim Starten einer Ausführung angegebene. Die Vorlagenerweiterung erfolgt zu einem frühen Zeitpunkt in der Ausführung, sodass diese Variablen nicht verfügbar sind.

Vorlagenausdrucksfunktionen

Sie können allgemeine Funktionen in Ihren Vorlagen verwenden. Sie können auch einige Vorlagenausdrucksfunktionen verwenden.

format

Einfaches Ersetzen von Zeichenfolgentoken
Mindestanzahl von Parametern: 2. Höchstanzahl von Parametern: N
Beispiel: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

coalesce

Wird als erstes nicht leeres Zeichenfolgenargument ausgewertet.
Mindestanzahl von Parametern: 2. Höchstanzahl von Parametern: N
Beispiel:

parameters:
- name: 'restoreProjects'
  default: ''
  type: string
- name: 'buildProjects'
  default: ''
  type: string

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

Einfügevorgang

Sie können mithilfe von Vorlagenausdrücken die Struktur einer YAML-Pipeline ändern. Beispiel zum Einfügen in eine Sequenz:

# 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

Wenn ein Array in ein Array eingefügt wird, wird das geschachtelte Array vereinfacht.

Verwenden Sie zum Einfügen in ein Mapping die besondere Eigenschaft ${{ 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

Bedingte Einfügung

Wenn Sie in einer Vorlage etwas bedingt in eine Sequenz oder ein Mapping einfügen möchten, verwenden Sie Einfügungen und die Ausdrucksauswertung. Sie können if-Anweisungen auch außerhalb von Vorlagen verwenden, solange Sie die Vorlagensyntax verwenden.

Beispielsweise können Sie so in einer Vorlage etwas in eine Sequenz einfügen:

# 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

Beispielsweise können Sie so in einer Vorlage etwas in ein Mapping einfügen:

# 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

Sie können die bedingte Einfügung auch für Variablen verwenden. In diesem Beispiel druckt start immer, und this is a test druckt nur dann, wenn die Variable foo gleich test ist.

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

Sie können Variablen auch basierend auf den Werten anderer Variablen festlegen. In der folgenden Pipeline wird myVar verwendet, um den Wert von conditionalVar festzulegen.

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

Iterative Einfügung

Die each-Anweisung ermöglicht das iterative Einfügen basierend auf einer Sequenz (Array) oder einem Mapping (Schlüssel-Wert-Paare) in YAML-Code.

Beispielsweise können Sie die Schritte jedes Auftrags mit anderen Vor- und Nachschritten umschließen:

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

Sie können auch die Eigenschaften des iterierten Elements ändern. Beispielsweise fügen Sie so weitere Abhängigkeiten hinzu:

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

Angeben eines Werts mit Escapezeichen

Wenn Sie einen Wert angeben müssen, der die Zeichen ${{ enthält, umschließen Sie den Wert in eine Ausdruckszeichenfolge. Beispiel: ${{ 'my${{value' }} oder ${{ 'my${{value with a '' single quote too' }}

Freigeben über