Wyrażenia

  • Artykuł

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

Ważne

Wybierz wersję z selektora wersji zawartości usługi Azure DevOps.

Wybierz wersję tego artykułu odpowiadającą twojej platformie i wersji. Selektor wersji znajduje się powyżej spisu treści. Wyszukaj platformę i wersję usługi Azure DevOps.

Wyrażenia mogą być używane w wielu miejscach, w których należy określić wartość ciągu, wartości logicznej lub liczbowej podczas tworzenia potoku. Gdy wyrażenie zwraca tablicę, stosowane są reguły indeksowania normalnego, a indeks zaczyna się od 0.

Najczęstszym zastosowaniem wyrażeń jest określenie, czy zadanie lub krok ma być uruchamiane.

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

Innym typowym zastosowaniem wyrażeń jest definiowanie zmiennych. Wyrażenia można oceniać w czasie kompilacji lub w czasie wykonywania. Wyrażenia czasu kompilacji mogą być używane w dowolnym miejscu; Wyrażenia środowiska uruchomieniowego mogą być używane w zmiennych i warunkach. Wyrażenia środowiska uruchomieniowego są przeznaczone jako sposób obliczania zawartości zmiennych i stanu (na przykład: 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> ]

Różnica między składniami wyrażeń czasu wykonywania i kompilacji jest przede wszystkim tym, jaki kontekst jest dostępny. W wyrażeniu czasu kompilacji (${{ <expression> }}) masz dostęp do parameters i statycznie zdefiniowany variables. W wyrażeniu środowiska uruchomieniowego ($[ <expression> ]) masz dostęp do większej variables liczby parametrów, ale bez parametrów.

W tym przykładzie wyrażenie środowiska uruchomieniowego ustawia wartość $(isMain). Zmienna statyczna w wyrażeniu kompilacji ustawia wartość $(compileVar).

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

Wyrażenie może być literałem, odwołaniem do zmiennej, odwołaniem do zależności, funkcji lub prawidłowej zagnieżdżonej kombinacji tych elementów.

Literały

W ramach wyrażenia można użyć literałów logicznych, null, liczbowych, ciągów lub wersji.

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

Wartość logiczna

True i False są wyrażeniami literału logicznego.

Null (zero)

Null to specjalne wyrażenie literału zwracane ze słownika, na przykład (variables['noSuch']). Wartość null może być wynikiem wyrażenia, ale nie może być wywoływana bezpośrednio w wyrażeniu.

Liczba

Zaczyna się od "-", "." lub "0" do "9".

String

Musi być cytowany pojedynczo. Na przykład: 'this is a string'.

Aby wyrazić literał pojedynczego cudzysłowu, należy go ująć za pomocą pojedynczego cudzysłowu. Na przykład: 'It''s OK if they''re using contractions.'.

Możesz użyć znaku potoku (|) dla ciągów wielowierszowych.

myKey: |
  one
  two
  three

Wersja

Numer wersji z maksymalnie czterema segmentami. Musi zaczynać się od liczby i zawierać dwa lub trzy znaki kropki (.). Na przykład: 1.2.3.4.

Zmienne

W ramach wyrażenia możesz uzyskać dostęp do zmiennych przy użyciu jednej z dwóch składni:

  • Składnia indeksu: variables['MyVar']
  • Składnia wyłusek właściwości: variables.MyVar

Aby można było użyć składni dereference właściwości, nazwa właściwości musi:

  • a-Z Rozpocznij od lub_
  • a-Z0-9 Następnie lub_

W zależności od kontekstu wykonywania dostępne są różne zmienne.

Zmienne są zawsze ciągami. Jeśli chcesz użyć wpisanych wartości, należy zamiast tego użyć parametrów .

Uwaga

Istnieje ograniczenie dotyczące używania zmiennych z wyrażeniami zarówno dla potoków klasycznych, jak i YAML podczas konfigurowania takich zmiennych za pośrednictwem interfejsu użytkownika karty zmiennych. Zmienne zdefiniowane jako wyrażenia nie powinny zależeć od innej zmiennej z wyrażeniem w wartości, ponieważ nie ma gwarancji , że oba wyrażenia będą prawidłowo oceniane. Na przykład mamy zmienną a , której wartość $[ <expression> ] jest używana jako część wartości zmiennej b. Ponieważ kolejność zmiennych przetwarzania nie jest gwarantowana, zmienna może mieć niepoprawną wartość zmiennej ba po ocenie.

Opisane konstrukcje są dozwolone tylko podczas konfigurowania zmiennych za pomocą słowa kluczowego zmiennych w potoku YAML. Należy umieścić zmienne w kolejności, w której powinny zostać przetworzone, aby uzyskać poprawne wartości po przetworzeniu.

Funkcje

Następujące wbudowane funkcje mogą być używane w wyrażeniach.

oraz

  • Ocenia, True czy wszystkie parametry są True
  • Minimalne parametry: 2. Maksymalna liczba parametrów: N
  • Rzutuje parametry na wartość logiczną na potrzeby oceny
  • Zwarcie po raz pierwszy False
  • Przykład: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

Łączonej

  • Oblicza parametry w kolejności (od lewej do prawej) i zwraca pierwszą wartość, która nie jest równa null ani ciągowi pustemu.
  • Żadna wartość nie jest zwracana, jeśli wszystkie wartości parametrów mają wartość null lub puste ciągi.
  • Minimalne parametry: 2. Maksymalna liczba parametrów: N
  • Przykład: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

zawiera

  • Ocenia, czy lewy True parametr String zawiera prawy parametr
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Rzutowanie parametrów na ciąg na potrzeby oceny
  • Wykonuje porównywanie porządkowych przypadków ignoruj wielkość liter
  • Przykład: contains('ABCDE', 'BCD') (zwraca wartość True)

containsValue

  • True Ocenia, czy lewy parametr jest tablicą, a dowolny element jest równy prawy parametr. True Ocenia również, czy lewy parametr jest obiektem, a wartość dowolnej właściwości jest równa prawego parametru.
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Jeśli lewy parametr jest tablicą, przekonwertuj każdy element, aby był zgodny z typem odpowiedniego parametru. Jeśli lewy parametr jest obiektem, przekonwertuj wartość każdej właściwości, aby dopasować typ odpowiedniego parametru. Porównanie równości dla każdego określonego elementu ocenia False , czy konwersja nie powiedzie się.
  • Porównywanie porządkowych przypadków dla ciągów
  • Zwarcie po pierwszym dopasowaniu

Uwaga

W potoku YAML nie ma składni literału służącej do określania tablicy. Ta funkcja jest ograniczona do użytku w potokach ogólnych. Jest przeznaczony do użycia w kontekście dekoratora potoku z tablicami dostarczanymi przez system, takimi jak lista kroków.

Możesz użyć containsValue wyrażenia , aby znaleźć zgodną wartość w obiekcie. Oto przykład przedstawiający wyszukiwanie na liście gałęzi źródłowych dla dopasowania elementu Build.SourceBranch.

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

  • Utwórz obiekt złożony i wyprowadza go w formacie JSON.
  • Minimalne parametry: 1. Maksymalna liczba parametrów: 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) }}

Dane wyjściowe skryptu:

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

counter

  • Tej funkcji można używać tylko w wyrażeniu definiującym zmienną. Nie można jej używać jako części warunku dla kroku, zadania lub etapu.
  • Oblicza liczbę, która jest zwiększana przy każdym uruchomieniu potoku.
  • Parametry: 2. prefix i seed.
  • Prefiks jest wyrażeniem ciągu. Oddzielna wartość licznika jest śledzona dla każdej unikatowej wartości prefiksu. Element prefix powinien używać znaków UTF-16.
  • Inicjator jest wartością początkową licznika

Możesz utworzyć licznik, który jest automatycznie zwiększany o jeden w każdym wykonaniu potoku. Podczas definiowania licznika należy podać element prefix i .seed Oto przykład, który to pokazuje.

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)

Wartość minor w powyższym przykładzie w pierwszym uruchomieniu potoku wynosi 100. W drugim przebiegu jest to 101, pod warunkiem, że wartość major wynosi nadal 1.

Jeśli edytujesz plik YAML i zaktualizujesz wartość zmiennej major na 2, w następnym uruchomieniu potoku wartość minor będzie wynosić 100. Kolejne uruchomienia zwiększają licznik do 101, 102, 103, ...

Później, jeśli edytujesz plik YAML i ustawisz wartość major z powrotem na 1, wartość licznika zostanie wznowione w miejscu, w którym została pozostawiona dla tego prefiksu. W tym przykładzie zostanie wznowione o godzinie 102.

Oto kolejny przykład ustawiania zmiennej do działania jako licznika rozpoczynającego się od 100, zwiększa się o 1 dla każdego przebiegu i jest resetowany do 100 każdego dnia.

Uwaga

pipeline.startTime jest niedostępna poza wyrażeniami. pipeline.startTime formatuje system.pipelineStartTime do obiektu daty i godziny, aby był dostępny do pracy z wyrażeniami. Domyślna strefa czasowa pipeline.startTime to UTC. Możesz zmienić strefę czasową organizacji.

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

Oto przykład posiadania licznika, który utrzymuje oddzielną wartość dla przebiegów żądania ściągnięcia i ciągłej integracji.

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

Liczniki są ograniczone do potoku. Innymi słowy, jego wartość jest zwiększana dla każdego uruchomienia tego potoku. Brak liczników o zakresie projektu.

Endswith

  • Ocenia, czy lewy True parametr Ciąg kończy się prawym parametrem
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Rzutowanie parametrów na ciąg na potrzeby oceny
  • Wykonuje porównywanie porządkowych przypadków ignoruj wielkość liter
  • Przykład: endsWith('ABCDE', 'DE') (zwraca wartość True)

eq

  • True Ocenia, czy parametry są równe
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Konwertuje prawy parametr na zgodny typ lewego parametru. Zwraca wartość False w przypadku niepowodzenia konwersji.
  • Porównywanie porządkowych przypadków dla ciągów
  • Przykład: eq(variables.letters, 'ABC')

format

  • Oblicza końcowe parametry i wstawia je do ciągu wiodącego parametru
  • Minimalne parametry: 1. Maksymalna liczba parametrów: N
  • Przykład: format('Hello {0} {1}', 'John', 'Doe')
  • Używa specyfikatorów formatu daty i godziny niestandardowego platformy .NET do formatowania daty (yyyy, yy, dMMfffffKffsssmHHmmMddH)
  • Przykład: format('{0:yyyyMMdd}', pipeline.startTime). W tym przypadku pipeline.startTime jest to specjalna zmienna obiektu daty i godziny.
  • Ucieczka przez podwojenie nawiasów klamrowych. Na przykład: format('literal left brace {{ and literal right brace }}').

ge

  • Ocenia, czy lewy True parametr jest większy niż lub równy właściwemu parametrowi
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Konwertuje prawy parametr na zgodny typ lewego parametru. Błędy w przypadku niepowodzenia konwersji.
  • Porównywanie porządkowych przypadków dla ciągów
  • Przykład: ge(5, 5) (zwraca wartość True)

gt

  • Ocenia, czy lewy True parametr jest większy niż właściwy parametr
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Konwertuje prawy parametr na zgodny typ lewego parametru. Błędy w przypadku niepowodzenia konwersji.
  • Porównywanie porządkowych przypadków dla ciągów
  • Przykład: gt(5, 2) (zwraca wartość True)

w

  • Ocenia, czy lewy True parametr jest równy dowolnemu właściwemu parametrowi
  • Minimalne parametry: 1. Maksymalna liczba parametrów: N
  • Konwertuje prawe parametry na zgodny typ lewego parametru. Porównanie równości ocenia False , czy konwersja nie powiedzie się.
  • Porównywanie porządkowych przypadków dla ciągów
  • Zwarcie po pierwszym dopasowaniu
  • Przykład: in('B', 'A', 'B', 'C') (zwraca wartość True)

join

  • Łączy wszystkie elementy w prawej tablicy parametrów oddzielone ciągiem parametrów po lewej stronie.
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Każdy element w tablicy jest konwertowany na ciąg. Obiekty złożone są konwertowane na pusty ciąg.
  • Jeśli właściwy parametr nie jest tablicą, wynik jest prawidłowym parametrem przekonwertowanym na ciąg.

W tym przykładzie średnik jest dodawany między poszczególnymi elementami w tablicy. Typ parametru jest obiektem.

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

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

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

le

  • Ocenia, czy lewy True parametr jest mniejszy lub równy prawego parametru
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Konwertuje prawy parametr na zgodny typ lewego parametru. Błędy w przypadku niepowodzenia konwersji.
  • Porównywanie porządkowych przypadków dla ciągów
  • Przykład: le(2, 2) (zwraca wartość True)

length

  • Zwraca długość ciągu lub tablicy, która pochodzi z systemu lub pochodzi z parametru
  • Minimalne parametry: 1. Maksymalna liczba parametrów 1
  • Przykład: length('fabrikam') zwraca wartość 8

Niższe

  • Konwertuje wartość ciągu lub zmiennej na wszystkie małe litery
  • Minimalne parametry: 1. Maksymalna liczba parametrów 1
  • Zwraca małe litery równoważne ciągowi
  • Przykład: lower('FOO') zwraca foo

lt

  • Ocenia, czy lewy True parametr jest mniejszy niż prawy parametr
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Konwertuje prawy parametr na zgodny typ lewego parametru. Błędy w przypadku niepowodzenia konwersji.
  • Porównywanie porządkowych przypadków dla ciągów
  • Przykład: lt(2, 5) (zwraca wartość True)

ne

  • True Ocenia, czy parametry nie są równe
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Konwertuje prawy parametr na zgodny typ lewego parametru. Zwraca wartość True w przypadku niepowodzenia konwersji.
  • Porównywanie porządkowych przypadków dla ciągów
  • Przykład: ne(1, 2) (zwraca wartość True)

not

  • True Ocenia, czy parametr jestFalse
  • Minimalne parametry: 1. Maksymalna liczba parametrów: 1
  • Konwertuje wartość na wartość logiczną na potrzeby oceny
  • Przykład: not(eq(1, 2)) (zwraca wartość True)

notIn

  • Ocenia, czy lewy True parametr nie jest równy żadnemu właściwemu parametrowi
  • Minimalne parametry: 1. Maksymalna liczba parametrów: N
  • Konwertuje prawe parametry na zgodny typ lewego parametru. Porównanie równości ocenia False , czy konwersja nie powiedzie się.
  • Porównywanie porządkowych przypadków dla ciągów
  • Zwarcie po pierwszym dopasowaniu
  • Przykład: notIn('D', 'A', 'B', 'C') (zwraca wartość True)

lub

  • True Ocenia, czy jakikolwiek parametr jestTrue
  • Minimalne parametry: 2. Maksymalna liczba parametrów: N
  • Rzutuje parametry na wartość logiczną na potrzeby oceny
  • Zwarcie po raz pierwszy True
  • Przykład: or(eq(1, 1), eq(2, 3)) (zwraca wartość True, zwarcie)

replace

  • Zwraca nowy ciąg, w którym wszystkie wystąpienia ciągu w bieżącym wystąpieniu są zastępowane innym ciągiem
  • Minimalne parametry: 3. Maksymalna liczba parametrów: 3
  • replace(a, b, c): zwraca wartość a ze wszystkimi wystąpieniami b zastąpionymi przez c
  • Przykład: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (zwraca http://server/saml/consumewartość )

split

  • Dzieli ciąg na podciągi na podstawie określonych znaków ograniczników
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Pierwszy parametr to ciąg do podzielenia
  • Drugi parametr to znaki rozdzielania
  • Zwraca tablicę podciągów. Tablica zawiera puste ciągi, gdy znaki rozdzielania są wyświetlane kolejno lub na końcu ciągu
  • Przykład: 
    variables:
- name: environments
  value: prod1,prod2 
steps:  
  - ${{ each env in split(variables.environments, ',')}}:
    - script: ./deploy.sh --environment ${{ env }}
  • Przykład użycia funkcji split() z funkcją 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

  • Ocenia, czy lewy ciąg parametru True rozpoczyna się od prawego parametru
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Rzutowanie parametrów na ciąg na potrzeby oceny
  • Wykonuje porównywanie porządkowych przypadków ignoruj wielkość liter
  • Przykład: startsWith('ABCDE', 'AB') (zwraca wartość True)

Górnej

  • Konwertuje wartość ciągu lub zmiennej na wszystkie wielkie litery
  • Minimalne parametry: 1. Maksymalna liczba parametrów 1
  • Zwraca wielkie litery odpowiadające ciągowi
  • Przykład: upper('bah') zwraca BAH

xor

  • True Ocenia, czy dokładnie jeden parametr toTrue
  • Minimalne parametry: 2. Maksymalna liczba parametrów: 2
  • Rzutuje parametry na wartość logiczną na potrzeby oceny
  • Przykład: xor(True, False) (zwraca wartość True)

Funkcje sprawdzania stanu zadania

Możesz użyć następujących funkcji sprawdzania stanu jako wyrażeń w warunkach, ale nie w definicjach zmiennych.

zawsze

  • Zawsze ocenia wartość True (nawet w przypadku anulowania). Uwaga: Błąd krytyczny może nadal uniemożliwiać uruchomienie zadania. Na przykład jeśli pobieranie źródeł nie powiodło się.

Anulowane

  • True Ocenia, czy potok został anulowany.

niepowodzenie

  • W przypadku kroku odpowiednik eq(variables['Agent.JobStatus'], 'Failed').
  • W przypadku zadania:
    • Bez argumentów funkcja oblicza wartość tylko True wtedy, gdy jakiekolwiek poprzednie zadanie na wykresie zależności nie powiodło się.
    • W przypadku nazw zadań jako argumentów ocenia się True tylko wtedy, gdy którekolwiek z tych zadań nie powiodło się.

Zakończyła się pomyślnie

  • W przypadku kroku równoważnego in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Użyj polecenia w dependsOn przypadku pracy z zadaniami i chcesz ocenić, czy poprzednie zadanie zakończyło się pomyślnie. Zadania są przeznaczone do równoległego uruchamiania, podczas gdy etapy są uruchamiane sekwencyjnie.
  • W przypadku zadania:
    • Bez argumentów funkcja oblicza wartość tylko wtedy, gdy wszystkie poprzednie zadania na wykresie zależności zakończyły True się powodzeniem lub częściowo powiodło się.
    • W przypadku nazw zadań jako argumentów True ocenia, czy wszystkie te zadania zakończyły się powodzeniem, czy częściowo powiodło się.
    • False Ocenia, czy potok zostanie anulowany.

succeededOrFailed

  • W przypadku kroku równoważnego in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

  • W przypadku zadania:

    • Bez argumentów funkcja ocenia True niezależnie od tego, czy jakiekolwiek zadania w grafie zależności zakończyły się powodzeniem, czy niepowodzeniem.
    • W przypadku nazw zadań jako argumentów True ocenia, czy którekolwiek z tych zadań zakończyło się powodzeniem, czy niepowodzeniem.
    • Zamiast tego możesz użyć not(canceled()) polecenia , jeśli w grafie zależności nie ma poprzednich pominiętych zadań.

    Jest to jak always(), z wyjątkiem tego, że zostanie obliczony False , gdy potok zostanie anulowany.

Wstawianie warunkowe

Można użyć ifklauzul , elseifi else , aby warunkowo przypisać wartości zmiennych lub ustawić dane wejściowe dla zadań podrzędnych. Można również warunkowo uruchomić krok po spełnieniu warunku.

Możesz użyć if polecenia , aby warunkowo przypisać wartości zmiennych lub ustawić dane wejściowe dla zadań podrzędnych. Można również warunkowo uruchomić krok po spełnieniu warunku.

Klauzule elseif i else są dostępne od usługi Azure DevOps 2022 i nie są dostępne dla usługi Azure DevOps Server 2020 i starszych wersji usługi Azure DevOps.

Warunkowe działają tylko w przypadku używania składni szablonu. Dowiedz się więcej o składni zmiennych.

W przypadku szablonów można użyć wstawiania warunkowego podczas dodawania sekwencji lub mapowania. Dowiedz się więcej na temat wstawiania warunkowego w szablonach.

Warunkowe przypisywanie zmiennej

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

Warunkowe ustawianie danych wejściowych zadania

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'

Warunkowe uruchamianie kroku

Jeśli nie ma ustawionej zmiennej lub wartość nie jest zgodna if z foo warunkami, else instrukcja jest uruchamiana. Tutaj wartość foo zwraca wartość true w elseif warunku.

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"

Każde słowo kluczowe

Słowa kluczowego each można użyć do pętli parametrów z typem obiektu.

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

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

Ponadto można iterować przez zagnieżdżone elementy w obiekcie.

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

Zależności

Wyrażenia mogą używać kontekstu zależności, aby odwoływać się do poprzednich zadań lub etapów. Zależności można użyć do:

  • Odwołuje się do stanu zadania poprzedniego zadania
  • Odwołuje się do stanu etapu poprzedniego etapu
  • Odwołuj się do zmiennych wyjściowych w poprzednim zadaniu na tym samym etapie
  • Odwołanie do zmiennych wyjściowych w poprzednim etapie na etapie
  • Odwoływania się do zmiennych wyjściowych w zadaniu w poprzednim etapie na poniższym etapie

Kontekst jest wywoływany dependencies dla zadań i etapów i działa podobnie jak zmienne. Jeśli odwołujesz się do zmiennej wyjściowej z zadania na innym etapie, kontekst jest nazywany stageDependencies.

Jeśli występują problemy ze zmiennymi wyjściowymi z znakami cudzysłowu (' lub ") w nich, zapoznaj się z tym przewodnikiem rozwiązywania problemów.

Omówienie składni zależności

Składnia odwoływania się do zmiennych wyjściowych z zależnościami różni się w zależności od okoliczności. Oto omówienie najbardziej typowych scenariuszy. Czasami składnia alternatywna również działa.

Type

Opis

zależność etapu do etapu (różne etapy)

Odwołanie do zmiennej wyjściowej z poprzedniego etapu zadania w innym etapie w warunku w stages.

  • Składnia: and(succeeded(), eq(stageDependencies.<stage-name>.outputs['<job-name>.<step-name>.<variable-name>'], 'true'))
  • Przykład: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))

zależność zadania do zadania (ten sam etap)

Odwołanie do zmiennej wyjściowej w innym zadaniu w tym samym etapie w stagesprogramie .

  • Składnia: and(succeeded(), eq(dependencies.<job-name>.outputs['<step-name>.<variable-name>'], 'true'))
  • Przykład: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Zależność zadania do etapu (różne etapy)

Odwołanie do zmiennej wyjściowej na innym etapie w obiekcie job.

  • Składnia: eq(stageDependencies.<stage-name>.<job-name>.outputs['<step-name>.<variable-name>'], 'true')
  • Przykład: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')

Zależność etapu do etapu (zadanie wdrożenia)

Odwołanie do zmiennej wyjściowej w zadaniu wdrożenia na innym etapie w stagesprogramie .

  • Składnia: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<deployment-job-name>.<step-name>.<variable-name>'], 'true')
  • Przykład: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')

Zależność etapu do etapu (zadanie wdrożenia z zasobem)

Odwołuje się do zmiennej wyjściowej w zadaniu wdrażania, która zawiera zasób na innym etapie w programie stages.

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

Istnieją również różne składnie zmiennych wyjściowych w zadaniach wdrażania w zależności od strategii wdrażania. Aby uzyskać więcej informacji, zobacz Zadania wdrażania.

Etap do etapu zależności

Strukturalnie dependencies obiekt jest mapą nazw zadań i etapów na results i outputs. W formacie JSON wyglądałoby to następująco:

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

Uwaga

W poniższych przykładach użyto standardowej składni potoku. Jeśli używasz potoków wdrażania, składnia zmiennych i zmiennych warunkowych będzie się różnić. Aby uzyskać informacje o określonej składni do użycia, zobacz Zadania wdrażania.

Użyj tej formy dependencies , aby mapować zmienne lub sprawdzać warunki na poziomie etapu.

W tym przykładzie istnieją dwa etapy: A i B. Etap A ma warunek false i nigdy nie zostanie uruchomiony w wyniku. Etap B jest uruchamiany, jeśli wynik etapu A to Succeeded, SucceededWithIssueslub Skipped. Przebieg etapu B, ponieważ etap A został pominięty.

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

Etapy mogą również używać zmiennych wyjściowych z innego etapu. W tym przykładzie istnieją również dwa etapy. Etap A obejmuje zadanie A1, które ustawia zmienną shouldrun wyjściową na true. Etap B jest uruchamiany, gdy shouldrun ma wartość true. Ze względu shouldrun na to, etap trueB jest uruchamiany.

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

Uwaga

Domyślnie każdy etap w potoku zależy od tego, który jest tuż przed nim w pliku YAML. Jeśli musisz odwołać się do etapu, który nie jest bezpośrednio przed bieżącym etapem, możesz zastąpić tę automatyczną wartość domyślną, dodając sekcję dependsOn do etapu.

Zależności zadania do zadania w ramach jednego etapu

Na poziomie zadania na jednym etapie dependencies dane nie zawierają informacji na poziomie etapu.

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

W tym przykładzie istnieją trzy zadania (a, b i c). Zadanie zawsze zostanie pominięte z powodu elementu condition: false. Zadanie b jest uruchamiane, ponieważ nie ma skojarzonych warunków. Zadanie c jest uruchamiane, ponieważ wszystkie jego zależności kończą się powodzeniem (zadanie b) lub są pomijane (zadanie 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

W tym przykładzie zadanie B zależy od zmiennej wyjściowej z zadania A.

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

Zależności zadania do zadania między etapami

Na poziomie zadania można również odwoływać się do danych wyjściowych z zadania w poprzednim etapie. Wymaga to użycia stageDependencies kontekstu.

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

W tym przykładzie zadanie B1 jest uruchamiane, jeśli zadanie A1 zostanie pominięte. Zadanie B2 sprawdza wartość zmiennej wyjściowej z zadania A1, aby określić, czy ma zostać uruchomiona.

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

Jeśli zadanie zależy od zmiennej zdefiniowanej przez zadanie wdrożenia na innym etapie, składnia jest inna. W poniższym przykładzie zadanie run_tests jest uruchamiane, jeśli build_job zadanie wdrożenia ma wartość truerunTests . Zwróć uwagę, że kluczem używanym dla słownika outputs jest 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:
        ...

Zmienne wyjściowe zadania wdrożenia

Jeśli etap zależy od zmiennej zdefiniowanej przez zadanie wdrożenia na innym etapie, składnia jest inna. W poniższym przykładzie etap test zależy od ustawienia shouldTest wdrożenia build_job na true. Zwróć uwagę, build_job że na conditiontest etapie pojawia się dwa razy.

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

W powyższym przykładzie warunek odwołuje się do środowiska, a nie zasobu środowiska. Aby odwołać się do zasobu środowiska, należy dodać nazwę zasobu środowiska do warunku zależności. W poniższym przykładzie warunek odwołuje się do zasobu maszyny wirtualnej środowiska o nazwie 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

Filtrowane tablice

Podczas działania w kolekcji elementów można użyć * składni, aby zastosować filtrowaną tablicę. Filtrowana tablica zwraca wszystkie obiekty/elementy niezależnie od ich nazw.

Rozważmy na przykład tablicę obiektów o nazwie foo. Chcemy uzyskać tablicę wartości id właściwości w każdym obiekcie w naszej tablicy.

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

Możemy wykonać następujące czynności:

foo.*.id

Spowoduje to, że system będzie działać foo jako filtrowana tablica, a następnie wybierz id właściwość .

Spowoduje to zwrócenie następującej wartości:

[ 1, 2, 3 ]

Rzutowanie typów

Wartości w wyrażeniu mogą być konwertowane z jednego typu na inny, gdy wyrażenie zostanie obliczone. Po obliczeniu wyrażenia parametry są powiązane z odpowiednim typem danych, a następnie zamieniane z powrotem w ciągi.

Na przykład w tym yaML wartości True i False są konwertowane na 1 i 0 po obliczeniu wyrażenia. Funkcja lt() zwraca True wartość , gdy lewy parametr jest mniejszy niż prawy parametr.

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

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

W tym przykładzie wartości variables.emptyString i pusty ciąg są obliczane jako puste ciągi. Funkcja coalesce() oblicza parametry w kolejności i zwraca pierwszą wartość, która nie jest równa null ani ciągowi pustemu.

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

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

Szczegółowe reguły konwersji zostały wymienione poniżej.

Od /Do Wartość logiczna Null (zero) Liczba String Wersja
Wartość logiczna - - Tak Tak -
Null Tak - Tak Tak -
Liczba Tak - - Tak Częściowe
ciąg Tak Częściowe Częściowe - Częściowe
Wersja Tak - - Tak -

Wartość logiczna

Numer do:

  • False → 0
  • True → 1

Ciąg do:

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

Null (zero)

  • Do wartości logicznej: False
  • Numer do: 0
  • Do ciągu: '' (pusty ciąg)

Liczba

  • Do wartości logicznej: 0 → False, dowolna inna liczba → True
  • Wersja: musi być większa niż zero i musi zawierać niezerową liczbę dziesiętną. Musi być mniejsza niż Int32.MaxValue (składnik dziesiętny).
  • Do ciągu: Konwertuje liczbę na ciąg bez separatora tysięcy i bez separatora dziesiętnego.

String

  • Do wartości logicznej: '' (pusty ciąg) → False, dowolny inny ciąg → True
  • Do wartości null: '' (pusty ciąg) → Null, każdy inny ciąg, który nie jest konwertowany
  • Aby numerować: '' (pusty ciąg) → 0, w przeciwnym razie uruchamia język C# Int32.TryParse przy użyciu metody InvariantCulture i następujące reguły: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Jeśli TryParse się nie powiedzie, to nie jest konwertowany.
  • Do wersji: uruchamia środowisko C#s Version.TryParse. Musi zawierać co najmniej składnik główny i pomocniczy. Jeśli TryParse się nie powiedzie, to nie jest konwertowany.

Wersja

  • Do wartości logicznej: True
  • Ciąg: Major.Minor lub Major.Minor.Build lub Major.Minor.Build.Build.Revision.

Często zadawane pytania

Chcę zrobić coś, co nie jest obsługiwane przez wyrażenia. Jakie opcje mam na potrzeby rozszerzania funkcji potoków?

Potok można dostosować za pomocą skryptu zawierającego wyrażenie. Na przykład ten fragment kodu pobiera zmienną BUILD_BUILDNUMBER i dzieli ją na powłokę Bash. Ten skrypt zwraca dwie nowe zmienne i $MAJOR_RUN$MINOR_RUN, dla głównych i pomocniczych numerów przebiegów. Dwie zmienne są następnie używane do tworzenia dwóch zmiennych $major potoku i $minor z parametrem task.setvariable. Te zmienne są dostępne dla kroków podrzędnych. Aby współużytkować zmienne w potokach, zobacz Grupy zmiennych.

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)"