Ausdrücke

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

Ausdrücke können an vielen Stellen verwendet werden, an denen Sie beim Erstellen einer Pipeline einen Zeichenfolgen-, booleschen oder Zahlenwert angeben müssen. Die häufigste Verwendung von Ausdrücken erfolgt unter Bedingungen , um zu 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 weitere häufige Verwendung von Ausdrücken ist das Definieren von Variablen. Ausdrücke können zur Kompilierzeit oder zur Laufzeit ausgewertet werden. Kompilierungszeitausdrücke können überall verwendet werden. Laufzeitausdrücke können in Variablen und Bedingungen verwendet werden. Laufzeitausdrücke sind als Möglichkeit zum Berechnen des Inhalts von Variablen und Zustand vorgesehen (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 Laufzeit- und Kompilierzeitausdruckssyntaxen besteht in erster Linie im verfügbaren Kontext. In einem Kompilierzeitausdruck (${{ <expression> }}) haben Sie Zugriff auf parameters und statisch definiert variables. In einem Laufzeitausdruck ($[ <expression> ]) haben Sie Zugriff auf mehr variables , aber keine Parameter.

In diesem Beispiel legt ein Laufzeitausdruck den Wert von $(isMain)fest. Eine statische Variable in einem Kompilierungsausdruck 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, ein Verweis auf eine Variable, ein Verweis auf eine Abhängigkeit, eine Funktion oder eine gültige geschachtelte Kombination von diesen sein.

Literale

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

# 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 Wörterbuchfehler zurückgegeben wird, z. B. (variables['noSuch']). Null kann die Ausgabe eines Ausdrucks sein, kann aber nicht direkt in einem Ausdruck aufgerufen werden.

Number

Beginnt mit "-", "." oder "0" bis "9".

String

Muss mit einem einzigen Anführungszeichen angegeben sein. Beispiel: 'this is a string'.

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

Sie können ein Pipezeichen (|) für mehrline Zeichenfolgen verwenden.

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.

Variablen

Als Teil eines Ausdrucks können Sie mit 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:

  • Beginnen Sie mit a-Z oder _
  • Folgen Sie a-Z0-9 oder _

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

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

Variablen sind immer Zeichenfolgen. Wenn Sie typisierte Werte verwenden möchten, sollten Sie stattdessen Parameter verwenden.

Hinweis

Es gibt eine Einschränkung für die Verwendung von Variablen mit Ausdrücken für klassische und YAML-Pipelines beim Einrichten solcher Variablen über die Benutzeroberfläche der Variablenregisterkarte. Variablen, die als Ausdrücke definiert sind, sollten nicht von einer anderen Variablen mit Ausdruck im Wert abhängen, da nicht garantiert ist , dass beide Ausdrücke ordnungsgemäß ausgewertet werden. Beispielsweise haben wir eine Variable a , deren Wert $[ <expression> ] als Teil für den Wert der Variablen bverwendet wird. Da die Reihenfolge der Verarbeitungsvariablen nicht garantiert ist, kann eine Variable b nach der Auswertung einen falschen Wert der Variablen a aufweisen.

Beschriebene Konstruktionen sind nur zulässig, wenn Variablen über das Variablenschlüsselwort in der YAML-Pipeline eingerichtet werden. Es ist erforderlich, die Variablen in der Reihenfolge zu platzieren, in der sie verarbeitet werden sollen, um die richtigen Werte nach der Verarbeitung abzurufen.

Functions

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

und

  • Wertet aus True , wenn alle Parameter sind True
  • Mindestparameter: 2. Max. Parameter: N
  • Wandelt Parameter für die Auswertung in Boolesch um
  • Kurzschlüsse nach der Ersten False
  • Beispiel: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

coalesce

  • Wertet die Parameter in der Reihenfolge aus und gibt den Wert zurück, der nicht gleich NULL oder leere Zeichenfolge ist.
  • Mindestparameter: 2. Max. Parameter: N
  • Beispiel: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

contains

  • Wertet aus True , ob der linke Parameter String den rechten Parameter enthält.
  • Mindestparameter: 2. Max. Parameter: 2
  • Wandelt Parameter zur Auswertung in String um
  • Führt den Ordnungsvergleich zwischen Groß- und Kleinschreibung aus.
  • Beispiel: contains('ABCDE', 'BCD') (gibt True zurück)

containsValue

  • Wertet True aus, ob der linke Parameter ein Array ist und jedes Element dem rechten Parameter entspricht. Außerdem wird ausgewertet True , ob der linke Parameter ein Objekt ist und der Wert einer beliebigen Eigenschaft dem rechten Parameter entspricht.
  • Mindestparameter: 2. Max. Parameter: 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 False für jedes bestimmte Element wird ausgewertet, wenn die Konvertierung fehlschlägt.
  • Ordinaler Ignore-Case-Vergleich für Zeichenfolgen
  • Kurzschlüsse nach dem ersten Spiel

Hinweis

Es gibt keine Literalsyntax in einer YAML-Pipeline zum Angeben eines Arrays. Diese Funktion ist in allgemeinen Pipelines nur eingeschränkt nutzbar. Es ist für die Verwendung im Pipelinedekoratorkontext mit vom System bereitgestellten Arrays wie der Liste der Schritte vorgesehen.

Sie können den containsValue Ausdruck verwenden, um einen übereinstimmenden Wert in einem Objekt zu finden. Hier sehen Sie ein Beispiel, das zeigt, in der Liste der Quell-Branches nach einer Übereinstimmung für Build.SourceBranchzu suchen.

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

  • Nehmen Sie ein komplexes Objekt und gibt es als JSON aus.
  • Mindestparameter: 1. Max. Parameter: 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 kann nur in einem Ausdruck verwendet werden, der eine Variable definiert. Es kann nicht als Teil einer Bedingung für einen Schritt, 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.
  • Präfix ist ein Zeichenfolgenausdruck. Für jeden eindeutigen Präfixwert wird ein separater Wert des Zählers nachverfolgt. Die prefix sollte UTF-16-Zeichen verwenden.
  • Seed ist der Startwert des Indikators.

Sie können einen Zähler erstellen, der bei jeder Ausführung Ihrer Pipeline automatisch um einen inkrementiert wird. Wenn Sie einen Leistungsindikator definieren, geben Sie eine prefix und eine an seed. Hier ist 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)

Der Wert von minor im obigen Beispiel in der ersten Ausführung der Pipeline ist 100. In der zweiten Ausführung ist es 101, vorausgesetzt, der Wert von major ist noch 1.

Wenn Sie die YAML-Datei bearbeiten und den Wert der Variablen major auf 2 aktualisieren, lautet der Wert in minor der nächsten Ausführung der Pipeline 100. Nachfolgende Ausführungen erhöhen den Zähler auf 101, 102, 103, ...

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

Hier ist ein weiteres Beispiel für das Festlegen einer Variablen, die als Zähler fungiert, bei 100 beginnt, für jede Ausführung um 1 erhöht wird 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 Datums- und Uhrzeitobjekt, sodass es für die Arbeit mit Ausdrücken verfügbar ist. Die Standardzeitzone für pipeline.startTime ist UTC. Sie können die Zeitzone für Ihre Organisation ändern.

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

Hier sehen Sie 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)]

Leistungsindikatoren sind auf eine Pipeline ausgerichtet. Anders ausgedrückt: Der Wert wird für jede Ausführung dieser Pipeline erhöht. Es gibt keine projektbezogenen Leistungsindikatoren.

endsWith

  • Wertet aus True , ob der linke Parameter String mit dem rechten Parameter endet.
  • Mindestparameter: 2. Max. Parameter: 2
  • Wandelt Parameter zur Auswertung in String um.
  • Führt einen Ordinal-Ignore-Case-Vergleich aus.
  • Beispiel: endsWith('ABCDE', 'DE') (gibt True zurück)

eq

  • Wertet aus True , ob Die Parameter gleich sind.
  • Mindestparameter: 2. Max. Parameter: 2
  • Konvertiert den rechten Parameter in den Typ des linken Parameters. Gibt zurück False , wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Beispiel: eq(variables.letters, 'ABC')

format

  • Wertet die nachfolgenden Parameter aus und fügt sie in die führende Parameterzeichenfolge ein.
  • Mindestparameter: 1. Max. Parameter: N
  • Beispiel: format('Hello {0} {1}', 'John', 'Doe')
  • Verwendet benutzerdefinierte .NET-Datums- und Uhrzeitformatbezeichner für die Datumsformatierung (yyyy, , mdMHHyyHMMdd, ) ssmmsfffffffK
  • Beispiel: format('{0:yyyyMMdd}', pipeline.startTime). In diesem Fall pipeline.startTime ist eine spezielle Datums-Uhrzeit-Objektvariable.
  • Escape durch Verdoppeln von geschweiften Klammern. Beispiel: format('literal left brace {{ and literal right brace }}')

ge

  • Wertet aus True , ob der linke Parameter größer oder gleich dem rechten Parameter ist.
  • Mindestparameter: 2. Max. Parameter: 2
  • Konvertiert den rechten Parameter in den Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Beispiel: ge(5, 5) (gibt True zurück)

gt

  • Wertet aus True , ob der linke Parameter größer als der rechte Parameter ist.
  • Mindestparameter: 2. Max. Parameter: 2
  • Konvertiert den rechten Parameter in den Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Beispiel: gt(5, 2) (gibt True zurück)

in

  • Wertet aus True , ob der linke Parameter gleich einem beliebigen rechten Parameter ist.
  • Mindestparameter: 1. Max. Parameter: N
  • Konvertiert die rechten Parameter so, dass sie mit dem Typ des linken Parameters übereinstimmen. Der Gleichheitsvergleich wertet False aus, wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Kurzschlüsse nach dem ersten Spiel
  • Beispiel: in('B', 'A', 'B', 'C') (gibt True zurück)

join

  • Verkettet alle Elemente im rechten Parameterarray, getrennt durch die linke Parameterzeichenfolge.
  • Mindestparameter: 2. Max. Parameter: 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, ist das Ergebnis der richtige Parameter, der in eine Zeichenfolge konvertiert wird.

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

  • Wertet aus True , ob der linke Parameter kleiner oder gleich dem rechten Parameter ist.
  • Mindestparameter: 2. Max. Parameter: 2
  • Konvertiert den rechten Parameter in den Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-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 entweder aus dem System stammt oder von einem Parameter stammt.
  • Mindestparameter: 1. Max. Parameter 1
  • Beispiel: Gibt 8 zurück. length('fabrikam')

lower

  • Konvertiert einen Zeichenfolgen- oder Variablenwert in alle Kleinbuchstaben.
  • Mindestparameter: 1. Max. Parameter 1
  • Gibt das Kleinbuchstabenäquivalent einer Zeichenfolge zurück.
  • Beispiel: lower('FOO') gibt zurück foo

lt

  • Wertet aus True , ob der linke Parameter kleiner als der rechte Parameter ist.
  • Mindestparameter: 2. Max. Parameter: 2
  • Konvertiert den rechten Parameter in den Typ des linken Parameters. Fehler, wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Beispiel: lt(2, 5) (gibt True zurück)

ne

  • Wertet aus True , ob Parameter ungleich sind.
  • Mindestparameter: 2. Max. Parameter: 2
  • Konvertiert den rechten Parameter in den Typ des linken Parameters. Gibt zurück True , wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Beispiel: ne(1, 2) (gibt True zurück)

not

  • Wertet aus True , ob der Parameter False
  • Mindestparameter: 1. Max. Parameter: 1
  • Konvertiert den Wert für die Auswertung in einen booleschen Wert.
  • Beispiel: not(eq(1, 2)) (gibt True zurück)

notIn

  • Wertet aus True , ob der linke Parameter nicht gleich einem rechten Parameter ist.
  • Mindestparameter: 1. Max. Parameter: N
  • Konvertiert die rechten Parameter so, dass sie mit dem Typ des linken Parameters übereinstimmen. Der Gleichheitsvergleich wertet False aus, wenn die Konvertierung fehlschlägt.
  • Ordinal ignore-case-vergleich für Zeichenfolgen
  • Kurzschlüsse nach dem ersten Spiel
  • Beispiel: notIn('D', 'A', 'B', 'C') (gibt True zurück)

oder

  • Wertet aus True , ob ein Parameter True
  • Mindestparameter: 2. Max. Parameter: N
  • Wandelt Parameter zur Auswertung in boolesche Werte um.
  • Kurzschlüsse nach dem ersten True
  • Beispiel: or(eq(1, 1), eq(2, 3)) (gibt True zurück, Kurzschlüsse)

replace

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

split

  • Teilt eine Zeichenfolge basierend auf den angegebenen Trennzeichen in Teilzeichenfolgen auf.
  • Mindestparameter: 2. Max. Parameter: 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 nacheinander oder am Ende der Zeichenfolge angezeigt werden.
  • 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

  • Wertet aus True , ob die linke Parameterzeichenfolge mit dem rechten Parameter beginnt.
  • Mindestparameter: 2. Max. Parameter: 2
  • Wandelt Parameter zur Auswertung in String um.
  • Führt einen Ordinal-Ignore-Case-Vergleich aus.
  • Beispiel: startsWith('ABCDE', 'AB') (gibt True zurück)

upper

  • Konvertiert einen Zeichenfolgen- oder Variablenwert in alle Großbuchstaben.
  • Mindestparameter: 1. Max. Parameter 1
  • Gibt die Großbuchstaben-Entsprechung einer Zeichenfolge zurück.
  • Beispiel: upper('bah') gibt zurück BAH

xor

  • Wertet aus True , ob genau ein Parameter ist. True
  • Mindestparameter: 2. Max. Parameter: 2
  • Wandelt Parameter zur Auswertung in boolesche Werte um.
  • Beispiel: xor(True, False) (gibt True zurück)

Auftragsstatusüberprüfungsfunktionen

Sie können die folgenden Statusüberprüfungsfunktionen als Ausdrücke in Bedingungen verwenden, jedoch nicht in Variablendefinitionen.

immer

  • Wird immer als True ausgewertet (auch wenn sie abgebrochen wird). Hinweis: Ein kritischer Fehler kann weiterhin die Ausführung einer Aufgabe verhindern. Beispiel: Quellen konnten nicht abgerufen werden.

canceled

  • Wertet aus True , ob die Pipeline abgebrochen wurde.

„Fehlgeschlagen“

  • Für einen Schritt entspricht eq(variables['Agent.JobStatus'], 'Failed').
  • Für einen Auftrag:
    • Ohne Argumente wird nur ausgewertet True , wenn ein vorheriger Auftrag im Abhängigkeitsdiagramm fehlgeschlagen ist.
    • Wenn Auftragsnamen als Argumente verwendet werden, wird nur ausgewertet True , wenn bei einem dieser Aufträge ein Fehler aufgetreten ist.

succeeded

  • Für einen Schritt entspricht in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Verwenden Sie bei dependsOn der Arbeit mit Aufträgen, und Sie möchten bewerten, 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 wird nur ausgewertet True , wenn alle vorherigen Aufträge im Abhängigkeitsdiagramm erfolgreich oder teilweise erfolgreich waren.
    • Wenn Auftragsnamen als Argumente verwendet werden, wird ausgewertet True , ob alle diese Aufträge erfolgreich oder teilweise erfolgreich waren.
    • Ergibt, False ob die Pipeline abgebrochen wird.

succeededOrFailed

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

  • Für einen Auftrag:

    • Ohne Argumente wird ausgewertet, um unabhängig davon, True ob Aufträge im Abhängigkeitsdiagramm erfolgreich waren oder fehlgeschlagen sind.
    • Wenn Auftragsnamen als Argumente verwendet werden, wird ausgewertet True , ob einer dieser Aufträge erfolgreich war oder fehlgeschlagen ist.

    Dies ist wie always()folgt, es wird jedoch ausgewertet False , wenn die Pipeline abgebrochen wird.

Bedingte Einfügung

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

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

Die elseif Klauseln und else sind ab Azure DevOps 2022 verfügbar und nicht für Azure DevOps Server 2020 und frühere Versionen von Azure DevOps verfügbar.

Bedingungen funktionieren nur, wenn Vorlagensyntax verwendet wird. Erfahren Sie mehr über die Variablensyntax.

Für Vorlagen können Sie die bedingte Einfügung verwenden, wenn Sie eine Sequenz oder Zuordnung hinzufügen. Erfahren Sie mehr über das bedingte 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 kein Variablensatz vorhanden ist oder der Wert von foo nicht mit den if Bedingungen übereinstimmt, wird die else -Anweisung ausgeführt. Hier gibt der Wert von foo true in der elseif Bedingung 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

Sie können das each Schlüsselwort verwenden, um Parameter mit dem Objekttyp durchzuschleifen.

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

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

Abhängigkeiten

Ausdrücke können den Abhängigkeitskontext verwenden, um auf vorherige Aufträge oder Phasen zu verweisen. Sie können Abhängigkeiten für Folgendes verwenden:

  • Verweisen auf den Auftragsstatus eines vorherigen Auftrags
  • Verweisen auf den Phasenstatus einer vorherigen Phase
  • 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 folgenden Phase

Der Kontext wird für Aufträge und Phasen aufgerufen dependencies und funktioniert ähnlich wie Variablen. Wenn Sie innerhalb eines Auftrags auf eine Ausgabevariable eines Auftrags in einer anderen Phase verweisen, wird der Kontext als bezeichnet stageDependencies.

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

Phasen-zu-Phasen-Abhängigkeiten

Strukturell ist das dependencies -Objekt eine Zuordnung von Auftrags- und Phasennamen zu results und outputs. Ausgedrückt als JSON, würde es wie folgt aussehen:

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

Verwenden Sie diese Form von dependencies , um Variablen zuzuordnen oder Bedingungen auf einer Phasenebene zu überprüfen. In diesem Beispiel wird Phase B unabhängig davon ausgeführt, ob Phase A erfolgreich ist oder übersprungen ist.

Hinweis

In den folgenden Beispielen wird die standardmäßige Pipelinesyntax verwendet. Wenn Sie Bereitstellungspipelines verwenden, unterscheiden sich die Syntax von Variablen und bedingten Variablen. Informationen zur zu verwendenden syntax finden Sie unter Bereitstellungsaufträge.

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 hängt Phase B von einer Variablen in Phase A ab.

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 in der YAML-Datei unmittelbar davor ab. Wenn Sie auf eine Phase verweisen müssen, die nicht unmittelbar vor der aktuellen phase liegt, können Sie diese automatische Standardeinstellung überschreiben, indem Sie der Phase einen dependsOn Abschnitt hinzufügen.

Auftrags-zu-Auftrag-Abhängigkeiten 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 wird Auftrag A immer übersprungen, und Auftrag B wird ausgeführt. Auftrag C wird ausgeführt, da alle Abhängigkeiten entweder erfolgreich sind oder übersprungen werden.

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

Auftrags-zu-Auftrag-Abhängigkeiten über Phasen hinweg

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 sie ausgeführt werden soll.

trigger: none

pool:
  vmImage: 'ubuntu-latest'

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 der Bereitstellungsauftrag build_job auf truefestgelegt istrunTests. Beachten Sie, dass der für das outputs Wörterbuch verwendete Schlüssel ist build_job.setRunTests.runTests.

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

Phase abhängig von der Auftragsausgabe

Wenn nach einem Build keine Änderungen erforderlich sind, können Sie eine Phase in einer Pipeline unter bestimmten Bedingungen überspringen. Ein Beispiel hierfür ist, wenn Sie den Terraform-Plan verwenden und die Genehmigung auslösen und nur dann anwenden möchten, wenn der Plan Änderungen enthält.

Wenn Sie diese Bedingung für eine Phase verwenden, müssen Sie die dependencies Variable und nicht stageDependenciesverwenden.

Das folgende Beispiel ist ein einfaches Skript, das eine Variable in einem Schritt in einer Phase festlegt (verwenden Sie Die tatsächlichen Informationen aus dem Terraform-Plan) und dann die zweite Phase nur dann aufruft, wenn die Variable einen bestimmten Wert aufweist.

stages:
- stage: plan_dev
  jobs:
  - job: terraform_plan_dev
    steps:
    - bash: echo '##vso[task.setvariable variable=terraform_plan_exitcode;isOutput=true]2'
      name: terraform_plan
- stage: apply_dev
  dependsOn: plan_dev
  condition: eq(dependencies.plan_dev.outputs['terraform_plan_dev.terraform_plan.terraform_plan_exitcode'], '2')
  jobs:
  - job: part_b
    steps:
    - bash: echo "BA"

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 von der Bereitstellungseinstellung build_jobshouldTest auf ab true. Beachten Sie, dass in der condition der test Phase build_job zweimal angezeigt wird.

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

Im obigen Beispiel verweist die Bedingung auf eine Umgebung und nicht auf eine Umgebungsressource. Um auf eine Umgebungsressource zu verweisen, müssen Sie den Namen der Umgebungsressource der Abhängigkeitsbedingung 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:
    ...

Gefilterte Arrays

Wenn Sie mit einer Auflistung von Elementen arbeiten, können Sie die * Syntax verwenden, um ein gefiltertes Array anzuwenden. Ein gefiltertes Array gibt alle Objekte/Elemente unabhängig von ihren Namen zurück.

Betrachten Sie beispielsweise 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"}
]

Wir haben folgende Möglichkeiten:

foo.*.id

Dadurch wird das System aufgefordert, als gefiltertes Array zu arbeiten foo und dann die id -Eigenschaft auszuwählen.

Dies würde Folgendes zurückgeben:

[ 1, 2, 3 ]

Typ-Umwandlung

Werte in einem Ausdruck können von einem Typ in einen anderen konvertiert werden, wenn der Ausdruck ausgewertet wird. Wenn ein Ausdruck ausgewertet wird, werden die Parameter mit dem relevanten Datentyp zusammengeführt und dann wieder in Zeichenfolgen umgewandelt.

In diesem YAML werden beispielsweise die Werte True und False in und 0 konvertiert1, wenn der Ausdruck ausgewertet wird. Die Funktion lt() gibt zurück True , 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 Werte variables.emptyString und die leere Zeichenfolge als leere Zeichenfolgen ausgewertet. Die Funktion coalesce() wertet die Parameter in der Reihenfolge aus und gibt den ersten Wert zurück, der nicht gleich NULL oder leere Zeichenfolge ist.

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

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

Ausführliche Konvertierungsregeln sind weiter unten aufgeführt.

Von / Bis 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

So nummerieren Sie:

  • False0
  • True1

So führen Sie eine Zeichenfolge aus:

  • False'False'
  • True'True'

NULL

  • Zu Boolean: False
  • So nummerieren Sie: 0
  • An Zeichenfolge: '' (die leere Zeichenfolge)

Number

  • Für Boolean: 0False, jede andere Zahl → True
  • Bis-Version: Muss größer als 0 sein und ein Dezimaltrennzeichen enthalten, das nicht null ist. Muss kleiner als Int32.MaxValue sein (auch dezimale Komponente).
  • In Zeichenfolge: Konvertiert die Zahl in eine Zeichenfolge ohne Tausendertrennzeichen und ohne Dezimaltrennzeichen.

String

  • Für Boolean: '' (die leere Zeichenfolge) → False, jede andere Zeichenfolge → True
  • Zu NULL: '' (die leere Zeichenfolge) → Null, alle anderen Zeichenfolgen, die nicht konvertiert werden können
  • Zum Nummerieren: '' (die leere Zeichenfolge) → 0. Andernfalls werden C#-Werte Int32.TryParse mit InvariantCulture und den folgenden Regeln ausgeführt: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | Allowtrailingwhite. Wenn TryParse ein Fehler auftritt, ist es nicht konvertierbar.
  • Bis-Version: Führt C# aus Version.TryParse. Muss mindestens Haupt- und Nebenkomponenten enthalten. Wenn TryParse ein Fehler auftritt, ist es nicht konvertierbar.

Version

  • Zu Boolean: True
  • Als Zeichenfolge: Major.Minor oder Major.Minor.Build oder Major.Minor.Build.Revision.

Häufig gestellte Fragen

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

Sie können Ihre Pipeline mit einem Skript anpassen, das einen Ausdruck enthält. Dieser Codeausschnitt verwendet beispielsweise die BUILD_BUILDNUMBER Variable und teilt sie mit Bash auf. Dieses Skript gibt zwei neue Variablen und $MAJOR_RUN$MINOR_RUNfür die Haupt- und Nebenlaufnummern aus. Die beiden Variablen werden dann verwendet, $major um zwei Pipelinevariable und $minor mit task.setvariable zu erstellen. Diese Variablen sind für downstream-Schritte verfügbar. Informationen zum freigeben von Variablen über Pipelines hinweg 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)"