Espressioni

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

Un altro uso comune delle espressioni consiste nella definizione delle variabili. Le espressioni possono essere valutate in fase di compilazione o in fase di esecuzione. Le espressioni in fase di compilazione possono essere usate ovunque; Le espressioni di runtime possono essere usate in variabili e condizioni. Le espressioni di runtime sono concepite come un modo per calcolare il contenuto delle variabili e dello stato (ad esempio: 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> ]

La differenza tra la sintassi delle espressioni in fase di compilazione e runtime è principalmente il contesto disponibile. In un'espressione in fase di compilazione (${{ <expression> }}) è possibile accedere a parameters e definire variablesstaticamente . In un'espressione di runtime ($[ <expression> ]) è possibile accedere a più variables parametri, ma non a parametri.

In questo esempio, un'espressione di runtime imposta il valore di $(isMain). Una variabile statica in un'espressione di compilazione imposta il valore di $(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

coalesce

• Valuta i parametri in ordine (da sinistra a destra) e restituisce il primo valore che non è null o empty-string.
• Non viene restituito alcun valore se i valori dei parametri sono tutte stringhe null o vuote.
• Parametri min: 2. Numero massimo di parametri: N
• Esempio: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Accettare un oggetto complesso e lo restituisce come JSON.
• Parametri min: 1. Numero massimo di parametri: 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) }}

Output dello script:

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

counter

• Questa funzione può essere usata solo in un'espressione che definisce una variabile. Non può essere usato come parte di una condizione per un passaggio, un processo o una fase.
• Valuta un numero incrementato con ogni esecuzione di una pipeline.
• Parametri: 2. prefix e seed.
• Il prefisso è un'espressione stringa. Viene rilevato un valore separato del contatore per ogni valore univoco del prefisso. Deve prefix usare caratteri UTF-16.
• Seed è il valore iniziale del contatore

È possibile creare un contatore incrementato automaticamente di uno in ogni esecuzione della pipeline. Quando si definisce un contatore, si specifica un prefix oggetto e un oggetto seed. Di seguito è riportato un esempio che illustra questa operazione.

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)

Il valore di minor nell'esempio precedente nella prima esecuzione della pipeline è 100. Nella seconda esecuzione è 101, purché il valore di major sia ancora 1.

Se si modifica il file YAML e si aggiorna il valore della variabile major su 2, nell'esecuzione successiva della pipeline il valore di minor sarà 100. Le esecuzioni successive incrementano il contatore a 101, 102, 103, ...

Successivamente, se si modifica il file YAML e si imposta il valore di major su 1, il valore del contatore riprende dove è rimasto per tale prefisso. In questo esempio riprende a 102.

Ecco un altro esempio di impostazione di una variabile da usare come contatore che inizia da 100, viene incrementato di 1 per ogni esecuzione e viene reimpostato su 100 ogni giorno.

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

Di seguito è riportato un esempio di presenza di un contatore che mantiene un valore separato per le richieste pull e le esecuzioni ci.

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

I contatori hanno come ambito una pipeline. In altre parole, il valore viene incrementato per ogni esecuzione della pipeline. Non sono presenti contatori con ambito progetto.

format

• Valuta i parametri finali e li inserisce nella stringa del parametro iniziale
• Parametri min: 1. Numero massimo di parametri: N
• Esempio: format('Hello {0} {1}', 'John', 'Doe')
• Usa identificatori di formato di data e ora personalizzati .NET per la formattazione della data (yyyy, yy, MMM, , dd, mffffdfffHHsssmmH) K
• Esempio: format('{0:yyyyMMdd}', pipeline.startTime). In questo caso pipeline.startTime è una variabile di oggetto data/ora speciale.
• Escape raddoppiando le parentesi graffe. Ad esempio: format('literal left brace {{ and literal right brace }}')

join

• Concatena tutti gli elementi nella matrice di parametri destra, separati dalla stringa del parametro a sinistra.
• Parametri min: 2. Numero massimo di parametri: 2
• Ogni elemento della matrice viene convertito in una stringa. Gli oggetti complessi vengono convertiti in stringa vuota.
• Se il parametro corretto non è una matrice, il risultato è il parametro corretto convertito in una stringa.

In questo esempio viene aggiunto un punto e virgola tra ogni elemento della matrice. Il tipo di parametro è un oggetto .

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

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

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

lower

• Converte un valore stringa o variabile in tutti i caratteri minuscoli
• Parametri min: 1. Max parameters 1
• Restituisce l'equivalente minuscolo di una stringa
• Esempio: lower('FOO') restituisce foo

replace

• Restituisce una nuova stringa in cui tutte le istanze di una stringa nell'istanza corrente vengono sostituite con un'altra stringa
• Parametri min: 3. Numero massimo di parametri: 3
• replace(a, b, c): restituisce un oggetto , con tutte le istanze di b sostituite da c
• Esempio: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (restituisce http://server/saml/consume)

split

• Suddivide una stringa in sottostringhe in base ai caratteri di delimitazione specificati
• Parametri min: 2. Numero massimo di parametri: 2
• Il primo parametro è la stringa da dividere
• Il secondo parametro è costituito dai caratteri delimitatori
• Restituisce una matrice di sottostringhe. La matrice include stringhe vuote quando i caratteri di delimitazione vengono visualizzati consecutivamente o alla fine della stringa
• Esempio:

  variables:
  - name: environments
    value: prod1,prod2 
  steps:  
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Esempio di uso di split() con 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 }}
  

upper

• Converte un valore stringa o variabile in tutti i caratteri maiuscoli
• Parametri min: 1. Max parameters 1
• Restituisce l'equivalente maiuscolo di una stringa
• Esempio: upper('bah') restituisce BAH

È possibile usare ifle clausole , elseife else per assegnare in modo condizionale i valori delle variabili o impostare gli input per le attività. È anche possibile eseguire in modo condizionale un passaggio quando viene soddisfatta una condizione.

È possibile usare if per assegnare in modo condizionale i valori delle variabili o impostare gli input per le attività. È anche possibile eseguire in modo condizionale un passaggio quando viene soddisfatta una condizione.

Le elseif clausole e else sono disponibili a partire da Azure DevOps 2022 e non sono disponibili per Azure DevOps Server 2020 e versioni precedenti di Azure DevOps.

Impostare in modo condizionale un input dell'attività

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'

Eseguire in modo condizionale un passaggio

Se non è presente alcun set di variabili o il valore di foo non corrisponde alle if condizioni, l'istruzione else viene eseguita. In questo caso il valore di foo restituisce true nella elseif condizione.

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"

Parola chiave each

È possibile usare la each parola chiave per scorrere i parametri con il tipo di oggetto.

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

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

Inoltre, è possibile scorrere gli elementi annidati all'interno di un oggetto .

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

Dipendenze

Le espressioni possono usare il contesto delle dipendenze per fare riferimento a processi o fasi precedenti. È possibile usare le dipendenze per:

• Fare riferimento allo stato del processo di un processo precedente
• Fare riferimento allo stato della fase di una fase precedente
• Fare riferimento alle variabili di output nel processo precedente nella stessa fase
• Fare riferimento alle variabili di output nella fase precedente in una fase
• Fare riferimento alle variabili di output in un processo in una fase precedente nella fase seguente

Il contesto viene chiamato dependencies per processi e fasi e funziona in modo molto simile alle variabili. Se si fa riferimento a una variabile di output da un processo in un'altra fase, il contesto viene chiamato stageDependencies.

Se si verificano problemi con le variabili di output con caratteri virgolette (' o ") in essi, vedere questa guida alla risoluzione dei problemi.

Panoramica della sintassi delle dipendenze

La sintassi di riferimento alle variabili di output con le dipendenze varia a seconda delle circostanze. Ecco una panoramica degli scenari più comuni. Potrebbero verificarsi momenti in cui funziona anche la sintassi alternativa.

Esistono anche sintassi diverse per le variabili di output nei processi di distribuzione a seconda della strategia di distribuzione. Per altre informazioni, vedere Processi di distribuzione.

Fasi per la gestione temporanea delle dipendenze

Strutturalmente, l'oggetto dependencies è una mappa dei nomi di processo e di fase a results e outputs. Espresso come JSON, sarà simile al seguente:

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

Utilizzare questo formato di dependencies per eseguire il mapping in variabili o controllare le condizioni a livello di fase.

In questo esempio sono presenti due fasi, A e B. Fase A ha la condizione false e non verrà mai eseguita di conseguenza. La fase B viene eseguita se il risultato della fase A è Succeeded, SucceededWithIssueso Skipped. La fase B viene eseguita perché la fase A è stata ignorata.

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

Le fasi possono anche usare variabili di output da un'altra fase. In questo esempio sono presenti anche due fasi. La fase A include un processo, A1, che imposta una variabile shouldrun di output su true. La fase B viene eseguita quando shouldrun è true. Poiché shouldrun è true, viene eseguita la fase 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

Dipendenze da processo a processo all'interno di una fase

A livello di processo all'interno di una singola fase, i dependencies dati non contengono informazioni a livello di fase.

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

In questo esempio sono presenti tre processi (a, b e c). Il processo verrà sempre ignorato a causa di condition: false. Il processo b viene eseguito perché non sono presenti condizioni associate. Il processo c viene eseguito perché tutte le relative dipendenze hanno esito positivo (processo b) o vengono ignorate (processo 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 questo esempio il processo B dipende da una variabile di output del processo 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

Dipendenze da processo a fasi diverse

A livello di processo, è anche possibile fare riferimento agli output di un processo in una fase precedente. Ciò richiede l'uso del stageDependencies contesto.

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

In questo esempio, il processo B1 viene eseguito se il processo A1 viene ignorato. Il processo B2 controlla il valore della variabile di output del processo A1 per determinare se deve essere eseguito.

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

Se un processo dipende da una variabile definita da un processo di distribuzione in una fase diversa, la sintassi è diversa. Nell'esempio seguente il processo run_tests viene eseguito se il build_job processo di distribuzione è impostato su runTests true. Si noti che la chiave usata per il outputs dizionario è 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:
        ...

Variabili di output del processo di distribuzione

Se una fase dipende da una variabile definita da un processo di distribuzione in una fase diversa, la sintassi è diversa. Nell'esempio seguente la fase test dipende dall'impostazione shouldTest di distribuzione build_job su true. Si noti che nella fase condition test viene build_job visualizzato due volte.

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

Nell'esempio precedente la condizione fa riferimento a un ambiente e non a una risorsa di ambiente. Per fare riferimento a una risorsa di ambiente, è necessario aggiungere il nome della risorsa di ambiente alla condizione delle dipendenze. Nell'esempio seguente la condizione fa riferimento a una risorsa macchina virtuale dell'ambiente denominata 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