Vorlagenausdrücke

Vorlagenausdrücke machen Ihre Azure Pipelines-Vorlagen dynamischer und wiederverwendbarer. Mithilfe von Vorlagenausdrücken können Sie folgende Aktionen ausführen:

• Parametrisieren von Vorlagen: Übergeben Sie Werte an Vorlagen, um ihr Verhalten anzupassen, ohne Code zu duplizieren.
• Konditionale Inhalte einfügen: Dynamisches Hinzufügen oder Ausschließen von Pipelineschritten, Jobs oder Phasen basierend auf Parameterwerten.
• Einfügen und Iterieren über Sammlungen: Generieren mehrerer Pipeline-Elemente aus Arrays oder Schlüssel-Wert-Paaren.
• Wiederholung reduzieren: Erstellen Sie flexible, wiederverwendbare Vorlagen, die in verschiedenen Szenarien und Teams funktionieren.

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. Verwenden Sie Parameter, um zu beeinflussen, wie eine Vorlage erweitert wird. Das parameters-Objekt funktioniert in einem Ausdruck wie das variables-Objekt. In Vorlagenausdrücken können nur vordefinierte Variablen verwendet werden.

Sie definieren beispielsweise eine Vorlage:

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

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

# File: azure-pipelines.yml

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

Kontext

Innerhalb eines Vorlagenausdrucks haben Sie Zugriff auf den parameters Kontext (die Datenmenge, die innerhalb des Ausdrucks verfügbar ist, z. B. Parameter und Variablen, die an die Vorlage übergeben werden), die die Werte der übergebenen Parameter enthalten. 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
• Mindestparameter: 2. Maximale Parameter: N
• Beispiel: ${{ format('{0} Build', parameters.os) }} → 'Windows Build'

verschmelzen

• Wird als erstes nicht leeres Zeichenfolgenargument ausgewertet.
• Mindestparameter: 2. Maximale Parameter: N
• Beispiel:

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

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

Einfügevorgang

Verwenden Sie Vorlagenausdrücke, um die Struktur einer YAML-Pipeline zu ändern. Verwenden Sie beispielsweise den folgenden Ausdruck, um in eine Sequenz einzufügen:

# 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

Wenn Sie ein Array in ein Array einfügen, wird das geschachtelte Array abgeflacht.

Verwenden Sie zum Einfügen in eine Abbildung (eine Sammlung von Schlüssel-Wert-Paaren, ähnlich einem Wörterbuch oder Objekt in YAML) die spezielle Eigenschaft ${{ 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

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: 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

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 Direktive ermöglicht die iterative Einfügung basierend auf einer YAML-Sequenz (Array) oder Zuordnung (Schlüsselwertpaare).

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 Parameter stringList definieren und durchlaufen, die eine Elementeliste enthalten.

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

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 escapen müssen, der buchstäblich enthält ${{, umschließen Sie den Wert in einer Ausdruckszeichenfolge. Verwenden Sie beispielsweise ${{ 'my${{value' }} oder ${{ 'my${{value with a '' single quote too' }}.