Ausdrücke

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

Wichtig

Wählen Sie die Version dieses Artikels aus, die Ihrer Plattform und Version entspricht. Die Versionsauswahl befindet sich oberhalb des Inhaltsverzeichnisses. Suchen Sie Ihre Azure DevOps-Plattform und -Version.

Ausdrücke können an vielen Stellen verwendet werden, an denen Sie beim Erstellen einer Pipeline eine Zeichenfolge, einen booleschen Wert oder eine Zahl angeben müssen. Wenn ein Ausdruck ein Array zurückgibt, gelten normale Indizierungsregeln, und der Index beginnt mit 0.

Die häufigste Zwecke von Ausdrücken ist in Bedingungen zum Bestimmen, ob ein Auftrag oder Schritt ausgeführt werden soll.

# Expressions are used to define conditions for a step, job, or stage
steps:
- task: ...
  condition: <expression>

Eine weiterer gängiger Zweck von Ausdrücken ist das Definieren von Variablen. Ausdrücke können zur Kompilierzeit oder Laufzeit ausgewertet werden. Kompilierzeitausdrücke können überall, Laufzeitausdrücke in Variablen und Bedingungen verwendet werden. Laufzeitausdrücke dienen als Möglichkeit zum Berechnen des Inhalts von Variablen und Zustand (Beispiel: condition).

# Two examples of expressions used to define variables
# The first one, a, is evaluated when the YAML file is compiled into a plan.
# The second one, b, is evaluated at runtime.
# Note the syntax ${{}} for compile time and $[] for runtime expressions.
variables:
  a: ${{ <expression> }}
  b: $[ <expression> ]

Der Unterschied zwischen der Syntax von Laufzeit- und Kompilierzeitausdrücken besteht hauptsächlich im verfügbaren Kontext. In einem Kompilierzeitausdruck (${{ <expression> }}) haben Sie Zugriff auf parameters und statisch definierte variables. In einem Laufzeitausdruck ($[ <expression> ]) haben Sie Zugriff auf mehr variables, aber nicht auf Parameter.

In diesem Beispiel legt ein Laufzeitausdruck den Wert von $(isMain) fest. Eine statische Variable in einem Kompilierzeitausdruck legt den Wert von $(compileVar) fest.

variables:
  staticVar: 'my value' # static variable
  compileVar: ${{ variables.staticVar }} # compile time expression
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')] # runtime expression

steps:
  - script: |
      echo ${{variables.staticVar}} # outputs my value
      echo $(compileVar) # outputs my value
      echo $(isMain) # outputs True

Ein Ausdruck kann ein Literal, Verweis auf eine Variable, Verweis auf eine Abhängigkeit, eine Funktion oder gültige geschachtelte Kombination dieser Elemente sein.

Literale

Als Teil eines Ausdrucks können Sie boolesche, NULL-, Zahlen-, Zeichenfolgen- oder Versionsliterale angeben.

# Examples
variables:
  someBoolean: ${{ true }} # case insensitive, so True or TRUE also works
  someNumber: ${{ -1.2 }}
  someString: ${{ 'a b c' }}
  someVersion: ${{ 1.2.3 }}

Boolean

True und False sind boolesche Literalausdrücke.

Null

Null ist ein spezieller Literalausdruck, der von einem Fehler im Zusammenhang mit dem Wörterbuch zurückgegeben wird, z. B. (variables['noSuch']). Null kann die Ausgabe eines Ausdrucks sein, die jedoch nicht direkt in einem Ausdruck aufgerufen werden kann.

Anzahl

Beginnt mit „-“, „.“ oder 0 bis 9.

String

Muss in einfache Anführungszeichen eingeschlossen werden. Beispiel: 'this is a string'.

Um ein einzelnes Anführungszeichen auszudrücken, versehen Sie es mit einem einzelnen Anführungszeichen als Escapezeichen. Beispiel: 'It''s OK if they''re using contractions.'.

Sie können für mehrzeilige Zeichenfolgen ein Pipezeichen (|) angeben.

myKey: |
  one
  two
  three

Version

Eine Versionsnummer mit bis zu vier Segmenten. Muss mit einer Zahl beginnen und zwei oder drei Punktzeichen (.) enthalten. Beispiel: 1.2.3.4.

Variables

Als Teil eines Ausdrucks können Sie mithilfe einer von zwei Syntaxen auf Variablen zugreifen:

• Indexsyntax: variables['MyVar']
• Syntax zur Dereferenzierung von Eigenschaften: variables.MyVar

Bei der Syntax zur Dereferenzierung von Eigenschaften muss der Name der Eigenschaft:

• Mit a-Z oder _ beginnen
• a-Z 0-9 Folgen Sie oder_

Je nach Ausführungskontext stehen verschiedene Variablen zur Verfügung.

• Wenn Sie mit YAML Pipelines erstellen, sind Pipelinevariablen verfügbar.
• Wenn Sie mit dem klassischen Editor Buildpipelines erstellen, sind Buildvariablen verfügbar.
• Wenn Sie Releasepipelines mit dem klassischen Editor erstellen, sind Releasevariablen verfügbar.

Variablen sind stets Zeichenfolgen. Wenn Sie typisierte Werte wünschen, sollten Sie stattdessen Parameter verwenden.

Hinweis

Es gibt eine Einschränkung bei der Verwendung von Variablen mit Ausdrücken sowohl für klassische als auch für YAML-Pipelines, wenn Sie solche Variablen über die Registerkarte „Variablen“ auf der Benutzeroberfläche einrichten. Als Ausdrücke definierte Variablen dürfen nicht von einer anderen Variable mit einem Ausdruck im Wert abhängen, da nicht garantiert ist, dass beide Ausdrücke ordnungsgemäß ausgewertet werden. Angenommen, wir haben die Variable a, deren Wert $[ <expression> ] als Teil des Werts der Variable b verwendet wird. Da die Reihenfolge der Verarbeitung von Variablen nicht garantiert ist, kann Variable b nach der Auswertung einen falschen Wert für Variable a aufweisen.

Beschriebene Konstruktionen sind nur zulässig, wenn Variablen über das Schlüsselwort „variables“ in der YAML-Pipeline eingerichtet werden. Sie müssen die Variablen in der Reihenfolge platzieren, in der sie verarbeitet werden sollen, um nach der Verarbeitung die gewünschten Werte zu erhalten.

Functions

Die folgenden integrierten Funktionen können in Ausdrücken verwendet werden.

und

• Wird mit True ausgewertet, wenn alle Parameter True sind.
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: N
• Wandelt Parameter für die Auswertung in boolesche Werte um
• Kurzschluss nach erstem False
• Beispiel: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

coalesce

• Wertet die Parameter in der richtigen Reihenfolge (von links nach rechts) aus und gibt den ersten Wert zurück, der nicht gleich null oder eine leere Zeichenkette ist.
• Es wird kein Wert zurückgegeben, wenn die Parameterwerte null oder leere Zeichenketten sind.
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: N
• Beispiel: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

contains

• Wird mit True ausgewertet, wenn die Zeichenfolge im linken Parameter den rechten Parameter enthält
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Wandelt Parameter zur Auswertung in Zeichenfolge um
• Führt einen OrdinalIgnoreCase-Vergleich durch
• Beispiel: contains('ABCDE', 'BCD') (gibt TRUE zurück)

containsValue

• Wird mit True ausgewertet, wenn der linke Parameter ein Array ist und jedes Element dem rechten Parameter entspricht. Wird auch mit True ausgewertet, wenn der linke Parameter ein Objekt ist und der Wert einer beliebigen Eigenschaft dem rechten Parameter entspricht.
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Wenn der linke Parameter ein Array ist, konvertieren Sie jedes Element so, dass es dem Typ des rechten Parameters entspricht. Wenn der linke Parameter ein Objekt ist, konvertieren Sie den Wert jeder Eigenschaft so, dass er dem Typ des rechten Parameters entspricht. Der Gleichheitsvergleich für jedes spezifische Element wird mit False ausgewertet, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Kurzschluss nach der ersten Übereinstimmung

Hinweis

In einer YAML-Pipeline gibt es keine Literalsyntax zum Angeben eines Arrays. Diese Funktion ist in allgemeinen Pipelines nur von begrenztem Nutzen. Sie ist für die Verwendung im Kontext des Pipelinedecorators mit vom System bereitgestellten Arrays wie der Schrittliste vorgesehen.

Mit dem Ausdruck containsValue können Sie einen übereinstimmenden Wert in einem Objekt ermitteln. Hier ist ein Beispiel dafür, wie in der Liste der Quellbranches nach einer Übereinstimmung für Build.SourceBranch gesucht wird.

parameters:
- name: branchOptions
  displayName: Source branch options
  type: object
  default:
    - refs/heads/main
    - refs/heads/test

jobs:
  - job: A1 
    steps:
    - ${{ each value in parameters.branchOptions }}:
      - script: echo ${{ value }}

  - job: B1 
    condition: ${{ containsValue(parameters.branchOptions, variables['Build.SourceBranch']) }}
    steps:
      - script: echo "Matching branch found"

convertToJson

• Verwendet ein komplexes Objekt und gibt es als JSON aus.
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: 1

parameters:
  - name: listOfValues
    type: object
    default:
      this_is:
        a_complex: object
        with:
          - one
          - two

steps:
- script: |
    echo "${MY_JSON}"
  env:
    MY_JSON: ${{ convertToJson(parameters.listOfValues) }}

Skriptausgabe:

{
  "this_is": {
    "a_complex": "object",
    "with": [
      "one",
      "two"
    ]
  }
}

Zähler

• Diese Funktion eignet sich nur für einen Ausdruck, der eine Variable definiert. Sie kann nicht als Teil einer Bedingung für einen Schritt, einen Auftrag oder eine Phase verwendet werden.
• Wertet eine Zahl aus, die mit jeder Ausführung einer Pipeline erhöht wird.
• Parameter: 2. prefix und seed.
• „prefix“ ist ein Zeichenfolgenausdruck. Für jeden eindeutigen Präfixwert wird ein separater Wert des Zählers nachverfolgt. prefix muss mit UTF-16-Zeichen angegeben werden.
• „seed“ ist der Startwert des Zählers.

Sie können einen Zähler erstellen, der bei jeder Ausführung Ihrer Pipeline automatisch um 1 erhöht wird. Wenn Sie einen Zähler definieren, geben Sie prefix und seed an. Hier sehen Sie ein Beispiel, das dies veranschaulicht.

variables:
  major: 1
  # define minor as a counter with the prefix as variable major, and seed as 100.
  minor: $[counter(variables['major'], 100)]

steps:
- bash: echo $(minor)

Im obigen Beispiel ist der Wert von minor bei der ersten Ausführung der Pipeline 100. Bei der zweiten Ausführung ist der Wert 101, vorausgesetzt, der Wert von major ist weiterhin 1.

Wenn Sie die YAML-Datei bearbeiten und den Wert der Variablen major in 2 ändern, wird bei der nächsten Ausführung der Pipeline der Wert von minor 100 sein. Bei den nachfolgenden Ausführungen wird der Zähler auf 101, 102, 103 usw. heraufgesetzt.

Wenn Sie die YAML-Datei später bearbeiten und den Wert von major auf 1 zurücksetzen, wird der Wert des Zählers dort fortgesetzt, wo er für dieses Präfix aufgehört hat. In diesem Beispiel wird er bei 102 fortgesetzt.

Hier ist ein weiteres Beispiel dafür, wir eine Variable festgelegt wird, die als Zähler fungiert, der bei 100 beginnt und der bei jeder Ausführung um 1 erhöht und jeden Tag auf 100 zurückgesetzt wird.

Hinweis

pipeline.startTime ist außerhalb von Ausdrücken nicht verfügbar. pipeline.startTime formatiert system.pipelineStartTime in ein Datum-/Uhrzeitobjekt, sodass es für das Arbeiten mit Ausdrücken verfügbar ist. Die Standardzeitzone für pipeline.startTime ist UTC. Sie können für Ihre Organisation die Zeitzone ändern.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Hier ist ein Beispiel für einen Zähler, der einen separaten Wert für PRs und CI-Ausführungen verwaltet.

variables:
  patch: $[counter(variables['build.reason'], 0)]

Zähler sind auf eine Pipeline begrenzt. Anders ausgedrückt: Der Wert wird für jede Ausführung dieser Pipeline erhöht. Es gibt keine auf Projekte begrenzten Zähler.

endsWith

• Wird mit True ausgewertet, wenn die Zeichenfolge im linken Parameter mit dem rechten Parameter endet
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Wandelt Parameter zur Auswertung in Zeichenfolge um
• Führt einen OrdinalIgnoreCase-Vergleich durch
• Beispiel: endsWith('ABCDE', 'DE') (gibt TRUE zurück)

eq

• Wird mit True ausgewertet, wenn Parameter gleich sind
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Konvertiert den rechten Parameter entsprechend dem Typ des linken Parameters. Gibt False zurück, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Beispiel: eq(variables.letters, 'ABC')

format

• Wertet die nachstehenden Parameter aus und fügt sie in die führende Parameterzeichenfolge ein
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: N
• Beispiel: format('Hello {0} {1}', 'John', 'Doe')
• Verwendet für die Datumsformatierung benutzerdefinierte .NET-Datums- und Uhrzeitformatbezeichner (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
• Beispiel: format('{0:yyyyMMdd}', pipeline.startTime). In diesem Fall ist pipeline.startTime eine spezielle Datum/-Uhrzeitobjektvariable.
• Verdoppelte geschweifte Klammern dienen als Escapezeichen. Beispiel: format('literal left brace {{ and literal right brace }}')

ge

• Wird mit True ausgewertet, wenn der linke Parameter größer oder gleich dem rechten Parameter ist
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Konvertiert den rechten Parameter entsprechend dem Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Beispiel: ge(5, 5) (gibt TRUE zurück)

gt

• Wird mit True ausgewertet, wenn der linke Parameter größer als der rechte Parameter ist
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Konvertiert den rechten Parameter entsprechend dem Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Beispiel: gt(5, 2) (gibt TRUE zurück)

in

• Wird mit True ausgewertet, wenn der linke Parameter gleich einem beliebigen rechten Parameter ist
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: N
• Konvertiert die rechten Parameter entsprechend dem Typ des linken Parameters. Der Gleichheitsvergleich wird mit False auswertet, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Kurzschluss nach erster Übereinstimmung
• Beispiel: in('B', 'A', 'B', 'C') (gibt TRUE zurück)

join

• Verkettet alle Elemente im rechten Parameterarray, getrennt durch die linke Parameterzeichenfolge.
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Jedes Element im Array wird in eine Zeichenfolge konvertiert. Komplexe Objekte werden in eine leere Zeichenfolge konvertiert.
• Wenn der rechte Parameter kein Array ist, entspricht das Ergebnis dem rechten Parameter, der in eine Zeichenfolge umgewandelt wurde.

In diesem Beispiel wird zwischen jedem Element im Array ein Semikolon hinzugefügt. Der Parametertyp ist ein Objekt.

parameters:
- name: myArray
  type: object
  default:
    - FOO
    - BAR
    - ZOO

variables:
   A: ${{ join(';',parameters.myArray) }}

steps:
  - script: echo $A # outputs FOO;BAR;ZOO

le

• Wird mit True ausgewertet, wenn der linke Parameter kleiner oder gleich dem rechten Parameter ist
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Konvertiert den rechten Parameter entsprechend dem Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Beispiel: le(2, 2) (gibt TRUE zurück)

length

• Gibt die Länge einer Zeichenfolge oder eines Arrays zurück, die/das entweder aus dem System oder von einem Parameter stammt
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: 1
• Beispiel: length('fabrikam') gibt 8 zurück.

lower

• Konvertiert einen Zeichenfolgen- oder Variablenwert durchgängig in Kleinbuchstaben
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: 1
• Gibt das Äquivalent einer Zeichenfolge in Kleinbuchstaben zurück
• Beispiel: lower('FOO') gibt foozurück

lt

• Wird mit True ausgewertet, wenn der linke Parameter kleiner als der rechte Parameter ist
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Konvertiert den rechten Parameter entsprechend dem Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Beispiel: lt(2, 5) (gibt TRUE zurück)

ne

• Wird mit True ausgewertet, wenn Parameter ungleich sind
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Konvertiert den rechten Parameter entsprechend dem Typ des linken Parameters. Gibt True zurück, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Beispiel: ne(1, 2) (gibt TRUE zurück)

not

• Wird mit True ausgewertet, wenn der Parameter False ist
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: 1
• Konvertiert den Wert für die Auswertung in einen booleschen Wert
• Beispiel: not(eq(1, 2)) (gibt TRUE zurück)

notIn

• Wird mit True ausgewertet, wenn der linke Parameter mit keinem der rechten Parameter übereinstimmt
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: N
• Konvertiert die rechten Parameter entsprechend dem Typ des linken Parameters. Der Gleichheitsvergleich wird mit False auswertet, wenn die Konvertierung fehlschlägt.
• OrdinalIgnoreCase-Vergleich für Zeichenfolgen
• Kurzschluss nach erster Übereinstimmung
• Beispiel: notIn('D', 'A', 'B', 'C') (gibt TRUE zurück)

oder

• Wird mit True ausgewertet, wenn ein beliebiger Parameter True ist
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: N
• Wandelt Parameter für die Auswertung in boolesche Werte um
• Kurzschluss nach erstem True
• Beispiel: or(eq(1, 1), eq(2, 3)) (gibt TRUE zurück, Kurzschluss erfolgt)

replace

• Gibt eine neue Zeichenfolge zurück, in der alle Vorkommen einer Zeichenfolge im aktuellen Vorkommen durch eine andere Zeichenfolge ersetzt werden
• Mindestanzahl von Parametern: 3. Maximalanzahl von Parametern: 3
• replace(a, b, c): gibt a zurück, wobei alle Vorkommen von b durch c ersetzt werden
• Beispiel: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (gibt http://server/saml/consume zurück)

split

• Unterteilt eine Zeichenfolge gemäß den angegebenen Trennzeichen in Teilzeichenfolgen
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Der erste Parameter ist die zu teilende Zeichenfolge.
• Der zweite Parameter ist das Trennzeichen.
• Gibt ein Array von Teilzeichenfolgen zurück. Das Array enthält leere Zeichenfolgen, wenn die Trennzeichen hintereinander oder am Ende der Zeichenfolge stehen.
• Beispiel:

  variables:
  - name: environments
    value: prod1,prod2 
  steps:  
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Beispiel für die Verwendung von split() mit replace():

  parameters:
  - name: resourceIds
    type: object
    default:
    - /subscriptions/mysubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/kubernetes-internal
    - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes
  - name: environments
    type: object
    default: 
    - prod1
    - prod2
  
  trigger:
  - main
  
  steps:
  - ${{ each env in parameters.environments }}:
    - ${{ each resourceId in parameters.resourceIds }}:
        - script: echo ${{ replace(split(resourceId, '/')[8], '-', '_') }}_${{ env }}
  

startsWith

• Wird mit True ausgewertet, wenn die Zeichenfolge im linken Parameter mit dem rechten Parameter beginnt
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Wandelt Parameter zur Auswertung in Zeichenfolge um
• Führt einen OrdinalIgnoreCase-Vergleich durch
• Beispiel: startsWith('ABCDE', 'AB') (gibt TRUE zurück)

upper

• Konvertiert einen Zeichenfolgen- oder Variablenwert durchgängig in Großbuchstaben
• Mindestanzahl von Parametern: 1. Maximalanzahl von Parametern: 1
• Gibt das Äquivalent einer Zeichenfolge in Großbuchstaben zurück
• Beispiel: upper('bah') gibt BAH zurück

xor

• Wird mit True ausgewertet, wenn genau ein Parameter True ist
• Mindestanzahl von Parametern: 2. Maximalanzahl von Parametern: 2
• Wandelt Parameter für die Auswertung in boolesche Werte um
• Beispiel: xor(True, False) (gibt TRUE zurück)

Überprüfungsfunktionen für Auftragsstatus

Sie können die folgenden Statusprüfungsfunktionen als Ausdrücke in Bedingungen verwenden, aber nicht in Variablendefinitionen.

immer

• Wird immer mit True ausgewertet (auch bei Abbruch). Hinweis: Ein kritischer Fehler kann weiterhin die Ausführung einer Aufgabe verhindern. Beispiel: Quellen konnten nicht abgerufen werden.

canceled

• Wird mit True ausgewertet, wenn die Pipeline abgebrochen wurde.

„Fehlgeschlagen“

• Für einen Schritt gleichbedeutend mit eq(variables['Agent.JobStatus'], 'Failed').
• Für einen Auftrag:
  • Ohne Argumente erfolgt die Auswertung nur dann mit True, wenn ein vorheriger Auftrag im Abhängigkeitsdiagramm fehlgeschlagen ist.
  • Mit Auftragsnamen als Argumenten erfolgt die Auswertung in True nur, wenn einer dieser Aufträge fehlgeschlagen ist.

succeeded

• Für einen Schritt gleichbedeutend mit in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Mit dependsOn verwenden, wenn Sie mit Aufträgen arbeiten und auswerten möchten, ob ein vorheriger Auftrag erfolgreich war. Aufträge sind so konzipiert, dass sie parallel ausgeführt werden, während Phasen sequenziell ausgeführt werden.
• Für einen Auftrag:
  • Ohne Argumente erfolgt eine Auswertung mit True nur, wenn alle vorherigen Aufträge im Abhängigkeitsdiagramm erfolgreich oder teilweise erfolgreich waren.
  • Mit Auftragsnamen als Argumenten erfolgt eine Auswertung mit True, wenn alle diese Aufträge erfolgreich oder teilweise erfolgreich waren.
  • Wird mit False ausgewertet, wenn die Pipeline abgebrochen wird.

succeededOrFailed

• Für einen Schritt gleichbedeutend mit in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

• Für einen Auftrag:

  • Ohne Argumente erfolgt eine Auswertung mit True unabhängig davon, ob ein Auftrag im Abhängigkeitsdiagramm erfolgreich war oder fehlgeschlagen ist.
  • Mit Auftragsnamen als Argumenten erfolgt eine Auswertung mit True unabhängig davon, ob einer dieser Aufträge erfolgreich war oder fehlgeschlagen ist.
  • Sie können stattdessen not(canceled()) verwenden, wenn es im Abhängigkeitsdiagramm bereits übersprungene Aufträge gibt.

  Dies entspricht always(), außer dass die Auswertung mit False erfolgt, wenn die Pipeline abgebrochen wird.

Bedingte Einfügung

Sie können die Klauseln if, elseif und else verwenden, um Variablenwerte bedingt zuzuweisen oder Eingaben für Aufgaben festzulegen. Sie können auch einen Schritt bedingt ausführen, wenn eine Bedingung erfüllt ist.

Bedingungen funktionieren nur mit Vorlagensyntax. Erfahren Sie mehr zur Syntax von Variablen.

Bei Vorlagen können Sie beim Hinzufügen einer Sequenz oder Zuordnung bedingtes Einfügen verwenden. Erfahren Sie mehr über bedingtes Einfügen in Vorlagen.

Bedingtes Zuweisen einer Variablen

variables:
  ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: # only works if you have a main branch
    stageName: prod

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo ${{variables.stageName}}

Bedingtes Festlegen einer Aufgabeneingabe

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)'
    ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      artifact: 'prod'
    ${{ else }}:
      artifact: 'dev'
    publishLocation: 'pipeline'

Bedingtes Ausführen eines Schritts

Wenn keine Variable festgelegt ist oder der Wert von foo nicht den if Bedingungen entspricht, wird die Anweisung else ausgeführt. Hier gibt der Wert von foo in der elseif-Bedingung TRUE zurück.

variables:
  - name: foo
    value: contoso # triggers elseif condition

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start"
- ${{ if eq(variables.foo, 'adaptum') }}:
  - script: echo "this is adaptum"
- ${{ elseif eq(variables.foo, 'contoso') }}: # true
  - script: echo "this is contoso" 
- ${{ else }}:
  - script: echo "the value is not adaptum or contoso"

Each-Schlüsselwort

Mit dem Schlüsselwort each können Sie Parameter mit dem Objekttyp in einer Schleife durchlaufen.

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

Darüber hinaus können Sie geschachtelte Elemente innerhalb eines Objekts durchlaufen.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Abhängigkeiten

Ausdrücke können anhand des Kontexts der Abhängigkeiten auf vorherige Aufträge oder Phasen verweisen. Sie können Abhängigkeiten für Folgendes verwenden:

• Verweisen auf den Auftragsstatus eines vorherigen Auftrags
• Verweisen auf den Phasenstatus eines vorherigen Auftrags
• Verweisen auf Ausgabevariablen im vorherigen Auftrag in derselben Phase
• Verweisen auf Ausgabevariablen in der vorherigen Phase in einer Phase
• Verweisen auf Ausgabevariablen in einem Auftrag in einer vorherigen Phase in der nachfolgenden Phase

Der Kontext wird für Aufträge und Phasen dependencies genannt und funktioniert ähnlich wie Variablen. Wenn Sie auf eine Ausgabevariable aus einem Auftrag in einer anderen Phase verweisen, wird der Kontext stageDependencies genannt.

Wenn Probleme mit Ausgabevariablen mit Anführungszeichen (' oder ") auftreten, lesen Sie diesen Leitfaden zur Problembehandlung.

Übersicht über die Abhängigkeitssyntax

Die Syntax für die Verweisung auf Ausgabevariablen mit Abhängigkeiten variiert je nach Kontext. Hier ist eine Übersicht über die gängigsten Szenarien. Es kann vorkommen, dass auch die alternative Syntax funktioniert.

Typ

Beschreibung

Abhängigkeit zwischen Phasen (unterschiedliche Phasen)

Verweisen auf eine Ausgabevariable aus einer vorherigen Phase in einem Auftrag in einer anderen Phase in einer Bedingung in stages.

• Syntax: and(succeeded(), eq(stageDependencies.<stage-name>.outputs['<job-name>.<step-name>.<variable-name>'], 'true'))
• Beispiel: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))

Abhängigkeit zwischen Aufträgen (gleiche Phase)

Verweisen auf eine Ausgabevariable in einem anderen Auftrag in derselben Phase in stages.

• Syntax: and(succeeded(), eq(dependencies.<job-name>.outputs['<step-name>.<variable-name>'], 'true'))
• Beispiel: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Abhängigkeit zwischen Auftrag und Phase (unterschiedliche Phasen)

Verweisen auf eine Ausgabevariable in einer anderen Phase in einem job.

• Syntax: eq(stageDependencies.<stage-name>.<job-name>.outputs['<step-name>.<variable-name>'], 'true')
• Beispiel: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')

Abhängigkeit zwischen Phasen (Bereitstellungsauftrag)

Verweisen auf eine Ausgabevariable in einem Bereitstellungsauftrag in einer anderen Phase in stages.

• Syntax: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<deployment-job-name>.<step-name>.<variable-name>'], 'true')
• Beispiel: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')

Abhängigkeit zwischen Phasen (Bereitstellungsauftrag mit Ressource)

Verweisen auf eine Ausgabevariable in einem Bereitstellungsauftrag, der eine Ressource in einer anderen Phase in stages enthält.

• Syntax: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<Deploy_resource-name>.<step-name>.<variable-name>'], 'true')
• Beispiel: eq(dependencies.build.outputs['build_job.Deploy_winVM.setRunTests.runTests'], 'true')

Je nach Bereitstellungsstrategie gibt es auch unterschiedliche Syntaxen für Ausgabevariablen in Bereitstellungsaufträgen. Weitere Informationen finden Sie unter Bereitstellungsaufträge.

Abhängigkeiten von Phase zu Phase

Strukturell ist das dependencies-Objekt eine Zuordnung von Auftrags- und Phasennamen zu results und outputs. Als JSON ausgedrückt sieht es wie folgt:

"dependencies": {
  "<STAGE_NAME>" : {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
        "jobName.stepName.variableName": "value"
    }
  },
  "...": {
    // another stage
  }
}

Hinweis

In den folgenden Beispielen wird die standardmäßige Pipelinesyntax verwendet. Bei Bereitstellungspipelines unterscheiden sich die Syntax von Variablen und bedingten Variablen. Informationen zur jeweiligen Syntax finden Sie unter Bereitstellungsaufträge.

Verwenden Sie diese Form von dependencies, um Variablen zuzuordnen oder Bedingungen auf Phasenebene zu überprüfen.

In diesem Beispiel gibt es zwei Phasen: A und B. Phase A hat die Bedingung false und wird niemals als Ergebnis ausgeführt. Phase B wird ausgeführt, wenn das Ergebnis von Phase A Succeeded, SucceededWithIssues oder Skipped ist. Phase B wird ausgeführt, weil Phase A übersprungen wurde.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Phasen können auch Ausgabevariablen aus einer anderen Phase verwenden. In diesem Beispiel gibt es auch zwei Phasen. Phase A enthält einen Auftrag, A1, der die Ausgabevariable shouldrun auf true festlegt. Phase B wird ausgeführt, wenn shouldrun den Wert true aufweist. Da shouldrun den Wert true hat, wird Phase B ausgeführt.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

Hinweis

Standardmäßig hängt jede Phase in einer Pipeline von der Phase vor ihr in der YAML-Datei ab. Wenn Sie auf eine Phase verweisen müssen, die sich nicht unmittelbar vor der aktuellen befindet, können Sie diese automatische Standardeinstellung außer Kraft setzen, indem Sie der Phase den Abschnitt dependsOn hinzufügen.

Abhängigkeiten von Auftrag zu Auftrag innerhalb einer Phase

Auf Auftragsebene innerhalb einer einzelnen Phase enthalten die dependencies-Daten keine Informationen auf Phasenebene.

"dependencies": {
  "<JOB_NAME>": {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
      "stepName.variableName": "value1"
    }
  },
  "...": {
    // another job
  }
}

In diesem Beispiel gibt es drei Aufträge (a, b und c). Auftrag wird aufgrund der Bedingung condition: false übersprungen. Auftrag b wird ausgeführt, da keine zugeordneten Bedingungen vorhanden sind. Auftrag c wird ausgeführt, da alle Abhängigkeiten entweder erfolgreich (Auftrag b) oder übersprungen werden (Auftrag a).

jobs:
- job: a
  condition: false
  steps:
  - script: echo Job a
- job: b
  steps:
  - script: echo Job b
- job: c
  dependsOn:
  - a
  - b
  condition: |
    and
    (
      in(dependencies.a.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'),
      in(dependencies.b.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
    )
  steps:
  - script: echo Job c

In diesem Beispiel hängt Auftrag B von einer Ausgabevariablen von Auftrag A ab.

jobs:
- job: A
  steps:
  - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
  # or on Windows:
  # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
    name: printvar

- job: B
  condition: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Phasenübergreifende Abhängigkeiten von Auftrag zu Auftrag

Auf Auftragsebene können Sie auch auf Ausgaben eines Auftrags in einer vorherigen Phase verweisen. Dies erfordert die Verwendung des Kontexts stageDependencies.

"stageDependencies": {
  "<STAGE_NAME>" : {
    "<JOB_NAME>": {
      "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
      "outputs": {
          "stepName.variableName": "value"
      }
    },
    "...": {
      // another job
    }
  },
  "...": {
    // another stage
  }
}

In diesem Beispiel wird Auftrag B1 ausgeführt, wenn Auftrag A1 übersprungen wird. Auftrag B2 überprüft den Wert der Ausgabevariablen aus Auftrag A1, um zu bestimmen, ob er ausgeführt werden soll.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  dependsOn: A
  jobs:
  - job: B1
    condition: in(stageDependencies.A.A1.result, 'Skipped') # change condition to `Succeeded and stage will be skipped`
    steps:
    - script: echo hello from Job B1
  - job: B2
    condition: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')
    steps:
     - script: echo hello from Job B2

Wenn ein Auftrag von einer Variablen abhängt, die von einem Bereitstellungsauftrag in einer anderen Phase definiert wird, ist die Syntax anders. Im folgenden Beispiel wird der Auftrag run_tests ausgeführt, wenn runTests vom Bereitstellungsauftrag build_job auf true festgelegt wurde. Beachten Sie, dass der für das Wörterbuch outputs verwendete Schlüssel build_job.setRunTests.runTests ist.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  jobs:  
    - job: run_tests
      condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true')
      steps:
        ...

Ausgabevariablen des Bereitstellungsauftrags

Wenn eine Phase von einer Variablen abhängt, die von einem Bereitstellungsauftrag in einer anderen Phase definiert wird, ist die Syntax anders. Im folgenden Beispiel hängt die Phase test davon ab, dass die Bereitstellung build_job den Wert shouldTest auf true festlegt. Beachten Sie, dass build_job in der condition der Phase test zweimal vorkommt.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')
  jobs:
    - job: A
      steps:
        - script: echo Hello from job A

In dem obigen Beispiel verweist die Bedingung auf eine Umgebung und nicht auf eine Umgebungsressource. Um auf eine Umgebungsressource zu verweisen, müssen Sie der Abhängigkeitsbedingung den Namen der Umgebungsressource hinzufügen. Im folgenden Beispiel verweist die Bedingung auf eine Umgebungs-VM-Ressource namens vmtest.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: vmtest
      resourceName: winVM2
      resourceType: VirtualMachine
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.Deploy_winVM2.setRunTests.runTests'], 'true')
  jobs:
  - job: A
    steps:
     - script: echo Hello from job A

Gefilterte Arrays

Wenn Sie mit einer Sammlung von Elementen arbeiten, können Sie mit der Syntax * ein gefiltertes Array anwenden. Ein gefiltertes Array gibt alle Objekte/Elemente unabhängig von ihren Namen zurück.

Nehmen wir als Beispiel ein Array von Objekten mit dem Namen foo. Wir möchten ein Array der Werte der id -Eigenschaft in jedem Objekt in unserem Array abrufen.

[
    { "id": 1, "a": "avalue1"},
    { "id": 2, "a": "avalue2"},
    { "id": 3, "a": "avalue3"}
]

Sie können dazu so vorgehen:

foo.*.id

Damit wird das System angewiesen, auf foo als gefiltertes Array einzuwirken und dann die id-Eigenschaft auszuwählen.

Die Rückgabe sieht wie folgt aus:

[ 1, 2, 3 ]

Typumwandlung

Werte in einem Ausdruck können von einem Typ in einen anderen konvertiert werden, wenn der Ausdruck ausgewertet wird. Beim Auswerten eines Ausdrucks werden die Parameter in den entsprechenden Datentyp umgewandelt und dann in Zeichenfolgen zurückverwandelt.

In diesem YAML-Beispiel werden die Werte True und False bei der Auswertung des Ausdrucks in 1 und 0 konvertiert. Die Funktion lt() gibt True zurück, wenn der linke Parameter kleiner als der rechte Parameter ist.

variables:
  firstEval: $[lt(False, True)] # 0 vs. 1, True
  secondEval: $[lt(True, False)] # 1 vs. 0, False

steps:
- script: echo $(firstEval)
- script: echo $(secondEval)

In diesem Beispiel werden die variables.emptyString-Werte und die leere Zeichenfolge als leere Zeichenfolgen ausgewertet. Die Funktion coalesce() wertet die Parameter in der richtigen Reihenfolge aus und gibt den ersten Wert zurück, der nicht gleich null oder eine leere Zeichenkette ist.

variables:
  coalesceLiteral: $[coalesce(variables.emptyString, '', 'literal value')]

steps:
- script: echo $(coalesceLiteral) # outputs literal value

Ausführliche Konvertierungsregeln sind weiter unten aufgeführt.

Von/In	Boolean	Null	Number	String	Version
Boolescher Wert	-	-	Ja	Ja	-
NULL	Ja	-	Ja	Ja	-
Number	Ja	-	-	Ja	Teilweise
String	Ja	Teilweise	Partial	-	Partial
Version	Ja	-	-	Ja	-

Boolean

In Zahl:

• False → 0
• True → 1

In Zeichenfolge:

• False → 'False'
• True → 'True'

Null

• In boolesch: False
• In Zahl: 0
• In Zeichenfolge: '' (die leere Zeichenfolge)

Number

• In boolesch: 0 → False, jede andere Zahl → True
• In Version: Muss größer sein als null und muss eine Dezimalzahl enthalten, die nicht gleich null ist. Muss kleiner als Int32.MaxValue (samt dezimaler Komponente) sein.
• In Zeichenfolge: Konvertiert die Zahl in eine Zeichenfolge ohne Tausender- und Dezimaltrennzeichen.

String

• In boolesch: '' (die leere Zeichenfolge) → False, jede andere Zeichenfolge → True
• In NULL: '' (die leere Zeichenfolge) → Null, jede andere nicht konvertierbare Zeichenfolge
• In Zahl: '' (die leere Zeichen) → 0, führt andernfalls Int32.TryParse von C# unter Verwendung von InvariantCulture und den folgenden Regeln aus: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Wenn TryParse fehlschlägt, ist keine Konvertierung möglich.
• In Version: führt Version.TryParse von C# aus. Muss mindestens Major- und Minor-Komponente enthalten. Wenn TryParse fehlschlägt, ist keine Konvertierung möglich.

Version

• In boolesch: True
• In Zeichenfolge: Major.Minor oder Major.Minor.Build oder Major.Minor.Build.Revision.

Häufig gestellte Fragen

Ich möchte etwas tun, das nicht durch Ausdrücke unterstützt wird. Welche Optionen habe ich zum Erweitern der Funktionalität von Pipelines?

Sie können Ihre Pipeline mit einem Skript anpassen, das einen Ausdruck enthält. Beispielsweise verwendet dieser Codeschnipsel die Variable BUILD_BUILDNUMBER und teilt sie mithilfe von Bash auf. Dieses Skript gibt die beiden neuen Variablen $MAJOR_RUNund $MINOR_RUN für die Haupt- und Nebenausführungsnummern aus. Mit den beiden Variablen werden dann die beiden Pipelinevariablen $major und $minor mithilfe von task.setvariable erstellt. Diese Variablen stehen nachgelagerten Schritten zur Verfügung. Informationen zum Freigeben von Variablen für mehrere Pipelines finden Sie unter Variablengruppen.

steps:
- bash: |
    MAJOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f1)
    echo "This is the major run number: $MAJOR_RUN"
    echo "##vso[task.setvariable variable=major]$MAJOR_RUN"

    MINOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f2)
    echo "This is the minor run number: $MINOR_RUN"
    echo "##vso[task.setvariable variable=minor]$MINOR_RUN"

- bash: echo "My pipeline variable for major run is $(major)"
- bash: echo "My pipeline variable for minor run is $(minor)"