Uttryck

  • Artikel

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

Viktigt!

Välj en version från Azure DevOps Innehållsversionsväljare.

Välj den version av den här artikeln som motsvarar din plattform och version. Versionsväljaren ligger ovanför innehållsförteckningen. Leta upp din Azure DevOps-plattform och -version.

Uttryck kan användas på många platser där du behöver ange ett sträng-, booleskt eller talvärde när du skapar en pipeline. När ett uttryck returnerar en matris gäller normala indexeringsregler och indexet börjar med 0.

Den vanligaste användningen av uttryck är i villkor för att avgöra om ett jobb eller ett steg ska köras.

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

En annan vanlig användning av uttryck är att definiera variabler. Uttryck kan utvärderas vid kompilering eller vid körning. Kompilera tidsuttryck kan användas var som helst. körningsuttryck kan användas i variabler och villkor. Körningsuttryck är avsedda som ett sätt att beräkna innehållet i variabler och tillstånd (exempel: 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> ]

Skillnaden mellan körnings- och kompileringstidsuttryckssyntaxer är främst vilken kontext som är tillgänglig. I ett kompileringsuttryck (${{ <expression> }}) har du åtkomst till parameters och statiskt definierat variables. I ett körningsuttryck ($[ <expression> ]) har du åtkomst till fler variables men inga parametrar.

I det här exemplet anger ett körningsuttryck värdet $(isMain)för . En statisk variabel i ett kompileringsuttryck anger värdet $(compileVar)för .

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

Ett uttryck kan vara en literal, en referens till en variabel, en referens till ett beroende, en funktion eller en giltig kapslad kombination av dessa.

Literaler

Som en del av ett uttryck kan du använda booleska, null-, tal-, sträng- eller versionsliteraler.

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

Booleskt

True och False är booleska literaluttryck.

Null

Null är ett särskilt literaluttryck som returneras från en ordlistemiss, till exempel (variables['noSuch']). Null kan vara utdata för ett uttryck men kan inte anropas direkt i ett uttryck.

Antal

Börjar med "-", "." eller "0" till och med "9".

String

Måste vara enstaka citattecken. Exempel: 'this is a string'.

Om du vill uttrycka ett literalt enkelt citattecken kan du undvika det med ett enda citattecken. Exempel: 'It''s OK if they''re using contractions.'.

Du kan använda ett pipe-tecken (|) för flerradssträngar.

myKey: |
  one
  two
  three

Version

Ett versionsnummer med upp till fyra segment. Måste börja med ett tal och innehålla två eller tre punkttecken (.). Exempel: 1.2.3.4.

Variabler

Som en del av ett uttryck kan du komma åt variabler med någon av två syntaxer:

  • Indexsyntax: variables['MyVar']
  • Syntax för egenskapsavreferens: variables.MyVar

För att kunna använda syntax för egenskapsavreferens måste egenskapsnamnet:

  • Börja med a-Z eller _
  • Följs av a-Z0-9 eller _

Beroende på körningskontexten är olika variabler tillgängliga.

Variabler är alltid strängar. Om du vill använda inskrivna värden bör du använda parametrar i stället.

Kommentar

Det finns en begränsning för att använda variabler med uttryck för både klassiska pipelines och YAML-pipelines när du konfigurerar sådana variabler via flikgränssnittet för variabler. Variabler som definieras som uttryck bör inte vara beroende av en annan variabel med uttryck i värde eftersom det inte är garanterat att båda uttrycken utvärderas korrekt. Vi har till exempel en variabel a vars värde $[ <expression> ] används som en del för värdet för variabeln b. Eftersom ordningen för bearbetningsvariabler inte garanteras kan variabeln b ha ett felaktigt värde för variabeln a efter utvärderingen.

Beskrivna konstruktioner tillåts endast när du konfigurerar variabler via nyckelordet variabler i YAML-pipelinen. Du måste placera variablerna i den ordning de ska bearbetas för att få rätt värden efter bearbetningen.

Functions

Följande inbyggda funktioner kan användas i uttryck.

och

  • Utvärderas till True om alla parametrar är True
  • Minsta parametrar: 2. Maxparametrar: N
  • Omvandlar parametrar till booleskt värde för utvärdering
  • Kortslutningar efter första False
  • Exempel: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

sammanstärning

  • Utvärderar parametrarna i ordning (från vänster till höger) och returnerar det första värdet som inte är lika med null eller tom sträng.
  • Inget värde returneras om parametervärdena alla är null- eller tomma strängar.
  • Minsta parametrar: 2. Maxparametrar: N
  • Exempel: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

innehåller

  • Utvärderar True om den vänstra parametern String innehåller rätt parameter
  • Minsta parametrar: 2. Maxparametrar: 2
  • Omvandlar parametrar till Sträng för utvärdering
  • Utför ordningstalsjämförelse av ignore-case
  • Exempel: contains('ABCDE', 'BCD') (returnerar Sant)

containsValue

  • Utvärderar True om den vänstra parametern är en matris och ett objekt är lika med den högra parametern. Utvärderar True även om den vänstra parametern är ett objekt och värdet för en egenskap är lika med den högra parametern.
  • Minsta parametrar: 2. Maxparametrar: 2
  • Om den vänstra parametern är en matris konverterar du varje objekt så att det matchar typen av den högra parametern. Om den vänstra parametern är ett objekt konverterar du värdet för varje egenskap för att matcha typen av den högra parametern. Likhetsjämförelsen för varje specifikt objekt utvärderas False om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Kortslutningar efter den första matchningen

Kommentar

Det finns ingen literalsyntax i en YAML-pipeline för att ange en matris. Den här funktionen är av begränsad användning i allmänna pipelines. Den är avsedd att användas i pipelinedekoratörkontexten med systembaserade matriser, till exempel listan med steg.

Du kan använda uttrycket containsValue för att hitta ett matchande värde i ett objekt. Här är ett exempel som visar hur du söker i listan över källgrenar för en matchning för 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

  • Ta ett komplext objekt och mata ut det som JSON.
  • Minsta parametrar: 1. Maxparametrar: 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) }}

Skriptutdata:

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

räknare

  • Den här funktionen kan bara användas i ett uttryck som definierar en variabel. Det kan inte användas som en del av ett villkor för ett steg, ett jobb eller en fas.
  • Utvärderar ett tal som ökas med varje körning av en pipeline.
  • Parametrar: 2. prefix och seed.
  • Prefix är ett stränguttryck. Ett separat värde för räknaren spåras för varje unikt prefixvärde. Ska prefix använda UTF-16 tecken.
  • Seed är startvärdet för räknaren

Du kan skapa en räknare som automatiskt ökas med en i varje körning av pipelinen. När du definierar en räknare anger du en prefix och en seed. Här är ett exempel som visar detta.

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)

Värdet minor för i exemplet ovan i den första körningen av pipelinen är 100. I den andra körningen är den 101, förutsatt att värdet major för fortfarande är 1.

Om du redigerar YAML-filen och uppdaterar värdet för variabeln major till 2 blir värdet minor 100 i nästa körning av pipelinen. Efterföljande körningar ökar räknaren till 101, 102, 103, ...

Senare, om du redigerar YAML-filen och anger värdet major för tillbaka till 1, återupptas värdet för räknaren där den slutade för prefixet. I det här exemplet återupptas den vid 102.

Här är ett annat exempel på hur du ställer in en variabel som ska fungera som en räknare som börjar vid 100, ökas med 1 för varje körning och återställs till 100 varje dag.

Kommentar

pipeline.startTime är inte tillgängligt utanför uttryck. pipeline.startTime formateras system.pipelineStartTime till ett datum- och tidsobjekt så att det är tillgängligt att arbeta med uttryck. Standardtidszonen för pipeline.startTime är UTC. Du kan ändra tidszonen för din organisation.

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

Här är ett exempel på att ha en räknare som behåller ett separat värde för PR:er och CI-körningar.

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

Räknare är begränsade till en pipeline. Med andra ord ökas dess värde för varje körning av pipelinen. Det finns inga räknare med projektomfattning.

endsWith

  • Utvärderar True om den vänstra parametern String slutar med högerparameter
  • Minsta parametrar: 2. Maxparametrar: 2
  • Omvandlar parametrar till Sträng för utvärdering
  • Utför ordningstalsjämförelse av ignore-case
  • Exempel: endsWith('ABCDE', 'DE') (returnerar Sant)

eq

  • Utvärderar True om parametrarna är lika med
  • Minsta parametrar: 2. Maxparametrar: 2
  • Konverterar högerparameter för att matcha typen av vänsterparameter. Returnerar False om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Exempel: eq(variables.letters, 'ABC')

format

  • Utvärderar de avslutande parametrarna och infogar dem i den inledande parametersträngen
  • Minsta parametrar: 1. Maxparametrar: N
  • Exempel: format('Hello {0} {1}', 'John', 'Doe')
  • Använder anpassade .NET-datum- och tidsformatsspecificerare för datumformatering (yyyy, , yyMM, M, dd, d, f) ffKHHHmmmsssffff
  • Exempel: format('{0:yyyyMMdd}', pipeline.startTime). I det här fallet pipeline.startTime är en särskild objektvariabel för datumtid.
  • Fly genom att fördubbla klammerparenteser. Till exempel: format('literal left brace {{ and literal right brace }}')

ge

  • Utvärderar True om den vänstra parametern är större än eller lika med den högra parametern
  • Minsta parametrar: 2. Maxparametrar: 2
  • Konverterar högerparameter för att matcha typen av vänsterparameter. Fel om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Exempel: ge(5, 5) (returnerar Sant)

gt

  • Utvärderar True om den vänstra parametern är större än den högra parametern
  • Minsta parametrar: 2. Maxparametrar: 2
  • Konverterar högerparameter för att matcha typen av vänsterparameter. Fel om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Exempel: gt(5, 2) (returnerar Sant)

in

  • Utvärderar True om den vänstra parametern är lika med valfri högerparameter
  • Minsta parametrar: 1. Maxparametrar: N
  • Konverterar högerparametrar för att matcha typen av vänsterparameter. Likhetsjämförelse utvärderas False om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Kortslutning efter första matchen
  • Exempel: in('B', 'A', 'B', 'C') (returnerar Sant)

anslut

  • Sammanfogar alla element i den högra parametermatrisen, avgränsade med den vänstra parametersträngen.
  • Minsta parametrar: 2. Maxparametrar: 2
  • Varje element i matrisen konverteras till en sträng. Komplexa objekt konverteras till en tom sträng.
  • Om rätt parameter inte är en matris är resultatet rätt parameter konverterad till en sträng.

I det här exemplet läggs ett semikolon till mellan varje objekt i matrisen. Parametertypen är ett objekt.

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

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

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

le

  • Utvärderar True om den vänstra parametern är mindre än eller lika med den högra parametern
  • Minsta parametrar: 2. Maxparametrar: 2
  • Konverterar högerparameter för att matcha typen av vänsterparameter. Fel om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Exempel: le(2, 2) (returnerar Sant)

längd

  • Returnerar längden på en sträng eller en matris, antingen en som kommer från systemet eller som kommer från en parameter
  • Minsta parametrar: 1. Maxparametrar 1
  • Exempel: length('fabrikam') returnerar 8

Lägre

  • Konverterar ett sträng- eller variabelvärde till alla gemener
  • Minsta parametrar: 1. Maxparametrar 1
  • Returnerar gemener som motsvarar en sträng
  • Exempel: lower('FOO') returnerar foo

lt

  • Utvärderar True om den vänstra parametern är mindre än den högra parametern
  • Minsta parametrar: 2. Maxparametrar: 2
  • Konverterar högerparameter för att matcha typen av vänsterparameter. Fel om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Exempel: lt(2, 5) (returnerar Sant)

ne

  • Utvärderar True om parametrarna inte är lika med
  • Minsta parametrar: 2. Maxparametrar: 2
  • Konverterar högerparameter för att matcha typen av vänsterparameter. Returnerar True om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Exempel: ne(1, 2) (returnerar Sant)

not

  • Utvärderar True om parametern är False
  • Minsta parametrar: 1. Maxparametrar: 1
  • Konverterar värdet till booleskt värde för utvärdering
  • Exempel: not(eq(1, 2)) (returnerar Sant)

notIn

  • Utvärderar True om den vänstra parametern inte är lika med någon högerparameter
  • Minsta parametrar: 1. Maxparametrar: N
  • Konverterar högerparametrar för att matcha typen av vänsterparameter. Likhetsjämförelse utvärderas False om konverteringen misslyckas.
  • Ordningstalsjämförelse av ignore-case för strängar
  • Kortslutning efter första matchen
  • Exempel: notIn('D', 'A', 'B', 'C') (returnerar Sant)

eller

  • Utvärderar True om någon parameter är True
  • Minsta parametrar: 2. Maxparametrar: N
  • Omvandlar parametrar till booleskt värde för utvärdering
  • Kortslutningar efter första True
  • Exempel: or(eq(1, 1), eq(2, 3)) (returnerar Sant, kortslutningar)

ersätt

  • Returnerar en ny sträng där alla instanser av en sträng i den aktuella instansen ersätts med en annan sträng
  • Minsta parametrar: 3. Maxparametrar: 3
  • replace(a, b, c): returnerar en, med alla instanser av b ersatta av c
  • Exempel: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (returnerar http://server/saml/consume)

dela

  • Delar upp en sträng i delsträngar baserat på de angivna avgränsande tecknen
  • Minsta parametrar: 2. Maxparametrar: 2
  • Den första parametern är strängen som ska delas
  • Den andra parametern är de avgränsande tecknen
  • Returnerar en matris med delsträngar. Matrisen innehåller tomma strängar när avgränsande tecken visas i följd eller i slutet av strängen
  • Exempel: 
    variables:
- name: environments
  value: prod1,prod2 
steps:  
  - ${{ each env in split(variables.environments, ',')}}:
    - script: ./deploy.sh --environment ${{ env }}
  • Exempel på användning av split() med 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

  • Utvärderar True om vänster parametersträng börjar med högerparameter
  • Minsta parametrar: 2. Maxparametrar: 2
  • Omvandlar parametrar till Sträng för utvärdering
  • Utför ordningstalsjämförelse av ignore-case
  • Exempel: startsWith('ABCDE', 'AB') (returnerar Sant)

Övre

  • Konverterar ett sträng- eller variabelvärde till alla versaler
  • Minsta parametrar: 1. Maxparametrar 1
  • Returnerar versaler som motsvarar en sträng
  • Exempel: upper('bah') returnerar BAH

xor

  • Utvärderar True om exakt en parameter är True
  • Minsta parametrar: 2. Maxparametrar: 2
  • Omvandlar parametrar till booleskt värde för utvärdering
  • Exempel: xor(True, False) (returnerar Sant)

Funktioner för jobbstatuskontroll

Du kan använda följande statuskontrollfunktioner som uttryck i villkor, men inte i variabeldefinitioner.

alltid

  • Utvärderas alltid till True (även när den avbryts). Obs! Ett kritiskt fel kan fortfarande hindra en aktivitet från att köras. Till exempel om det inte gick att hämta källor.

Annullerad

  • Utvärderas till True om pipelinen avbröts.

Misslyckades

  • För ett steg som motsvarar eq(variables['Agent.JobStatus'], 'Failed').
  • För ett jobb:
    • Utan argument utvärderas endast till True om något tidigare jobb i beroendediagrammet misslyckades.
    • Med jobbnamn som argument utvärderas endast till True om något av dessa jobb misslyckades.

Lyckades

  • För ett steg som motsvarar in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Använd med dependsOn när du arbetar med jobb och du vill utvärdera om ett tidigare jobb lyckades. Jobb är utformade för att köras parallellt medan faser körs sekventiellt.
  • För ett jobb:
    • Utan argument utvärderas endast till True om alla tidigare jobb i beroendediagrammet lyckades eller delvis lyckades.
    • Med jobbnamn som argument utvärderas till True om alla dessa jobb lyckades eller delvis lyckades.
    • Utvärderas till False om pipelinen avbryts.

succeededOrFailed

  • För ett steg som motsvarar in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

  • För ett jobb:

    • Utan argument utvärderas till True oavsett om några jobb i beroendediagrammet lyckades eller misslyckades.
    • Med jobbnamn som argument utvärderas till True om något av dessa jobb lyckades eller misslyckades.
    • Du kanske vill använda not(canceled()) i stället när det finns tidigare överhoppade jobb i beroendediagrammet.

    Det här är som always(), förutom att den utvärderas False när pipelinen avbryts.

Villkorsstyrd infogning

Du kan använda if, elseifoch else -satser för att villkorligt tilldela variabelvärden eller ange indata för aktiviteter. Du kan också villkorligt köra ett steg när ett villkor uppfylls.

Du kan använda if för att villkorligt tilldela variabelvärden eller ange indata för aktiviteter. Du kan också villkorligt köra ett steg när ett villkor uppfylls.

elseif Satserna och else är tillgängliga från och med Azure DevOps 2022 och är inte tillgängliga för Azure DevOps Server 2020 och tidigare versioner av Azure DevOps.

Villkor fungerar bara när du använder mallsyntax. Läs mer om variabelsyntax.

För mallar kan du använda villkorsstyrd infogning när du lägger till en sekvens eller mappning. Läs mer om villkorsstyrd infogning i mallar.

Tilldela en variabel villkorligt

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

Villkorligt ange indata för en aktivitet

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'

Kör ett steg villkorligt

Om det inte finns någon variabeluppsättning, eller om foo värdet för inte matchar if villkoren, körs -instruktionen else . Här returnerar värdet foo för true i villkoret 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"

Varje nyckelord

Du kan använda nyckelordet each för att loopa igenom parametrar med objekttypen.

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

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

Dessutom kan du iterera genom kapslade element i ett objekt.

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

Beroenden

Uttryck kan använda beroendekontexten för att referera till tidigare jobb eller faser. Du kan använda beroenden för att:

  • Referera till jobbstatusen för ett tidigare jobb
  • Referera till fasstatusen för en tidigare fas
  • Referensutdatavariabler i föregående jobb i samma fas
  • Referera till utdatavariabler i föregående steg i en fas
  • Referera till utdatavariabler i ett jobb i en tidigare fas i följande steg

Kontexten anropas dependencies för jobb och faser och fungerar ungefär som variabler. Om du refererar till en utdatavariabel från ett jobb i en annan fas kallas stageDependencieskontexten .

Om du har problem med att utdatavariabler har citattecken (' eller ") i dem kan du läsa den här felsökningsguiden.

Översikt över beroendesyntax

Syntaxen för att referera till utdatavariabler med beroenden varierar beroende på omständigheterna. Här är en översikt över de vanligaste scenarierna. Det kan finnas tillfällen då alternativ syntax också fungerar.

Typ

Beskrivning

fas-till-fas-beroende (olika steg)

Referera till en utdatavariabel från en tidigare fas i ett jobb i ett annat steg i ett villkor i stages.

  • Syntax: and(succeeded(), eq(stageDependencies.<stage-name>.outputs['<job-name>.<step-name>.<variable-name>'], 'true'))
  • Exempel: and(succeeded(), eq(stageDependencies.A.outputs['A1.printvar.shouldrun'], 'true'))

jobb till jobbberoende (samma fas)

Referera till en utdatavariabel i ett annat jobb i samma fas i stages.

  • Syntax: and(succeeded(), eq(dependencies.<job-name>.outputs['<step-name>.<variable-name>'], 'true'))
  • Exempel: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Jobb för att mellanlagra beroende (olika faser)

Referera till en utdatavariabel i ett annat stadium i en job.

  • Syntax: eq(stageDependencies.<stage-name>.<job-name>.outputs['<step-name>.<variable-name>'], 'true')
  • Exempel: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')

Beroende mellan steg (distributionsjobb)

Referensutdatavariabel i ett distributionsjobb i ett annat steg i stages.

  • Syntax: eq(dependencies.<stage-name>.outputs['<deployment-job-name>.<deployment-job-name>.<step-name>.<variable-name>'], 'true')
  • Exempel: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')

Beroende mellan steg (distributionsjobb med resurs)

Referera till en utdatavariabel i ett distributionsjobb som innehåller en resurs i en annan fas i stages.

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

Det finns också olika syntaxer för utdatavariabler i distributionsjobb beroende på distributionsstrategin. Mer information finns i Distributionsjobb.

Beroenden mellan steg till steg

Strukturellt är objektet dependencies en karta över jobb- och fasnamn till results och outputs. Uttryckt som JSON skulle det se ut så här:

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

Kommentar

I följande exempel används standardsyntax för pipeline. Om du använder distributionspipelines skiljer sig både variabel- och villkorsvariabelsyntaxen åt. Information om den specifika syntax som ska användas finns i Distributionsjobb.

Använd den här formen för dependencies att mappa i variabler eller kontrollera villkor på en stegnivå.

I det här exemplet finns det två steg, A och B. Steg A har villkoret false och körs aldrig som ett resultat. Steg B körs om resultatet av steg A är Succeeded, SucceededWithIssueseller Skipped. Steg B körs eftersom steg A hoppades över.

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

Faser kan också använda utdatavariabler från en annan fas. I det här exemplet finns det också två steg. Steg A innehåller ett jobb, A1, som anger en utdatavariabel shouldrun till true. Steg B körs när shouldrun är true. Eftersom shouldrun är true, körs steg 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

Kommentar

Som standard beror varje steg i en pipeline på den precis före den i YAML-filen. Om du behöver referera till en fas som inte är omedelbart före den aktuella, kan du åsidosätta den här automatiska standardinställningen genom att lägga till ett dependsOn avsnitt i fasen.

Jobb till jobbberoenden inom en fas

På jobbnivå i en enda fas dependencies innehåller data inte information på stegnivå.

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

I det här exemplet finns det tre jobb (a, b och c). Jobb a hoppas alltid över på grund av condition: false. Jobb b körs eftersom det inte finns några associerade villkor. Jobbet c körs eftersom alla dess beroenden antingen lyckas (jobb b) eller hoppas över (jobb 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

I det här exemplet beror jobb B på en utdatavariabel från jobb 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

Jobb till jobbberoenden mellan olika faser

På jobbnivå kan du också referera till utdata från ett jobb i ett tidigare skede. Detta kräver att kontexten stageDependencies används.

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

I det här exemplet körs jobbet B1 om jobbet A1 hoppas över. Jobb B2 kontrollerar värdet för utdatavariabeln från jobb A1 för att avgöra om den ska köras.

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

Om ett jobb är beroende av en variabel som definierats av ett distributionsjobb i en annan fas är syntaxen annorlunda. I följande exempel körs jobbet run_tests om distributionsjobbet build_job är inställt runTests på true. Observera att nyckeln som används för outputs ordlistan är 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:
        ...

Utdatavariabler för distributionsjobb

Om en fas är beroende av en variabel som definierats av ett distributionsjobb i en annan fas är syntaxen annorlunda. I följande exempel beror fasen test på distributionsinställningen build_jobshouldTest till true. Observera att i steget conditiontestbuild_job visas två gånger.

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

I exemplet ovan refererar villkoret till en miljö och inte en miljöresurs. Om du vill referera till en miljöresurs måste du lägga till miljöresursnamnet i beroendevillkoret. I följande exempel refererar villkoret till en miljöresurs för virtuella datorer med namnet 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

Filtrerade matriser

När du använder en samling objekt kan du använda syntaxen * för att använda en filtrerad matris. En filtrerad matris returnerar alla objekt/element oavsett namn.

Tänk dig till exempel en matris med objekt med namnet foo. Vi vill hämta en matris med värdena för id egenskapen i varje objekt i matrisen.

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

Vi kan göra följande:

foo.*.id

Detta talar om för systemet att fungera foo som en filtrerad matris och sedan välja egenskapen id .

Detta skulle returnera:

[ 1, 2, 3 ]

Typgjutning

Värden i ett uttryck kan konverteras från en typ till en annan när uttrycket utvärderas. När ett uttryck utvärderas slås parametrarna samman till relevant datatyp och omvandlas sedan tillbaka till strängar.

I den här YAML-filen konverteras till exempel värdena True och False till 1 och 0 när uttrycket utvärderas. Funktionen lt() returnerar True när den vänstra parametern är mindre än den högra parametern.

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

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

I det här exemplet utvärderas både värdena variables.emptyString och den tomma strängen som tomma strängar. Funktionen coalesce() utvärderar parametrarna i ordning och returnerar det första värdet som inte är lika med null eller tom sträng.

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

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

Detaljerade konverteringsregler visas nedan.

Från/till Booleskt Null Antal String Version
Boolesk - - Ja Ja -
Null Ja - Ja Ja -
Antal Ja - - Ja Delvis
Sträng Ja Delvis Delvis - Delvis
Version: Ja - - Ja -

Booleskt

Så här numrerar du:

  • False → 0
  • True → 1

Så här strängar du:

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

Null

  • Till booleskt värde: False
  • Så här numrerar du: 0
  • Till sträng: '' (den tomma strängen)

Antal

  • Till boolesk: 0 → False, valfritt annat tal → True
  • Till version: Måste vara större än noll och måste innehålla en decimal som inte är noll. Måste vara mindre än Int32.MaxValue (decimalkomponent också).
  • Till sträng: Konverterar talet till en sträng utan tusentalsavgränsare och ingen decimalavgränsare.

String

  • Till boolesk: '' (den tomma strängen) → False, alla andra strängar → True
  • Till null: '' (den tomma strängen) → Null, alla andra strängar som inte kan konverteras
  • Till tal: '' (den tomma strängen) → 0, annars kör C#:er Int32.TryParse med InvariantCulture och följande regler: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Om TryParse misslyckas är det inte konvertibelt.
  • Till version: kör C#s Version.TryParse. Måste minst innehålla huvud- och delkomponenten. Om TryParse misslyckas är det inte konvertibelt.

Version

  • Till booleskt värde: True
  • Till sträng: Major.Minor eller Major.Minor.Build eller Major.Minor.Build.Revision.

Vanliga frågor

Jag vill göra något som inte stöds av uttryck. Vilka alternativ har jag för att utöka funktionerna i Pipelines?

Du kan anpassa pipelinen med ett skript som innehåller ett uttryck. Det här kodfragmentet tar till exempel variabeln BUILD_BUILDNUMBER och delar den med Bash. Det här skriptet matar ut två nya variabler, $MAJOR_RUN och $MINOR_RUN, för de större och mindre körningsnumren. De två variablerna används sedan för att skapa två pipelinevariabler $major och $minor med task.setvariable. Dessa variabler är tillgängliga för underordnade steg. Information om hur du delar variabler mellan pipelines finns i Variabelgrupper.

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