Expressies

  • Artikel

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

Belangrijk

Select a version from 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). Met een statische variabele in een compile-expressie wordt de waarde van $(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

Een expressie kan een letterlijke waarde 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 letterlijke waarden voor 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 }}

Boolean

True en False zijn booleaanse letterlijke expressies.

Null

Null is een speciale letterlijke expressie die wordt geretourneerd door een woordenlijstmisser, 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'.

String

Moet een enkele aan citering zijn. 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 eigenschapsdeductie: variables.MyVar

Als u de syntaxis voor eigenschapsdeductie wilt 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 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 of True alle parameters True
  • Minimale parameters: 2. Maximum aantal parameters: N
  • Casts parameters naar Booleaanse waarde voor evaluatie
  • Kortsluiting na eerste False
  • Voorbeeld: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

samenvoeging

  • 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.
  • Minimale 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
  • Minimale parameters: 2. Maximum aantal parameters: 2
  • Cast parameters naar String voor evaluatie
  • Hiermee wordt ordinale ignore-casevergelijking uitgevoerd
  • Voorbeeld: contains('ABCDE', 'BCD') (retourneert Waar)

containsValue

  • 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.
  • Minimale 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 overeenkomst

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 volgt een voorbeeld waarin wordt getoond hoe u in een lijst met bronbranches zoekt voor 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"

convertToJson

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

counter

  • 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. UTF-16 prefix tekens moeten worden gebruikt.
  • Seed 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 dit 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 1 instelt op 1, wordt de waarde van de teller hervat waar het was gebleven voor dat voorvoegsel. In dit voorbeeld wordt het hervat op 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 volgt een voorbeeld van het hebben van een teller die een afzonderlijke waarde onderhoudt voor PULL's en CI-uitvoeringen.

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

Tellers zijn gericht op een pijplijn. Met andere woorden, de waarde wordt verhoogd voor elke uitvoering van die pijplijn. Er zijn geen projectbereiktellers.

endsWith

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

eq

  • Evalueert True of parameters gelijk zijn
  • Minimale 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')

indeling

  • Evalueert de volgparameters en voegt deze in de voorloopparametertekenreeks 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, MMddM, mmHHHdfsmss, ff, ) ffffK
  • Voorbeeld: format('{0:yyyyMMdd}', pipeline.startTime). In dit geval pipeline.startTime is een speciale datum/tijd-objectvariabele.
  • Ontsnap 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
  • Minimale 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
  • Minimale 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 juiste parameters geconverteerd zodat deze overeenkomen met het type 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)

join

  • Voegt alle elementen in de rechterparametermatrix samen, gescheiden door de linkerparametertekenreeks.
  • Minimale 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
  • Minimale 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)

length

  • 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

Lagere

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

lt

  • Evalueert True of de linkerparameter kleiner is dan de rechterparameter
  • Minimale 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
  • Minimale 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)

not

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

notIn

  • Evalueert True of de linkerparameter niet gelijk is aan een rechterparameter
  • Minimale parameters: 1. Maximum aantal parameters: N
  • Hiermee worden de juiste parameters geconverteerd zodat deze overeenkomen met het type 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 of een parameter is True
  • Minimale parameters: 2. Maximum aantal parameters: N
  • Casts parameters naar Booleaanse waarde voor evaluatie
  • Kortsluiting na eerste True
  • Voorbeeld: or(eq(1, 1), eq(2, 3)) (retourneert Waar, korte circuits)

replace

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

split

  • Splitst een tekenreeks in subtekenreeksen op basis van de opgegeven scheidingstekens
  • Minimale parameters: 2. Maximum aantal parameters: 2
  • De eerste parameter is de tekenreeks die moet worden gesplitst
  • De tweede parameter is de scheidingstekens
  • 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 }}

startsWith

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

Bovenste

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

xor

  • Evalueert True of precies één parameter is True
  • Minimale parameters: 2. Maximum aantal parameters: 2
  • Casts parameters naar 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 ( 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 of True de pijplijn is geannuleerd.

mislukt

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

Geslaagd

  • Voor een stap, gelijk aan in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
  • Gebruik deze functie dependsOn bij het werken met taken en u wilt evalueren of een eerdere taak is geslaagd. Taken zijn ontworpen om parallel te worden uitgevoerd terwijl fasen opeenvolgend worden uitgevoerd.
  • Voor een taak:
    • Zonder argumenten wordt alleen geëvalueerd als alle vorige taken in de afhankelijkheidsgrafiek True 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 of False de pijplijn is geannuleerd.

succeededOrFailed

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

  • Voor een taak:

    • Zonder argumenten wordt geëvalueerd, ongeacht of taken in de afhankelijkheidsgrafiek True 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 als always()volgt, behalve dat deze evalueert False wanneer de pijplijn wordt geannuleerd.

Voorwaardelijke invoeging

U kunt , elseifen else componenten gebruiken ifom variabele waarden voorwaardelijk toe te wijzen of invoer in te stellen voor taken. U kunt ook een stap voorwaardelijk uitvoeren wanneer aan een voorwaarde wordt voldaan.

U kunt if variabelenwaarden voorwaardelijk toewijzen of invoer instellen voor taken. 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 reeks 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 variabele is ingesteld of de waarde foo ervan niet overeenkomt met de if voorwaarden, wordt de else instructie uitgevoerd. Hier retourneert 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 geneste elementen in een object herhalen.

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:

  • Verwijzen naar de taakstatus van een vorige taak
  • Verwijzen naar de fasestatus van een vorige fase
  • Referentie-uitvoervariabelen in de vorige taak in dezelfde fase
  • Referentie-uitvoervariabelen in de vorige fase in een fase
  • Referentie-uitvoervariabelen in 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. Houd er rekening mee dat er soms ook alternatieve syntaxis werkt.

Type

Beschrijving

fase tot faseafhankelijkheid (verschillende fasen)

Verwijzen naar een uitvoervariabele uit een vorige fase in een taak in een andere fase in 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.<stage-name>.outputs['<step-name>.<variable-name>'], 'true'))
  • Voorbeeld: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))

Taak voor faseafhankelijkheid (verschillende fasen)

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 van 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 implementatietaak die een resource in een andere fase bevat 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 worden standaardpijplijnsyntaxis 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 deze vorm van het toewijzen in variabelen of het controleren van dependencies voorwaarden 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 , SucceededSucceededWithIssuesof 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 shouldrun .true Omdat shouldrun , wordt truefase 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.

Taak-naar-taakafhankelijkheden 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. Taak c wordt uitgevoerd omdat alle afhankelijkheden zijn geslaagd (taak b) of worden overgeslagen (taak 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

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

Taak-naar-taakafhankelijkheden in verschillende fasen

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 wordt weergegeven.

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 geeft aan dat het systeem moet worden gebruikt foo als een gefilterde matrix en vervolgens de id eigenschap selecteert.

Dit retourneert:

[ 1, 2, 3 ]

Type cast-conversie

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)

In dit voorbeeld worden de waarden variables.emptyString en de lege tekenreeks beide geëvalueerd als lege tekenreeksen. De functie coalesce() evalueert de parameters op 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 Boolean Null Aantal String Versie
Boolean - - Ja Ja -
Null Ja - Ja Ja -
Aantal Ja - - Ja Gedeeltelijk
Tekenreeks Ja Gedeeltelijk Gedeeltelijk - Gedeeltelijk
Versie Ja - - Ja -

Boolean

Nummer:

  • False → 0
  • True → 1

Tekenreeks:

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

Null

  • 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 niet-nuldecimaal 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.

String

  • 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 het mislukt, is het niet converteerbaar.
  • Naar versie: voert C#'s Version.TryParseuit. Moet minimaal primaire en secundaire onderdelen bevatten. Als TryParse het mislukt, is het niet converteerbaar.

Versie

  • 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 uitgevoerd, en $MINOR_RUNvoor de primaire en secundaire uitvoeringsnummers. 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)"