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. 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 kompilátoru (${{ <expression> }}) máte přístup k parameters a staticky definovaným variablesvýrazům . Ve výrazu modulu runtime ($[ <expression> ]) máte přístup k více variables parametrům, ale žádné parametry.

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.

String

Musí být s jedním uvozvozem. Například: 'this is a string'.

Pokud chcete vyjádřit literál jednoduché uvozovky, uchytáte ho jednoduchým uvozovkou. 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 s až čtyřmi segmenty. Musí začínat číslem a obsahovat dva nebo tři tečky (.) znaky. 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 _
  • Za ním a-Z0-9 nebo _

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

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 uživatelského rozhraní karty proměnných platí omezení použití proměnných s výrazy pro kanály Classic i YAML. 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ých slov proměnných v kanálu YAML. 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.

Functions

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

a

  • Vyhodnotí se, True jestli jsou všechny parametry True
  • Minimální parametry: 2. Maximální parametry: N
  • Přetypuje parametry na logickou hodnotu pro vyhodnocení.
  • Zkraty po prvním False
  • Příklad: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

Coalesce

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

containsValue

  • 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 se vyhodnotí False , pokud převod selže.
  • Porovnání řadových případů přeskakování u řetězců
  • Zkraty po první zápase

Poznámka:

V kanálu YAML neexistuje žádná syntaxe literálu pro zadání pole. Tato funkce je omezena v obecných kanálech. Je určená pro použití v kontextu dekorátoru kanálu 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 zobrazení 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 jedinečnou hodnotu předpony se sleduje samostatná hodnota čítače. Měl prefix by používat UTF-16 znaků.
  • Počáteční hodnota čítače

V každém spuštění kanálu můžete vytvořit čítač, který se automaticky zvýší o jeden. 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 v prvním spuštění kanálu 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 žádosti o přijetí změn a spuštění CI.

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

Čítače jsou vymezeny na kanál. Jinými slovy, jeho hodnota se zvýší pro každé spuštění tohoto kanálu. Neexistují žádné čítače v rozsahu projektu.

Endswith

  • True Vyhodnotí, jestli řetězec levého parametru končí pravým parametrem.
  • 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: 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')

format

  • 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 .NET pro formátování dat (yyyy, yy, , MMM, dd, dHH, , H, m, smmfffssffff, , ) K
  • Příklad: format('{0:yyyyMMdd}', pipeline.startTime). V tomto případě pipeline.startTime je speciální proměnná objektu data a času.
  • Uchvátěním 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)

in

  • 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 False vyhodnotí, 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)

join

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

length

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

not

  • True Vyhodnotí, jestli je parametrFalse
  • 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 False vyhodnotí, 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 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, se všemi instancemi b nahrazenými písmeny c.
  • Příklad: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (vrátí http://server/saml/consume)

split

  • 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ěžců. Pole obsahuje prázdné řetězce, pokud se oddělovače 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 }}

Startswith

  • True Vyhodnotí, jestli levý řetězec parametru začíná správným parametrem.
  • 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: startsWith('ABCDE', 'AB') (vrátí hodnotu True)

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í, jestli je právě jeden parametr.True
  • Minimální parametry: 2. Maximální parametry: 2
  • Přetypuje parametry na logickou hodnotu 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šena

  • Vyhodnotí se, True jestli byl kanál zrušen.

selhalo

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

Podařilo

  • V případě kroku, který odpovídá in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Používá se při práci s úlohami dependsOn a chcete vyhodnotit, jestli byla předchozí úloha úspěšná. Úlohy jsou navržené tak, aby běžely paralelně, zatímco fáze běží postupně.
  • Pro úlohu:
    • Bez argumentů se vyhodnotí True pouze v případě, že všechny předchozí úlohy v grafu závislostí byly úspěšné 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, False jestli je kanál zrušený.

succeededOrFailed

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

  • Pro úlohu:

    • Bezargumentch True
    • U názvů úloh jako argumentů True se vyhodnotí, 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 se podobá always(), s výjimkou toho, že se vyhodnotí False , když se kanál zruší.

Podmíněné vložení

Pomocí klauzulí , elseifa else klauzulí můžete ifpodmí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. Při splnění podmínky můžete také podmíněně spustit krok.

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 můžete použít each ke smyčce 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:

  • Odkazování na stav úlohy předchozí úlohy
  • Odkazování na stav fáze předchozí fáze
  • Odkazovat na výstupní proměnné v předchozí úloze ve stejné fázi
  • Odkazovat na výstupní proměnné v předchozí fázi fáze
  • Odkazovat na výstupní proměnné v úloze v předchozí fázi 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, volá stageDependenciesse 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

fáze k závislosti (různé fáze)

Odkazování na výstupní proměnnou z předchozí fáze v úloze v jiné fázi v podmínce 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'))

úloha do závislosti úlohy (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'))

Úloha k fázové závislosti (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')

Fáze závislosti (úloha nasazení)

Odkazovat na výstupní proměnnou v úloze nasazení v jiné fázi .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')

Příprava závislosti (úloha nasazení s prostředkem)

Odkazovat na výstupní proměnnou v úloze nasazení, která zahrnuje prostředek v jiné fázi .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í.

Fáze až fáze závislostí

Strukturálně, dependencies objekt je mapa názvů úloh a fází na 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 kanálu. Pokud používáte kanály nasazení, bude se lišit syntaxe proměnných i podmíněných proměnných. Informace o konkrétní syntaxi, která se má použít, najdete v tématu Úlohy 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. Vzhledem k tomu shouldrun , že je fáze trueB spuštěná.

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.

Úloha do závislostí úloh v rámci jedné fáze

Na úrovni úlohy v rámci jedné fáze dependencies data 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 bude vždy přeskočena condition: falsez důvodu . Ú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ď proběhnou úspěšně (úloha b), nebo se přeskočí (ú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

Úloha do závislostí ú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í shouldTest nasazení build_job na true. Všimněte si, že ve conditiontest fázi se build_job zobrazí 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 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 fungoval foo jako filtrované pole, a pak tuto vlastnost vyberte id .

To by se vrátilo:

[ 1, 2, 3 ]

Přetypování typů

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 shodí s příslušným datovým typem a pak se vrátí zpět 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)

V tomto příkladu se hodnoty variables.emptyString i 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 String Verze
Logická hodnota - - Ano Yes -
Null Ano - Ano Yes -
Počet Ano - - Yes Částečná
Řetězec Ano Částečná Částečná - Částečná
Verze Ano - - Yes -

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)

Počet

  • Logická hodnota: 0 → False, jakékoli jiné číslo → True
  • Verze: Musí být větší než nula a musí obsahovat nenulové desetinné číslo. Musí být menší než Int32.MaxValue (desetinná komponenta).
  • 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

  • Logické hodnoty: '' (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 se nepřepojí.
  • Na verzi: spustí C# Version.TryParse. Musí obsahovat minimálně hlavní a vedlejší komponentu. Pokud TryParse dojde k chybě, pak se nepřepojí.

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?

Kanál můžete přizpůsobit 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é a $MAJOR_RUN$MINOR_RUNpro hlavní a vedlejší čísla spuštění. Dvě proměnné se pak použijí k vytvoření dvou proměnných $major kanálu a $minor pomocí parametru 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)"