Sdílet prostřednictvím

Výrazy

  • Článek

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

Důležité

Vyberte verzi ze selektoru verze obsahu Azure DevOps.

Vyberte verzi tohoto článku, která odpovídá vaší platformě a verzi. Selektor verzí je nad obsahem dokumentu. Vyhledejte platformu a verzi Azure DevOps.

Výrazy se dají použít na mnoha místech, kde při vytváření kanálu potřebujete zadat řetězec, logickou hodnotu nebo číselnou hodnotu. Když výraz vrátí matici, použijí se normální pravidla indexování a index začíná znakem 0.

Nejběžnější použití výrazů je v podmínkách k určení, jestli se má úloha nebo krok spustit.

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

Dalším běžným použitím výrazů je definování proměnných. Výrazy lze vyhodnotit v době kompilace nebo v době běhu. Výrazy času kompilace lze použít kdekoli; Výrazy modulu runtime lze použít v proměnných a podmínkách. Výrazy modulu runtime jsou určeny jako způsob, jak vypočítat obsah proměnných a stavu (například: 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> ]

Rozdíl mezi syntaxí výrazů za běhu a kompilace je primárně tím, jaký kontext je k dispozici. Ve výrazu vyhodnocovaném při kompilaci (${{ <expression> }}) máte přístup k parameters a staticky definovaným variables. Ve výrazu modulu runtime ($[ <expression> ]) máte přístup k více variables položkám, ale k žádným parametrům.

V tomto příkladu výraz modulu runtime nastaví hodnotu $(isMain). Statická proměnná ve výrazu kompilace nastaví hodnotu $(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

Výraz může být literál, odkaz na proměnnou, odkaz na závislost, funkci nebo platnou vnořenou kombinaci.

Literály

Jako součást výrazu můžete použít logické literály, hodnoty null, číslo, řetězec nebo literály verze.

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

Logická hodnota

True a False jsou logické literální výrazy.

Null

Null je speciální literálový výraz vrácený ze slovníku, například (variables['noSuch']). Hodnota Null může být výstupem výrazu, ale nelze ji volat přímo ve výrazu.

Počet

Začíná na -, .nebo 0 až 9.

Řetězec

Musí být v jednoduchých uvozovkách. Například: 'this is a string'.

Pokud chcete vyjádřit literální jednoduchý apostrof, unikněte ho dalším jednoduchým apostrofem. Například: 'It''s OK if they''re using contractions.'.

Znak svislé čáry (|) můžete použít pro víceřádkové řetězce.

myKey: |
  one
  two
  three

Verze

Číslo verze, které má až čtyři segmenty. Musí začínat číslem a obsahovat dva nebo tři znaky tečky (.). Například: 1.2.3.4.

Proměnné

Jako součást výrazu můžete přistupovat k proměnným pomocí jedné ze dvou syntaxí:

  • Syntaxe indexu: variables['MyVar']
  • Syntaxe dereference vlastností: variables.MyVar

Aby bylo možné použít syntaxi dereference vlastností, musí název vlastnosti:

  • Začít od a-Z nebo _
  • Mělo by následovat a-Z0-9 nebo _

V závislosti na kontextu spuštění jsou k dispozici různé proměnné.

  • Pokud vytváříte kanály pomocí YAML, jsou k dispozici proměnné kanálu.
  • Pokud vytváříte kanály sestavení pomocí klasického editoru, jsou k dispozici proměnné sestavení.
  • Pokud vytváříte vydávací kanály pomocí klasického editoru, jsou proměnné vydání k dispozici.

Proměnné jsou vždy řetězce. Pokud chcete použít typové hodnoty, měli byste místo toho použít parametry .

Poznámka:

Při nastavování těchto proměnných prostřednictvím záložky proměnných v uživatelském rozhraní platí omezení pro použití proměnných s výrazy pro klasické i YAML kanály. Proměnné definované jako výrazy by neměly záviset na jiné proměnné s výrazem v hodnotě, protože není zaručeno , že oba výrazy budou vyhodnoceny správně. Například máme proměnnou a , jejíž hodnota $[ <expression> ] se používá jako součást pro hodnotu proměnné b. Vzhledem k tomu, že pořadí zpracovávaných proměnných není zaručené, b může mít po vyhodnocení nesprávnou hodnotu proměnné a .

Popsané konstrukce jsou povoleny pouze při nastavování proměnných prostřednictvím klíčového slova variables v YAML pipeline. Je nutné umístit proměnné do pořadí, v jakém by se měly zpracovat, aby se po zpracování získaly správné hodnoty.

Funkce

Ve výrazech lze použít následující předdefinované funkce.

a

  • Vyhodnotí na True, pokud jsou všechny parametry True
  • Minimální parametry: 2. Maximální parametry: N
  • Převádí parametry na logické hodnoty k účelům vyhodnocení.
  • Zkraty po prvním False
  • Příklad: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

sloučit

  • Vyhodnotí parametry v pořadí (zleva doprava) a vrátí první hodnotu, která se nerovná hodnotě null nebo prázdný řetězec.
  • Není vrácena žádná hodnota, pokud všechny hodnoty parametrů mají hodnotu null nebo prázdné řetězce.
  • Minimální parametry: 2. Maximální parametry: N
  • Příklad: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

obsahuje

  • True Vyhodnotí, jestli řetězec levého parametru obsahuje správný parametr.
  • Minimální parametry: 2. Maximální parametry: 2
  • Přetypuje parametry do řetězce pro vyhodnocení.
  • Provede porovnání řadových případů ignorování.
  • Příklad: contains('ABCDE', 'BCD') (vrátí hodnotu True)

obsahujeHodnotu

  • True Vyhodnotí, jestli je levý parametr pole a jakákoli položka se rovná správnému parametru. Také vyhodnotí True , zda levý parametr je objekt a hodnota jakékoli vlastnosti se rovná správnému parametru.
  • Minimální parametry: 2. Maximální parametry: 2
  • Pokud je levý parametr pole, převeďte každou položku tak, aby odpovídala typu pravého parametru. Pokud je levý parametr objekt, převeďte hodnotu každé vlastnosti tak, aby odpovídala typu pravého parametru. Porovnání rovnosti pro každou konkrétní položku False se vyhodnotí, pokud převod selže.
  • Porovnání řadových případů přeskakování u řetězců
  • Zkraty po prvním zápasu

Poznámka:

V rámci YAML pipeline neexistuje žádná doslovná syntaxe pro zadání pole. Tato funkce je omezena v obecných kanálech. Je určen pro použití v kontextu dekoračního kontextu potrubí s poli poskytovanými systémem, jako je seznam kroků.

Pomocí výrazu containsValue můžete najít odpovídající hodnotu v objektu. Tady je příklad, který ukazuje hledání v seznamu zdrojových větví pro shodu pro 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

  • Vezme složitý objekt a vypíše ho jako JSON.
  • Minimální parametry: 1. Maximální parametry: 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) }}

Výstup skriptu:

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

counter

  • Tuto funkci lze použít pouze ve výrazu, který definuje proměnnou. Nedá se použít jako součást podmínky pro krok, úlohu nebo fázi.
  • Vyhodnotí číslo, které se zvýší při každém spuštění kanálu.
  • Parametry: 2. prefix a seed.
  • Předpona je řetězcový výraz. Pro každou unikátní hodnotu předpony je sledována samostatná hodnota čítače. Mělo by prefix používat znaky UTF-16.
  • Počáteční hodnota (nebo semeno) čítače

Můžete vytvořit čítač, který se při každém spuštění vašeho kanálu automaticky zvýší o jedno. Při definování čítače zadáte prefix a seed. Tady je příklad, který to ukazuje.

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)

Hodnota minor v předchozím příkladu při prvním spuštění potrubí je 100. Ve druhém spuštění je to 101 za předpokladu, že hodnota major je stále 1.

Pokud upravíte soubor YAML a aktualizujete hodnotu proměnné major na hodnotu 2, pak v dalším spuštění kanálu bude hodnota minor 100. Následné spuštění zvýší čítač na 101, 102, 103, ...

Pokud později upravíte soubor YAML a nastavíte hodnotu major zpět na hodnotu 1, hodnota čítače se obnoví tam, kde pro tuto předponu skončila. V tomto příkladu se obnoví na 102.

Tady je další příklad nastavení proměnné tak, aby fungovala jako čítač, který začíná na 100, se pro každé spuštění zvýší o 1 a každý den se resetuje na 100.

Poznámka:

pipeline.startTime není k dispozici mimo výrazy. pipeline.startTime formátuje system.pipelineStartTime do objektu data a času, aby byl k dispozici pro práci s výrazy. Výchozí časové pásmo je pipeline.startTime UTC. Časové pásmo pro vaši organizaci můžete změnit.

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

Tady je příklad čítače, který udržuje samostatnou hodnotu pro PR a běhy CI.

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

Čítače jsou vymezeny na pipeline. Jinými slovy, jeho hodnota se zvýší při každém spuštění tohoto řetězce. Neexistují žádné čítače ve specifikaci projektu.

končí na

  • True Vyhodnotí, jestli řetězec levého parametru končí pravým parametrem.
  • Minimální parametry: 2. Maximální parametry: 2
  • Přetypuje parametry na řetězec pro vyhodnocení.
  • Provede porovnání řadových případů ignorování.
  • Příklad: endsWith('ABCDE', 'DE') (vrátí hodnotu True)

eq

  • True Vyhodnotí, jestli jsou parametry stejné.
  • Minimální parametry: 2. Maximální parametry: 2
  • Převede pravý parametr tak, aby odpovídal typu levého parametru. Vrátí False , pokud převod selže.
  • Porovnání řadových případů přeskakování u řetězců
  • Příklad: eq(variables.letters, 'ABC')

formát

  • Vyhodnotí koncové parametry a vloží je do řetězce úvodního parametru.
  • Minimální parametry: 1. Maximální parametry: N
  • Příklad: format('Hello {0} {1}', 'John', 'Doe')
  • Používá specifikátory vlastního formátu data a času pro formátování dat v .NET (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
  • Příklad: format('{0:yyyyMMdd}', pipeline.startTime). V tomto případě pipeline.startTime je speciální proměnná objektu data a času.
  • Vynechejte pomocí zdvojení závorek. Příklad: format('literal left brace {{ and literal right brace }}')

ge

  • True Vyhodnotí, jestli je levý parametr větší nebo roven správnému parametru.
  • Minimální parametry: 2. Maximální parametry: 2
  • Převede pravý parametr tak, aby odpovídal typu levého parametru. Chyby v případě selhání převodu
  • Porovnání řadových případů přeskakování u řetězců
  • Příklad: ge(5, 5) (vrátí hodnotu True)

gt

  • True Vyhodnotí, jestli je levý parametr větší než správný parametr.
  • Minimální parametry: 2. Maximální parametry: 2
  • Převede pravý parametr tak, aby odpovídal typu levého parametru. Chyby v případě selhání převodu
  • Porovnání řadových případů přeskakování u řetězců
  • Příklad: gt(5, 2) (vrátí hodnotu True)

v

  • True Vyhodnotí, jestli je levý parametr roven libovolnému správnému parametru.
  • Minimální parametry: 1. Maximální parametry: N
  • Převede správné parametry tak, aby odpovídaly typu levého parametru. Porovnání rovnosti se vyhodnotí pouze tehdy, pokud převod selže.
  • Porovnání řadových případů přeskakování u řetězců
  • Zkraty po první shodě
  • Příklad: in('B', 'A', 'B', 'C') (vrátí hodnotu True)

iif

  • Vrátí druhý parametr, pokud se první parametr vyhodnotí jako Truea třetí parametr otherwize.
  • Minimální parametry: 1. Maximální parametry: 3
  • Prvním parametrem musí být podmínka.
  • Příklad: iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') vrátí hodnotu 'ManagedDevOpsPool', když se potrubí spustí v reakci na návrh na sloučení.

připojit se

  • Zřetězí všechny prvky v pravém poli parametrů oddělené řetězcem levého parametru.
  • Minimální parametry: 2. Maximální parametry: 2
  • Každý prvek v poli je převeden na řetězec. Komplexní objekty se převedou na prázdný řetězec.
  • Pokud správný parametr není pole, je výsledkem správný parametr převedený na řetězec.

V tomto příkladu se mezi každou položku v poli přidá středník. Typ parametru je objekt.

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

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

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

le

  • True Vyhodnotí, jestli je levý parametr menší nebo roven správnému parametru.
  • Minimální parametry: 2. Maximální parametry: 2
  • Převede pravý parametr tak, aby odpovídal typu levého parametru. Chyby v případě selhání převodu
  • Porovnání řadových případů přeskakování u řetězců
  • Příklad: le(2, 2) (vrátí hodnotu True)

délka

  • Vrátí délku řetězce nebo pole, buď z systému, nebo z parametru.
  • Minimální parametry: 1. Maximální počet parametrů 1
  • Příklad: vrátí hodnotu 8. length('fabrikam')

nižší

  • Převede hodnotu řetězce nebo proměnné na všechna malá písmena.
  • Minimální parametry: 1. Maximální počet parametrů 1
  • Vrátí ekvivalent malého písmena řetězce.
  • Příklad: lower('FOO') vrátí foo

lt

  • True Vyhodnotí, jestli je levý parametr menší než správný parametr.
  • Minimální parametry: 2. Maximální parametry: 2
  • Převede pravý parametr tak, aby odpovídal typu levého parametru. Chyby v případě selhání převodu
  • Porovnání řadových případů přeskakování u řetězců
  • Příklad: lt(2, 5) (vrátí hodnotu True)

ne

  • True Vyhodnotí, jestli se parametry nerovnají.
  • Minimální parametry: 2. Maximální parametry: 2
  • Převede pravý parametr tak, aby odpovídal typu levého parametru. Vrátí True , pokud převod selže.
  • Porovnání řadových případů přeskakování u řetězců
  • Příklad: ne(1, 2) (vrátí hodnotu True)

ne

  • Vyhodnocuje True, jestliže je parametr False
  • Minimální parametry: 1. Maximální parametry: 1
  • Převede hodnotu na logickou hodnotu pro vyhodnocení.
  • Příklad: not(eq(1, 2)) (vrátí hodnotu True)

notIn

  • Vyhodnotí, jestli se levý parametr nerovná True žádnému správnému parametru.
  • Minimální parametry: 1. Maximální parametry: N
  • Převede správné parametry tak, aby odpovídaly typu levého parametru. Porovnání rovnosti se vyhodnotí False, pokud převod selže.
  • Porovnání řadových případů přeskakování u řetězců
  • Zkraty po první shodě
  • Příklad: notIn('D', 'A', 'B', 'C') (vrátí hodnotu True)

nebo

  • True Vyhodnotí, jestli je některý parametrTrue
  • Minimální parametry: 2. Maximální parametry: N
  • Přetypuje parametry na logickou hodnotu (Boolean) pro vyhodnocení.
  • Zkraty po prvním True
  • Příklad: or(eq(1, 1), eq(2, 3)) (vrátí hodnotu True, zkraty)

replace

  • Vrátí nový řetězec, ve kterém jsou všechny instance řetězce v aktuální instanci nahrazeny jiným řetězcem.
  • Minimální parametry: 3. Maximální parametry: 3
  • replace(a, b, c): vrátí a, kde jsou všechny instance b nahrazeny c.
  • Příklad: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (vrátí http://server/saml/consume)

rozdělit

  • Rozdělí řetězec na podřetězce na základě zadaných oddělovacích znaků.
  • Minimální parametry: 2. Maximální parametry: 2
  • Prvním parametrem je řetězec, který se má rozdělit.
  • Druhý parametr je oddělovač znaků.
  • Vrátí pole podřetězců. Pole obsahuje prázdné řetězce, když se oddělovací znaky objeví po sobě nebo na konci řetězce.
  • Příklad: 
    variables:
- name: environments
  value: prod1,prod2 
steps:  
  - ${{ each env in split(variables.environments, ',')}}:
    - script: ./deploy.sh --environment ${{ env }}
  • Příklad použití funkce split() s 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 }}

začínáNa

  • True Vyhodnotí, jestli levý řetězec parametru začíná správným parametrem.
  • Minimální parametry: 2. Maximální parametry: 2
  • Přetypuje parametry na řetězec pro vyhodnocení.
  • Provede porovnání řadových případů ignorování.
  • Příklad: startsWith('ABCDE', 'AB') (vrátí hodnotu True)

ořezat

  • Vrátí parametr bez úvodních a koncových prázdných znaků.
  • Minimální parametry: 1. Maximální parametry: 1
  • Příklad: trim(' variable ') vrátí 'proměnnou'.

horní

  • Převede řetězec nebo proměnnou hodnotu na všechna velká písmena.
  • Minimální parametry: 1. Maximální počet parametrů 1
  • Vrátí ekvivalent velkého písmena řetězce.
  • Příklad: upper('bah') vrátí BAH

xor

  • True Vyhodnotí, zda je právě jeden parametr True
  • Minimální parametry: 2. Maximální parametry: 2
  • Převádí parametry na Boolean pro vyhodnocení.
  • Příklad: xor(True, False) (vrátí hodnotu True)

Funkce kontroly stavu úlohy

Následující funkce kontroly stavu můžete použít jako výrazy v podmínkách, ale ne v definicích proměnných.

vždy

  • Vždy se vyhodnotí jako True (i když je zrušeno). Poznámka: Kritická chyba může stále bránit spuštění úlohy. Pokud se například nepodařilo získat zdroje.

zrušený

  • Vyhodnotí se na True, jestli byl datový tok zrušen.

selhalo

  • Pro krok, který odpovídá eq(variables['Agent.JobStatus'], 'Failed').
  • Pro práci:
    • Bez uvedení argumentů se vyhodnotí True pouze v případě, že jakákoli předchozí úloha v grafu závislostí neuspěla.
    • U názvů úloh jako argumentů True se vyhodnotí pouze v případě, že některá z těchto úloh selhala.

uspěl

  • V případě kroku, který odpovídá in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Při práci s úlohami použijte dependsOn, chcete-li vyhodnotit, zda byla předchozí úloha úspěšná. Úlohy jsou navržené tak, aby běžely paralelně, zatímco fáze běží postupně.
  • Na pozici:
    • Vyhodnocuje se k True pouze tehdy, když nemá argumenty a všechny předchozí úlohy v grafu závislostí byly zcela nebo částečně úspěšné.
    • U názvů úloh jako argumentů True se vyhodnotí, jestli byly všechny tyto úlohy úspěšné nebo částečně úspěšné.
    • Vyhodnotí se jako False, pokud je potrubí zrušeno.

úspěšnýneboNeúspěšný

  • V případě kroku, který odpovídá in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

  • Pro práci:

    • Bez argumentů se hodnotí jako True bez ohledu na to, zda nějaké úlohy v grafu závislostí uspěly nebo selhaly.
    • Při použití názvů úloh jako argumentů se vyhodnotí True, jestli některé z těchto úloh proběhly úspěšně nebo selhaly.
    • Místo toho můžete chtít použít not(canceled()) , když v grafu závislostí existují předchozí přeskočené úlohy.

    To je podobné always(), kromě toho, že se False vyhodnotí, když je kanál zrušen.

Podmíněné vložení

Pomocí klauzulí if, elseif a else můžete podmíněně přiřadit hodnoty proměnných nebo nastavit vstupy pro úkoly. Při splnění podmínky můžete také podmíněně spustit krok.

Můžete použít if k podmíněnému přiřazení proměnných hodnot nebo nastavení vstupů pro úkoly. Krok můžete spustit také při splnění podmínky.

Klauzule elseif a else klauzule jsou dostupné od Azure DevOps 2022 a nejsou k dispozici pro Azure DevOps Server 2020 a starší verze Azure DevOps.

Podmíněné podmínky fungují jenom při použití syntaxe šablony. Přečtěte si další informace o syntaxi proměnných.

U šablon můžete při přidávání sekvence nebo mapování použít podmíněné vložení. Přečtěte si další informace o podmíněném vkládání v šablonách.

Podmíněné přiřazení proměnné

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

Podmíněné nastavení vstupu úkolu

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'

Podmíněné spuštění kroku

Pokud neexistuje žádná proměnná sada nebo hodnota foo neodpovídá if podmínkám, else příkaz se spustí. Tady hodnota foo vrátí hodnotu true v podmínce 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ždé klíčové slovo

Klíčové slovo each můžete použít pro iteraci parametrů s typem objektu.

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

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

Kromě toho můžete iterovat vnořenými prvky v rámci objektu.

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

Závislosti

Výrazy můžou použít kontext závislostí k odkazování na předchozí úlohy nebo fáze. Pomocí závislostí můžete:

  • Odkaz na stav předchozí úlohy
  • Odkaz na stav předchozí fáze
  • Odkaz na výstupní proměnné v předchozí úloze ve stejné fázi
  • Odkazovat na výstupní proměnné v předchozí fázi jedné fáze
  • Odkazovat na výstupní proměnné úlohy z předchozí fáze v následující fázi.

Kontext se volá dependencies pro úlohy a fáze a funguje podobně jako proměnné. Pokud odkazujete na výstupní proměnnou z úlohy v jiné fázi, stageDependencies se nazývá kontext.

Pokud máte problémy s výstupními proměnnými s uvozovkami (' nebo ") v nich, prohlédněte si tohoto průvodce odstraňováním potíží.

Přehled syntaxe závislostí

Syntaxe odkazování na výstupní proměnné se závislostmi se liší v závislosti na okolnostech. Tady je přehled nejběžnějších scénářů. Někdy může docházet i k tomu, že alternativní syntaxe funguje.

Typ

Popis

závislost mezi fázemi (různé fáze)

Odkazování na výstupní proměnnou z předchozí fáze v úloze, která je v jiné fázi v rámci podmínky v stages.

  • Syntaxe: and(succeeded(), eq(stageDependencies.<stage-name>.outputs['<job-name>.<step-name>.<variable-name>'], 'true'))
  • Příklad: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))

závislost mezi úlohami (stejná fáze)

Odkazovat na výstupní proměnnou v jiné úloze ve stejné fázi v stages.

  • Syntaxe: and(succeeded(), eq(dependencies.<job-name>.outputs['<step-name>.<variable-name>'], 'true'))
  • Příklad: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Závislost úlohy na fázích (různé fáze)

Odkaz na výstupní proměnnou v jiné fázi v objektu job.

  • Syntaxe: eq(stageDependencies.<stage-name>.<job-name>.outputs['<step-name>.<variable-name>'], 'true')
  • Příklad: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')

Závislost mezi fázemi (úloha nasazení)

Odkaz na výstupní proměnnou v úloze nasazení v jiném kroku v stages.

  • Syntaxe: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<deployment-job-name>.<step-name>.<variable-name>'], 'true')
  • Příklad: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')

Závislost mezi etapami (úloha nasazení s prostředkem)

Odkazujte na výstupní proměnnou v úloze nasazení, která zahrnuje prostředek v jiné fázi v stages.

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

V úlohách nasazení existují také různé syntaxe pro výstupní proměnné v závislosti na strategii nasazení. Další informace najdete v tématu Úlohy nasazení.

Závislosti mezi fázemi

Objekt dependencies je strukturovaně mapou, která přiřazuje názvy úloh a fází k results a outputs. Vyjádřeno jako JSON by vypadalo takto:

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

Poznámka:

Následující příklady používají standardní syntaxi pipeline. Pokud používáte kanály nasazení, syntaxe proměnných i podmíněných proměnných se bude lišit. Informace o konkrétní syntaxi, která se má použít, najdete v tématu Úlohy pro nasazení.

Pomocí této formy dependencies můžete mapovat proměnné nebo kontrolovat podmínky na úrovni fáze.

V tomto příkladu existují dvě fáze, A a B. Fáze A má podmínku false a v důsledku toho se nikdy nespustí. Fáze B se spustí, pokud je Succeededvýsledek fáze A , SucceededWithIssuesnebo Skipped. Fáze B běží, protože fáze A byla vynechána.

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

Fáze můžou také používat výstupní proměnné z jiné fáze. V tomto příkladu existují také dvě fáze. Fáze A obsahuje úlohu A1, která nastaví výstupní proměnnou shouldrun na true. Fáze B se spustí, když shouldrun je true. Protože je shouldruntrue, běží fáze B.

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

Poznámka:

Ve výchozím nastavení každá fáze kanálu závisí na jedné fázi těsně před ní v souboru YAML. Pokud potřebujete odkazovat na fázi, která není bezprostředně před aktuální fází, můžete tuto automatickou výchozí hodnotu přepsat přidáním dependsOn oddílu do fáze.

Závislosti mezi úlohami v rámci jedné fáze

Na úrovni úlohy v jedné fázi data dependencies neobsahují informace na úrovni fáze.

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

V tomto příkladu existují tři úlohy (a, b a a c). Práce a bude vždy přeskočena kvůli condition: false. Úloha b se spustí, protože neexistují žádné přidružené podmínky. Úloha c se spustí, protože všechny její závislosti buď se vykonají úspěšně (úloha b), nebo jsou přeskočeny (úloha 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

V tomto příkladu úloha B závisí na výstupní proměnné z úlohy 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

Závislosti úloh napříč fázemi

Na úrovni úlohy můžete také odkazovat na výstupy z úlohy v předchozí fázi. To vyžaduje použití stageDependencies kontextu.

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

V tomto příkladu se úloha B1 spustí, pokud je úloha A1 vynechána. Úloha B2 zkontroluje hodnotu výstupní proměnné z úlohy A1 a určí, jestli se má spustit.

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

Pokud úloha závisí na proměnné definované úlohou nasazení v jiné fázi, syntaxe se liší. V následujícím příkladu se úloha run_tests spustí, pokud je úloha nasazení nastavena build_jobrunTests na true. Všimněte si, že klíč použitý pro outputs slovník je 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:
        ...

Výstupní proměnné úlohy nasazení

Pokud fáze závisí na proměnné definované úlohou nasazení v jiné fázi, syntaxe se liší. V následujícím příkladu fáze test závisí na nastavení build_job nasazení shouldTest na true. Všimněte si, že v condition fázi test se build_job objeví dvakrát.

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

V předchozím příkladu podmínka odkazuje na prostředí, nikoli na prostředek prostředí. Pokud chcete odkazovat na prostředek prostředí, budete muset přidat název prostředku prostředí do podmínky závislostí. V následujícím příkladu podmínka odkazuje na prostředek virtuálního počítače v prostředí s názvem 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

Filtrovaná pole

Pokud pracujete s kolekcí položek, můžete pomocí syntaxe použít * filtrované pole. Filtrované pole vrátí všechny objekty/prvky bez ohledu na jejich názvy.

Jako příklad zvažte pole objektů pojmenovaných foo. Chceme získat pole hodnot vlastnosti v každém objektu id v naší matici.

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

Mohli bychom udělat toto:

foo.*.id

Tím systému řeknete, aby pracoval s foo jako s filtrovaným polem a poté vybral vlastnost id.

To by se vrátilo:

[ 1, 2, 3 ]

Přetypování

Hodnoty ve výrazu mohou být převedeny z jednoho typu na jiný, protože se výraz vyhodnotí. Při vyhodnocení výrazu se parametry převedou na příslušný datový typ a pak jsou opět převedeny na řetězce.

Například v tomto YAML se hodnoty True a False jsou převedeny na 1 a 0 při vyhodnocení výrazu. Funkce lt() se vrátí True , když je levý parametr menší než pravý 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)

Když výraz použijete eq() k vyhodnocení ekvivalence, hodnoty se implicitně převedou na čísla (false na 0 a true na 1).

variables:
  trueAsNumber: $[eq('true', true)] # 1 vs. 1, True
  falseAsNumber: $[eq('false', true)] # 0 vs. 1, False

steps:
- script: echo $(trueAsNumber)
- script: echo $(falseAsNumber)

V tomto dalším příkladu se hodnoty variables.emptyString a prázdný řetězec vyhodnotí jako prázdné řetězce. Funkce coalesce() vyhodnotí parametry v pořadí a vrátí první hodnotu, která se nerovná hodnotě null nebo prázdný řetězec.

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

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

Níže jsou uvedena podrobná pravidla převodu.

Z / Do Logická hodnota Null Počet / Číslo řetězec Verze
Boolean - - Ano Ano -
Nula Ano - Ano Ano -
Počet Ano - - Ano Částečná
Řetězec Ano Částečná Částečná - Částečná
Verze Ano - - Ano -

Logická hodnota

Na číslo:

  • False → 0
  • True → 1

Do řetězce:

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

Null

  • Na logickou hodnotu: False
  • Na číslo: 0
  • Na řetězec: '' (prázdný řetězec)

Číslo

  • Na Boolean: 0 → False, všechna ostatní čísla → True
  • Verze: Musí být větší než nula a musí obsahovat nenulové desetinné číslo. Musí být menší než Int32.MaxValue (včetně desetinné části).
  • Na řetězec: Převede číslo na řetězec bez oddělovače tisíců a bez oddělovače desetinných míst.

String

  • Převod na logickou hodnotu: '' (prázdný řetězec) → False, jakýkoli jiný řetězec → True
  • Na hodnotu null: '' (prázdný řetězec) → Null, jakýkoli jiný řetězec není konvertibilní.
  • Číslo: '' (prázdný řetězec) → 0, jinak spustí C# Int32.TryParse pomocí InvariantCulture a následujících pravidel: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Pokud TryParse dojde k chybě, pak nelze převést.
  • Pro verzi: spouští C# Version.TryParse. Musí obsahovat minimálně Hlavní a Vedlejší komponentu. Pokud TryParse selže, pak není převoditelný.

Verze

  • Na logickou hodnotu: True
  • Řetězec: Major.Minor nebo Major.Minor.Build nebo Major.Minor.Build.Revision.

Často kladené dotazy

Chci udělat něco, co výrazy nepodporují. Jaké možnosti mám pro rozšíření funkcí Pipelines?

Můžete přizpůsobit svou Pipeline pomocí skriptu, který obsahuje výraz. Tento fragment kódu například vezme proměnnou BUILD_BUILDNUMBER a rozdělí ji pomocí bashe. Tento skript vypíše dvě nové proměnné, $MAJOR_RUN a $MINOR_RUN, pro hlavní a vedlejší čísla spuštění. Dvě proměnné se pak použijí k vytvoření dvou proměnných v rámci pipeline, $major a $minor pomocí task.setvariable. Tyto proměnné jsou k dispozici pro podřízené kroky. Pokud chcete sdílet proměnné mezi kanály, podívejte se na skupiny proměnných.

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