Delen via

Expressies

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Belangrijk

Selecteer een versie in de Azure DevOps Content Version-selector.

Selecteer de versie van dit artikel die overeenkomt met uw platform en versie. De versiekiezer staat boven de inhoudsopgave. Zoek uw Azure DevOps-platform en -versie op.

Expressies kunnen op veel plaatsen worden gebruikt waar u een tekenreeks, booleaanse waarde of getalwaarde moet opgeven bij het ontwerpen van een pijplijn. Wanneer een expressie een matrix retourneert, zijn normale indexeringsregels van toepassing en begint de index met 0.

Het meest voorkomende gebruik van expressies is in voorwaarden om te bepalen of een taak of stap moet worden uitgevoerd.

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

Een ander veelvoorkomend gebruik van expressies is het definiëren van variabelen. Expressies kunnen tijdens het compileren of tijdens runtime worden geëvalueerd. Tijdexpressies voor compileren kunnen overal worden gebruikt; runtime-expressies kunnen worden gebruikt in variabelen en voorwaarden. Runtime-expressies zijn bedoeld als een manier om de inhoud van variabelen en statussen te berekenen (bijvoorbeeld: 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> ]

Het verschil tussen runtime- en compileertijdexpressiesyntaxis is voornamelijk de context die beschikbaar is. In een compileertijdexpressie (${{ <expression> }}) hebt u toegang tot parameters en statisch gedefinieerd variables. In een runtime-expressie ($[ <expression> ]) hebt u toegang tot meer variables maar geen parameters.

In dit voorbeeld stelt een runtime-expressie de waarde van $(isMain). Een statische variabele in een compile-expressie stelt de waarde van $(compileVar) in.

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

Een expressie kan een literaal zijn, een verwijzing naar een variabele, een verwijzing naar een afhankelijkheid, een functie of een geldige geneste combinatie hiervan.

Letterlijke waarden

Als onderdeel van een expressie kunt u booleaanse waarden, null, getallen, tekenreeksen of versies gebruiken.

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

Booleaans

True en False zijn booleaanse letterlijke expressies.

Nul

Null is een speciale letterlijke waarde die wordt geretourneerd bij een zoekfout in een woordenboek, bijvoorbeeld (variables['noSuch']). Null kan de uitvoer van een expressie zijn, maar kan niet rechtstreeks in een expressie worden aangeroepen.

Aantal

Begint met '-', '.' of '0' tot en met '9'.

Snaar / Touwtje

Moet enkel aanhalingstekens hebben. Voorbeeld: 'this is a string'.

Als u een letterlijke enkele aanhalingsteken wilt uitdrukken, escapet u deze met één aanhalingsteken. Voorbeeld: 'It''s OK if they''re using contractions.'.

U kunt een pipe-teken (|) gebruiken voor tekenreeksen met meerdere regels.

myKey: |
  one
  two
  three

Versie

Een versienummer met maximaal vier segmenten. Moet beginnen met een getal en moet twee of drie punttekens (.) bevatten. Voorbeeld: 1.2.3.4.

Variabelen

Als onderdeel van een expressie hebt u toegang tot variabelen met behulp van een van de twee syntaxis:

  • Indexsyntaxis: variables['MyVar']
  • Syntaxis voor eigenschapsdereferentie: variables.MyVar

Om de eigenschap-dereferentiesyntaxis te gebruiken, moet de eigenschapsnaam:

  • Beginnen met a-Z of _
  • Worden gevolgd door a-Z0-9 of _

Afhankelijk van de uitvoeringscontext zijn er verschillende variabelen beschikbaar.

Variabelen zijn altijd tekenreeksen. Als u getypte waarden wilt gebruiken, moet u in plaats daarvan parameters gebruiken.

Notitie

Er is een beperking voor het gebruik van variabelen met expressies voor zowel klassieke als YAML-pijplijnen bij het instellen van dergelijke variabelen via de gebruikersinterface van het tabblad Variabelen. Variabelen die zijn gedefinieerd als expressies, moeten niet afhankelijk zijn van een andere variabele met expressie in waarde, omdat niet wordt gegarandeerd dat beide expressies correct worden geëvalueerd. We hebben bijvoorbeeld een variabele a waarvan de waarde $[ <expression> ] wordt gebruikt als onderdeel van de waarde van de variabele b. Omdat de volgorde van de verwerkingsvariabelen niet is gegarandeerd, kan de variabele ba na de evaluatie een onjuiste waarde hebben.

Beschreven constructies zijn alleen toegestaan tijdens het instellen van variabelen via het trefwoord "variabelen" in de YAML-pijplijn. Het is vereist om de variabelen in de volgorde te plaatsen waarin ze moeten worden verwerkt om de juiste waarden te verkrijgen na verwerking.

Functies

De volgende ingebouwde functies kunnen worden gebruikt in expressies.

en

  • Evalueert tot True als alle parameters True
  • Minimum aantal parameters: 2. Maximum aantal parameters: N
  • Zet parameters om naar een booleaanse waarde voor evaluatie
  • Kortsluiting na de eerste False
  • Voorbeeld: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

samensmelten

  • Evalueert de parameters in volgorde (van links naar rechts) en retourneert de eerste waarde die niet gelijk is aan null of lege tekenreeks.
  • Er wordt geen waarde geretourneerd als de parameterwaarden allemaal null- of lege tekenreeksen zijn.
  • Minimum aantal parameters: 2. Maximum aantal parameters: N
  • Voorbeeld: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

bevat

  • Evalueert True of de tekenreeks van de linkerparameter de juiste parameter bevat
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Casteert parameters naar String ter evaluatie
  • Hiermee wordt ordinale ignore-casevergelijking uitgevoerd
  • Voorbeeld: contains('ABCDE', 'BCD') (retourneert waar)

bevatWaarde

  • Evalueert True of de linkerparameter een matrix is en een item gelijk is aan de rechterparameter. Evalueert True ook of de linkerparameter een object is en de waarde van een eigenschap gelijk is aan de rechterparameter.
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Als de linkerparameter een matrix is, converteert u elk item zodat dit overeenkomt met het type van de rechterparameter. Als de linkerparameter een object is, converteert u de waarde van elke eigenschap zodat deze overeenkomt met het type van de rechterparameter. De gelijkheidsvergelijking voor elk specifiek item evalueert False als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Kortsluiting na de eerste overeenstemming

Notitie

Er is geen letterlijke syntaxis in een YAML-pijplijn voor het opgeven van een matrix. Deze functie is van beperkt gebruik in algemene pijplijnen. Het is bedoeld voor gebruik in de context van de pijplijn decorator met door het systeem geleverde matrices, zoals de lijst met stappen.

U kunt de containsValue expressie gebruiken om een overeenkomende waarde in een object te vinden. Hier is een voorbeeld dat laat zien hoe in een lijst met bronbranches wordt gezocht naar een overeenkomst voor 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"

omzettenNaarJson

  • Neem een complex object en voert het uit als JSON.
  • Minimale parameters: 1. Maximaal aantal parameters: 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) }}

Scriptuitvoer:

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

toonbank

  • Deze functie kan alleen worden gebruikt in een expressie die een variabele definieert. Het kan niet worden gebruikt als onderdeel van een voorwaarde voor een stap, taak of fase.
  • Evalueert een getal dat wordt verhoogd met elke uitvoering van een pijplijn.
  • Parameters: 2. prefix en seed.
  • Voorvoegsel is een tekenreeksexpressie. Er wordt een afzonderlijke waarde van de teller bijgehouden voor elke unieke waarde van het voorvoegsel. Het prefix moet UTF-16 tekens gebruiken.
  • De zaadwaarde is de beginwaarde van de teller

U kunt een teller maken die automatisch met één wordt verhoogd bij elke uitvoering van uw pijplijn. Wanneer u een teller definieert, geeft u een prefix en een seed. Hier volgt een voorbeeld dat dit laat zien.

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)

De waarde van minor in het bovenstaande voorbeeld in de eerste uitvoering van de pijplijn is 100. In de tweede uitvoering is het 101, mits de waarde major nog steeds 1 is.

Als u het YAML-bestand bewerkt en de waarde van de variabele major bijwerkt op 2, wordt in de volgende uitvoering van de pijplijn de waarde minor 100. Volgende uitvoeringen verhogen de teller naar 101, 102, 103, ...

Als u later het YAML-bestand bewerkt en de waarde van major opnieuw op 1 instelt, dan vervolgt de waarde van de teller waar deze was gebleven voor dat voorvoegsel. In dit voorbeeld hervat het bij 102.

Hier volgt een ander voorbeeld van het instellen van een variabele om te fungeren als een teller die begint bij 100, wordt verhoogd met 1 voor elke uitvoering en wordt elke dag opnieuw ingesteld op 100.

Notitie

pipeline.startTime is niet beschikbaar buiten expressies. pipeline.startTime wordt system.pipelineStartTime opgemaakt in een datum- en tijdobject, zodat het beschikbaar is voor gebruik met expressies. De standaardtijdzone voor pipeline.startTime UTC is. U kunt de tijdzone voor uw organisatie wijzigen.

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

Hier is een voorbeeld van een teller die een afzonderlijke waarde onderhoudt voor PR's en CI-uitvoeringen.

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

Tellers zijn beperkt tot een pijplijn. Met andere woorden, de waarde wordt bij elke uitvoering van die pijplijn verhoogd. Er zijn geen projectgebonden tellers.

eindigtOp

  • Evalueert of de tekenreeks van de linkerparameter eindigt True met de rechterparameter
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Casteert parameters naar String ter evaluatie
  • Hiermee wordt ordinale ignore-casevergelijking uitgevoerd
  • Voorbeeld: endsWith('ABCDE', 'DE') (retourneert waar)

Eq

  • Evalueert True of parameters gelijk zijn
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Hiermee converteert u de rechterparameter zodat deze overeenkomt met het type linkerparameter. Retourneert False als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Voorbeeld: eq(variables.letters, 'ABC')

formaat

  • Evalueert de achterlopende parameters en voegt deze in de leidende parameterreeks in
  • Minimale parameters: 1. Maximum aantal parameters: N
  • Voorbeeld: format('Hello {0} {1}', 'John', 'Doe')
  • Maakt gebruik van aangepaste datum- en tijdnotatieaanduidingen voor .NET voor datumopmaak (yyyy, yy, MMMdd, dHHHmmmsssf, ff, ) ffffK
  • Voorbeeld: format('{0:yyyyMMdd}', pipeline.startTime). In dit geval pipeline.startTime is een speciale datum/tijd-objectvariabele.
  • Escape door accolades te verdubbelen. Bijvoorbeeld: format('literal left brace {{ and literal right brace }}')

Ge

  • Evalueert True of de linkerparameter groter is dan of gelijk is aan de rechterparameter
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Hiermee converteert u de rechterparameter zodat deze overeenkomt met het type linkerparameter. Fouten als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Voorbeeld: ge(5, 5) (retourneert waar)

Gt

  • Evalueert True of de linkerparameter groter is dan de rechterparameter
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Hiermee converteert u de rechterparameter zodat deze overeenkomt met het type linkerparameter. Fouten als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Voorbeeld: gt(5, 2) (retourneert waar)

in

  • Evalueert True of de linkerparameter gelijk is aan een rechterparameter
  • Minimale parameters: 1. Maximum aantal parameters: N
  • Hiermee worden de parameters aan de rechterkant geconverteerd om te passen bij het type van de linkerparameter. Gelijkheidsvergelijking evalueert False of conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Kortsluiting na eerste match
  • Voorbeeld: in('B', 'A', 'B', 'C') (retourneert waar)

IIF

  • Retourneert de tweede parameter als de eerste parameter True evalueert, en anders de derde parameter.
  • Minimale parameters: 1. Maximum aantal parameters: 3
  • De eerste parameter moet een voorwaarde zijn
  • Voorbeeld: iif(eq(variables['Build.Reason'], 'PullRequest'), 'ManagedDevOpsPool', 'Azure Pipelines') retourneert 'ManagedDevOpsPool' wanneer de pijplijn wordt uitgevoerd als reactie op een pull request.

deelnemen

  • Voegt alle elementen in de rechterparameterarray samen, gescheiden door de linkerparameterstring.
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Elk element in de matrix wordt geconverteerd naar een tekenreeks. Complexe objecten worden geconverteerd naar een lege tekenreeks.
  • Als de juiste parameter geen matrix is, is het resultaat de juiste parameter die is geconverteerd naar een tekenreeks.

In dit voorbeeld wordt een puntkomma toegevoegd tussen elk item in de matrix. Het parametertype is een object.

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

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

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

Le

  • Evalueert True of de linkerparameter kleiner is dan of gelijk is aan de rechterparameter
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Hiermee converteert u de rechterparameter zodat deze overeenkomt met het type linkerparameter. Fouten als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Voorbeeld: le(2, 2) (retourneert waar)

lengte

  • Retourneert de lengte van een tekenreeks of een matrix, een tekenreeks die afkomstig is van het systeem of die afkomstig is van een parameter
  • Minimale parameters: 1. Maximum aantal parameters 1
  • Voorbeeld: length('fabrikam') retourneert 8

verlagen

  • Converteert een tekenreeks of variabele waarde naar alle kleine letters
  • Minimale parameters: 1. Maximum aantal parameters 1
  • Retourneert het equivalent in kleine lettertekens van een tekenreeks
  • Voorbeeld: lower('FOO') retourneert foo

Lt

  • Evalueert True of de linkerparameter kleiner is dan de rechterparameter
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Hiermee converteert u de rechterparameter zodat deze overeenkomt met het type linkerparameter. Fouten als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Voorbeeld: lt(2, 5) (retourneert waar)

Ne

  • Evalueert True of parameters niet gelijk zijn
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Hiermee converteert u de rechterparameter zodat deze overeenkomt met het type linkerparameter. Retourneert True als de conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Voorbeeld: ne(1, 2) (retourneert waar)

niet

  • Evalueert True wanneer de parameter False is.
  • Minimale parameters: 1. Maximum aantal parameters: 1
  • Converteert waarde naar Booleaanse waarde voor evaluatie
  • Voorbeeld: not(eq(1, 2)) (retourneert waar)

nietIn

  • Evalueert True of de linkerparameter niet gelijk is aan een rechterparameter
  • Minimale parameters: 1. Maximum aantal parameters: N
  • Hiermee worden de parameters aan de rechterkant geconverteerd om te passen bij het type van de linkerparameter. Gelijkheidsvergelijking evalueert False of conversie mislukt.
  • Ordinale ignore-case-vergelijking voor tekenreeksen
  • Kortsluiting na eerste match
  • Voorbeeld: notIn('D', 'A', 'B', 'C') (retourneert waar)

of

  • Evalueert True als er een parameter is True
  • Minimum aantal parameters: 2. Maximum aantal parameters: N
  • Zet parameters om naar een booleaanse waarde voor evaluatie
  • Kortsluiting na de eerste True
  • Voorbeeld: or(eq(1, 1), eq(2, 3)) (retourneert Waar, kortsluiting)

vervangen

  • Retourneert een nieuwe tekenreeks waarin alle exemplaren van een tekenreeks in het huidige exemplaar worden vervangen door een andere tekenreeks
  • Minimumparameters: 3. Maximum aantal parameters: 3
  • replace(a, b, c): retourneert a, met alle exemplaren van b vervangen door c
  • Voorbeeld: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (retourneert http://server/saml/consume)

splitsen

  • Splitst een tekenreeks in subtekenreeksen op basis van de opgegeven scheidingstekens
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • De eerste parameter is de tekenreeks die moet worden gesplitst
  • De tweede parameter is het scheidingsteken
  • Retourneert een matrix met subtekenreeksen. De matrix bevat lege tekenreeksen wanneer de scheidingstekens opeenvolgend of aan het einde van de tekenreeks worden weergegeven
  • Voorbeeld: 
    variables:
- name: environments
  value: prod1,prod2
steps:
  - ${{ each env in split(variables.environments, ',')}}:
    - script: ./deploy.sh --environment ${{ env }}
  • Voorbeeld van het gebruik van split() met 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 }}

begintMet

  • Evalueert True of de tekenreeks van de linkerparameter begint met de rechterparameter
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Casteert parameters naar String ter evaluatie
  • Hiermee wordt ordinale ignore-casevergelijking uitgevoerd
  • Voorbeeld: startsWith('ABCDE', 'AB') (retourneert waar)

bijknippen

  • Geeft de parameter terug zonder voorloop- en volgspaties
  • Minimale parameters: 1. Maximum aantal parameters: 1
  • Voorbeeld: trim(' variable ') retourneert 'variabele'

bovenste

  • Converteert een tekenreeks of variabele waarde naar alle hoofdletters
  • Minimale parameters: 1. Maximum aantal parameters 1
  • Geeft het hoofdletter-equivalent van een string
  • Voorbeeld: upper('bah') retourneert BAH

Xor

  • Evalueert True wanneer precies één parameter True is
  • Minimum aantal parameters: 2. Maximum aantal parameters: 2
  • Zet parameters om naar een booleaanse waarde voor evaluatie
  • Voorbeeld: xor(True, False) (retourneert waar)

Functies voor taakstatuscontrole

U kunt de volgende statuscontrolefuncties gebruiken als expressies in voorwaarden, maar niet in variabeledefinities.

altijd

  • Evalueert altijd naar True (zelfs wanneer geannuleerd). Opmerking: Een kritieke fout kan nog steeds voorkomen dat een taak wordt uitgevoerd. Als het ophalen van bronnen bijvoorbeeld is mislukt.

Geannuleerd

  • Evalueert tot True als de pijplijn is geannuleerd.

mislukt

  • Voor een stap, gelijk aan eq(variables['Agent.JobStatus'], 'Failed').
  • Voor een baan:
    • Zonder argumenten evalueert alleen True als een eerdere taak in de afhankelijkheidsgrafiek is mislukt.
    • Met taaknamen als argumenten wordt er alleen geëvalueerd naar True als een van die taken is mislukt.

Geslaagd

  • Voor een stap, gelijk aan in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Gebruik dependsOn wanneer u werkt met taken en wilt evalueren of een eerdere taak is geslaagd. Taken zijn ontworpen om parallel te worden uitgevoerd terwijl fasen opeenvolgend worden uitgevoerd.
  • Voor een baan:
    • Zonder argumenten resulteert in True alleen als alle vorige taken in de afhankelijkheidsgraaf zijn geslaagd of gedeeltelijk zijn geslaagd.
    • Met taaknamen als argumenten wordt geëvalueerd True of al deze taken zijn geslaagd of gedeeltelijk zijn geslaagd.
    • Evalueert als False als de pijplijn is geannuleerd.

geslaagdOfMislukt

  • Voor een stap, gelijk aan in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

  • Voor een baan:

    • Zonder argumenten resulteert het in True, ongeacht of taken in de afhankelijkheidsgrafiek zijn geslaagd of mislukt.
    • Met taaknamen als argumenten wordt geëvalueerd True of een van deze taken is geslaagd of mislukt.
    • U kunt in plaats daarvan gebruiken not(canceled()) wanneer er eerdere overgeslagen taken in de afhankelijkheidsgrafiek staan.

    Dit is zoals always(), behalve dat het False evalueert wanneer de pijplijn wordt geannuleerd.

Voorwaardelijke invoeging

U kunt de if, elseif en else clausules gebruiken om variabele waarden voorwaardelijk toe te wijzen of invoer voor taken in te stellen. U kunt ook een stap voorwaardelijk uitvoeren wanneer aan een voorwaarde wordt voldaan.

U kunt if gebruiken om variabelenwaarden voorwaardelijk toe te wijzen, of invoer voor taken in te stellen. U kunt ook een stap voorwaardelijk uitvoeren wanneer aan een voorwaarde wordt voldaan.

De elseif en else componenten zijn beschikbaar vanaf Azure DevOps 2022 en zijn niet beschikbaar voor Azure DevOps Server 2020 en eerdere versies van Azure DevOps.

Voorwaardelijke voorwaarden werken alleen bij het gebruik van sjabloonsyntaxis. Meer informatie over de syntaxis van variabelen.

Voor sjablonen kunt u voorwaardelijke invoeging gebruiken bij het toevoegen van een sequentie of toewijzing. Meer informatie over voorwaardelijke invoeging in sjablonen.

Voorwaardelijk een variabele toewijzen

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

Een taakinvoer voorwaardelijk instellen

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'

Een stap voorwaardelijk uitvoeren

Als er geen variabelenset is of als de waarde foo niet overeenkomt met de if voorwaarden, wordt de else instructie uitgevoerd. Hier geeft de waarde foo waar in de elseif voorwaarde.

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"

Elk trefwoord

U kunt het each trefwoord gebruiken om parameters te doorlopen met het objecttype.

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

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

Daarnaast kunt u door geneste elementen binnen een object itereren.

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

Afhankelijkheden

Expressies kunnen de context van afhankelijkheden gebruiken om te verwijzen naar eerdere taken of fasen. U kunt afhankelijkheden gebruiken voor het volgende:

  • Verwijs naar de status van een eerdere taak
  • Verwijzen naar de fasestatus van een vorige fase
  • Referentie-uitvoervariabelen in de vorige taak in dezelfde fase
  • Verwijs in een fase naar de uitvoervariabelen uit de vorige fase.
  • Verwijs naar uitvoervariabelen van een taak in een vorige fase in de volgende fase

De context wordt aangeroepen dependencies voor taken en fasen en werkt vergelijkbaar met variabelen. Als u verwijst naar een uitvoervariabele van een taak in een andere fase, wordt de context aangeroepen stageDependencies.

Als u problemen ondervindt met uitvoervariabelen met aanhalingstekens (' of ") in deze variabelen, raadpleegt u deze gids voor probleemoplossing.

Overzicht van syntaxis van afhankelijkheden

De syntaxis van het verwijzen naar uitvoervariabelen met afhankelijkheden is afhankelijk van de omstandigheden. Hier volgt een overzicht van de meest voorkomende scenario's. Het kan voorkomen dat alternatieve syntaxis ook werkt.

Typ

Beschrijving

fase tot faseafhankelijkheid (verschillende fasen)

Verwijs naar een uitvoervariabele uit een eerdere fase in een taak in een andere fase bij een voorwaarde in stages.

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

taak naar taakafhankelijkheid (dezelfde fase)

Verwijzen naar een uitvoervariabele in een andere taak in dezelfde fase in stages.

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

Taak afhankelijk van fase (verschillende stadia)

Verwijzen naar een uitvoervariabele in een andere fase in een job.

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

Fase-op-fase afhankelijkheid (implementatietaak)

Referentie-uitvoervariabele in een implementatietaak in een andere fase in stages.

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

Fase-naar-fase-afhankelijkheid (implementatietaak met resource)

Verwijs naar een uitvoervariabele in een deploymenttaak die een resource in een andere fase bevat binnen stages.

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

Er zijn ook verschillende syntaxis voor uitvoervariabelen in implementatietaken, afhankelijk van de implementatiestrategie. Zie Implementatietaken voor meer informatie.

Fase-naar-fase-afhankelijkheden

Structureel is het dependencies object een kaart van taak- en fasenamen aan results en outputs. Uitgedrukt als JSON, ziet het er als volgt uit:

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

Notitie

In de volgende voorbeelden wordt de standaard pijplijn syntaxis gebruikt. Als u implementatiepijplijnen gebruikt, verschillen zowel de syntaxis van de variabele als de voorwaardelijke variabele. Zie Implementatietaken voor meer informatie over de specifieke syntaxis die u wilt gebruiken.

Gebruik dit formulier van dependencies om variabelen in te voeren of om voorwaarden te controleren op faseniveau.

In dit voorbeeld zijn er twee fasen: A en B. Fase A heeft de voorwaarde false en wordt nooit uitgevoerd als gevolg hiervan. Fase B wordt uitgevoerd als het resultaat van fase A Succeeded, SucceededWithIssues, of Skipped. Fase B wordt uitgevoerd omdat fase A is overgeslagen.

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

Fasen kunnen ook uitvoervariabelen uit een andere fase gebruiken. In dit voorbeeld zijn er ook twee fasen. Fase A bevat een taak, A1, waarmee een uitvoervariabele shouldrun wordt ingesteld op true. Fase B wordt uitgevoerd wanneer shouldruntrue. Omdat shouldruntrue is, wordt fase B uitgevoerd.

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

Notitie

Standaard is elke fase in een pijplijn afhankelijk van de fase vlak voordat deze zich in het YAML-bestand bevindt. Als u wilt verwijzen naar een fase die zich niet direct vóór de huidige fase bevindt, kunt u deze automatische standaardinstelling overschrijven door een dependsOn sectie toe te voegen aan de fase.

Afhankelijkheden van taak naar taak binnen één fase

Op taakniveau in één fase bevatten de dependencies gegevens geen informatie op faseniveau.

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

In dit voorbeeld zijn er drie taken (a, b en c). Job a zal altijd worden overgeslagen vanwege condition: false. Taak b wordt uitgevoerd omdat er geen gekoppelde voorwaarden zijn. Omdat alle afhankelijkheden van taak c of zijn geslaagd (taak b) of zijn overgeslagen (taak a), wordt taak c uitgevoerd.

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

In dit voorbeeld is taak B afhankelijk van een uitvoervariabele van taak 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

Afhankelijkheden van taak tot taak tussen stappen

Op taakniveau kunt u ook verwijzen naar uitvoer van een taak in een vorige fase. Hiervoor moet u de stageDependencies context gebruiken.

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

In dit voorbeeld wordt taak B1 uitgevoerd als taak A1 wordt overgeslagen. Taak B2 controleert de waarde van de uitvoervariabele van taak A1 om te bepalen of deze moet worden uitgevoerd.

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

Als een taak afhankelijk is van een variabele die is gedefinieerd door een implementatietaak in een andere fase, is de syntaxis anders. In het volgende voorbeeld wordt de taak run_tests uitgevoerd als de build_job implementatietaak is ingesteld op runTeststrue. U ziet dat de sleutel die voor de outputs woordenlijst wordt gebruikt, is 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:
        ...

Uitvoervariabelen voor implementatietaak

Als een fase afhankelijk is van een variabele die is gedefinieerd door een implementatietaak in een andere fase, is de syntaxis anders. In het volgende voorbeeld is de fase test afhankelijk van de implementatie-instelling build_job in shouldTesttrue. U ziet dat in de conditiontest fase build_job twee keer voorkomt.

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

In het bovenstaande voorbeeld verwijst de voorwaarde naar een omgeving en niet naar een omgevingsresource. Als u naar een omgevingsresource wilt verwijzen, moet u de naam van de omgevingsresource toevoegen aan de voorwaarde voor afhankelijkheden. In het volgende voorbeeld verwijst de voorwaarde naar een omgevingsresource van de virtuele machine met de naam 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

Gefilterde matrices

Wanneer u werkt op een verzameling items, kunt u de * syntaxis gebruiken om een gefilterde matrix toe te passen. Een gefilterde matrix retourneert alle objecten/elementen, ongeacht hun namen.

Denk bijvoorbeeld aan een matrix met objecten met de naam foo. We willen een matrix ophalen van de waarden van de id eigenschap in elk object in onze matrix.

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

We kunnen het volgende doen:

foo.*.id

Dit instrueert het systeem om foo als een gefilterde reeks te gebruiken en vervolgens de id eigenschap te selecteren.

Dit zou teruggeven:

[ 1, 2, 3 ]

Typeconversie

Waarden in een expressie kunnen worden geconverteerd van het ene type naar het andere wanneer de expressie wordt geëvalueerd. Wanneer een expressie wordt geëvalueerd, worden de parameters samengevoegd tot het relevante gegevenstype en vervolgens weer omgezet in tekenreeksen.

In deze YAML worden bijvoorbeeld de waarden TrueFalse geconverteerd naar 1 en 0 wanneer de expressie wordt geëvalueerd. De functie lt() retourneert True wanneer de linkerparameter kleiner is dan de rechterparameter.

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

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

Wanneer u de expressie gebruikt voor het eq() evalueren van gelijkwaardigheid, worden waarden impliciet geconverteerd naar getallen (false naar 0 en true naar 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)

In dit volgende voorbeeld worden de waarden variables.emptyString en de lege tekenreeks beide geëvalueerd als lege tekenreeksen. De functie coalesce() evalueert de parameters in volgorde en retourneert de eerste waarde die niet gelijk is aan null of lege tekenreeks.

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

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

Gedetailleerde conversieregels worden hieronder weergegeven.

Van/naar Booleaans Nul Aantal Snaar / Touwtje Versie
Booleaans - - Ja Ja -
Nul Ja - Ja Ja -
Nummer Ja - - Ja Gedeeltelijk
Tekenreeks Ja Gedeeltelijk Gedeeltelijk - Gedeeltelijk
Versie Ja - - Ja -

Booleaans

Nummer:

  • False → 0
  • True → 1

Om te converteren naar een tekenreeks:

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

Nul

  • Omzetten naar Booleaanse waarde: False
  • Nummer: 0
  • Naar tekenreeks: '' (de lege tekenreeks)

Aantal

  • Naar Booleaanse waarde: 0 → False, een ander getal → True
  • Naar versie: moet groter zijn dan nul en moet een decimaal die niet nul is bevatten. Moet kleiner zijn dan Int32.MaxValue (decimaal onderdeel ook).
  • Naar tekenreeks: converteert het getal naar een tekenreeks zonder scheidingsteken voor duizendtallen en geen decimaalteken.

Snaar / Touwtje

  • Naar Booleaanse waarde: '' (de lege tekenreeks) → False, elke andere tekenreeks → True
  • Naar null: '' (de lege tekenreeks) → Null, elke andere tekenreeks die niet converteerbaar is
  • Naar getal: '' (de lege tekenreeks) → 0, anders wordt C#'s Int32.TryParse uitgevoerd met behulp van InvariantCulture en de volgende regels: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. Als TryParse mislukt, is het niet converteerbaar.
  • Naar versie: voert C#'s Version.TryParse uit. Moet minimaal primaire en secundaire onderdelen bevatten. Als TryParse mislukt, is het niet converteerbaar.

Versie

  • Omzetten naar Booleaanse waarde: True
  • Naar tekenreeks: Major.Minor of Major.Minor.Build of Major.Minor.Build.Revision.

Veelgestelde vragen

Ik wil iets doen dat niet wordt ondersteund door expressies. Welke opties heb ik voor het uitbreiden van de functionaliteit van pijplijnen?

U kunt uw pijplijn aanpassen met een script dat een expressie bevat. Dit fragment neemt bijvoorbeeld de BUILD_BUILDNUMBER variabele en splitst deze met Bash. Met dit script worden twee nieuwe variabelen $MAJOR_RUN en $MINOR_RUN gegenereerd, voor de belangrijkste en minder belangrijke runnummers. De twee variabelen worden vervolgens gebruikt om twee pijplijnvariabelen $major te maken en $minor met task.setvariable. Deze variabelen zijn beschikbaar voor downstreamstappen. Als u variabelen tussen pijplijnen wilt delen, raadpleegt u Variabelegroepen.

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