Wyrażenia

# 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. Używaj wyrażeń czasu kompilacji w dowolnym miejscu; użyj wyrażeń środowiska uruchomieniowego w zmiennych i warunkach. Użyj wyrażeń środowiska uruchomieniowego, aby obliczyć zawartość 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 zdefiniowanych variables. W wyrażeniu środowiska uruchomieniowego ($[ <expression> ]) masz dostęp do większej liczby variables, ale nie 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

połączyć

• Oblicza parametry w kolejności (od lewej do prawej) i zwraca pierwszą wartość, która nie ma wartości null ani pustego ciągu.
• Zwraca wartość bez wartości, jeśli wszystkie wartości parametrów mają wartość null lub puste ciągi.
• Parametry minimalne: 2. Maksymalna liczba parametrów: N.
• Przykład: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Weź obiekt złożony i przekształć go na format 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"
    ]
  }
}

licznik

• Tej funkcji należy używać tylko w wyrażeniu, które definiuje zmienną. Nie używaj go jako części warunku dla kroku, zadania lub etapu.
• Oblicza liczbę, która zwiększa się przy każdym uruchomieniu potoku.
• Przyjmuje dwa parametry: prefix i seed.
• prefix jest wyrażeniem ciągu. Funkcja śledzi oddzielną wartość licznika dla każdego niepowtarzalnego elementu prefix. Użyj znaków UTF-16 w pliku prefix.
• seed to wartość początkowa licznika.

Możesz utworzyć licznik, który będzie automatycznie zwiększał się o jeden za każdym razem, gdy uruchomisz potok. Podczas definiowania licznika podaj prefix i seed. W poniższym przykładzie przedstawiono tę koncepcję.

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 poprzednim przykładzie to 100 podczas pierwszego uruchomienia potoku. W drugim przebiegu wartość to 101, o ile wartość major pozostaje 1.

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

Jeśli później edytujesz plik YAML i ustawisz wartość major z powrotem na 1, wartości licznika zostaną wznowione od miejsca, w którym została przerwana dla tego prefiksu. W tym przykładzie zostanie wznowione o godzinie 102.

W poniższym przykładzie pokazano, jak ustawić zmienną, która będzie działać jako licznik rozpoczynający się od 100, zwiększający się o 1 przy każdym uruchomieniu i resetujący się do 100 każdego dnia.

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

W poniższym przykładzie przedstawiono licznik, który utrzymuje odrębną wartość dla pull requestów i procesów CI.

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

Liczniki są ograniczone zakresowo do potoku. Innymi słowy, rurociąg zwiększa wartość licznika dla każdego przebiegu. Żadne liczniki nie są objęte zakresem projektu.

układ

• 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 niestandardowych specyfikatorów formatu daty i czasu platformy .NET do formatowania daty (, yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff)
• 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 }}').

Plik IIIF

• Zwraca drugi parametr, jeśli pierwszy parametr zwróci wartość True, a trzeci parametr w przeciwnym razie
• Minimalne parametry: 1. Maksymalna liczba parametrów: 3
• Pierwszy parametr musi być warunkiem
• Przykład: iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') zwraca wartość "ManagedDevOpsPool", gdy potok jest uruchamiany w odpowiedzi na pull request (żądanie ściągnięcia).

dołączyć

• Łączy wszystkie elementy w prawej tablicy parametrów oddzielone ciągiem parametrów po lewej stronie.
• Parametry minimalne: 2. Parametry maksymalne: 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 dodajemy średnik między poszczególnymi elementami 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

dolny

• Konwertuje ciąg lub wartość zmiennej na wszystkie małe litery.
• Parametry minimalne: 1. Parametry maksymalne: 1.
• Zwraca ciąg znaków w postaci małych liter.
• Przykład: lower('FOO') zwraca wartość foo.

zamienić

• Zwraca nowy ciąg, w którym wszystkie wystąpienia ciągu w bieżącym wystąpieniu są zastępowane innym ciągiem.
• Parametry minimalne: 3. Maksymalna liczba parametrów: 3.
• replace(a, b, c): zwraca 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 wartość http://server/saml/consume).

podzielić

• Dzieli ciąg na podciągi na podstawie określonych znaków ograniczników.
• Parametry minimalne: 2. Parametry maksymalne: 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 rozdzielające występują kolejno lub na końcu tekstu.
• 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 }}
  

przycinać

• Zwraca parametr bez wiodących i końcowych białych znaków.
• Minimalne parametry: 1. Maksymalna liczba parametrów: 1
• Przykład: trim(' variable ') zwraca zmienną

górny

• Konwertuje wartość ciągu lub zmiennej na wszystkie wielkie litery
• Parametry minimalne: 1. Parametry maksymalne: 1.
• Zwraca wersję ciągu znaków w wielkich literach
• Przykład: upper('bah') zwraca BAH

Użyj klauzul if, elseif i else, aby warunkowo przypisać wartości zmiennych lub ustawić dane wejściowe dla zadań. Można również warunkowo uruchomić krok, jeśli zostanie spełniony warunek.

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ść foo nie jest zgodna z if warunkami, else instrukcja zostaje wykonana. W tym przykładzie wartość foo zwraca wartość true w warunku elseif.

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

Użyj słowa kluczowego each , aby przeprowadzić pętlę przez parametry z typem obiektu.

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

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

Można również iterować po zagnieżdżonych elementach 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. Użyj zależności, aby:

• Odwołaj się do statusu poprzedniego zadania
• Odwołuje się do stanu poprzedniego etapu
• Odwołuj się do zmiennych wyjściowych w poprzednim zadaniu na tym samym etapie
• Odwołanie do zmiennych wyjściowych z poprzedniego etapu w obecnym etapie.
• Odwołuj się do zmiennych wyjściowych zadania z poprzedniego etapu w następnym etapie.

Kontekst jest określany jako 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.

Składnia zmiennych wyjściowych w zadaniach wdrażania różni się w zależności od strategii wdrażania. Aby uzyskać więcej informacji, zobacz Zadania wdrażania.

Zależności między etapami

Zasadniczo obiekt dependencies jest mapą przypisującą nazwy zadań i etapów do results i outputs. Wygląda na to, że jest wyrażona w formacie JSON:

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

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 nie jest uruchamiany. Etap B jest uruchamiany, jeśli wynik etapu A to Succeeded, SucceededWithIssueslub Skipped. Etap B jest realizowany, 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ą 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 na shouldrun, true etap B 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

Zależności między zadaniami w ramach jednego etapu

Na poziomie zadania w ramach jednego etapu dane dependencies 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 a jest zawsze pomijane z powodu elementu condition: false. Zadanie b działa, ponieważ nie ma powiązanych 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 między zadaniami w różnych etapach

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 zadanie wdrożenia build_job zostało ustawione na runTeststrue. 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 wdrożenia build_job tak, by shouldTest było true. Zwróć uwagę, że w condition etapie testbuild_job 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