Parametri di runtime

Articolo
07/03/2023

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

I parametri di runtime consentono di avere un maggiore controllo sui valori che è possibile passare a una pipeline. Con i parametri di runtime è possibile:

Fornire valori diversi agli script e alle attività in fase di esecuzione
Tipi di parametri di controllo, intervalli consentiti e impostazioni predefinite
Selezionare dinamicamente processi e fasi con espressioni modello

È possibile specificare parametri nei modelli e nella pipeline. I parametri hanno tipi di dati, ad esempio number e string, e possono essere limitati a un subset di valori. La parameters sezione in un YAML definisce i parametri disponibili.

I parametri sono disponibili solo in fase di analisi dei modelli. I parametri vengono espansi subito prima dell'esecuzione della pipeline in modo che i valori racchiusi da ${{ }} vengano sostituiti con i valori dei parametri. Usare le variabili se è necessario che i valori siano più ampiamente disponibili durante l'esecuzione della pipeline.

Nota

Queste linee guida non si applicano alle pipeline classiche. Per i parametri nelle pipeline classiche, vedere Parametri di processo (versione classica).For parameters in classic pipelines, see Process parameters (classic).

I parametri devono contenere un nome e un tipo di dati. I parametri non possono essere facoltativi. È necessario assegnare un valore predefinito nel file YAML o quando si esegue la pipeline. Se non si assegna un valore predefinito o si imposta su defaultfalse, viene usato il primo valore disponibile.

Usare templateContext per passare proprietà aggiuntive a fasi, passaggi e processi usati come parametri in un modello.

Usare i parametri nelle pipeline

Impostare i parametri di runtime all'inizio di un FILE YAML.

Questa pipeline di esempio include un image parametro con tre agenti ospitati come string opzioni. Nella sezione processi il pool valore specifica l'agente dal parametro usato per eseguire il processo. l'oggetto trigger è impostato su nessuno in modo che sia possibile selezionare il valore di image quando si attiva manualmente la pipeline per l'esecuzione.

parameters:
- name: image
  displayName: Pool Image
  type: string
  default: ubuntu-latest
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest

trigger: none

jobs:
- job: build
  displayName: build
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber) with ${{ parameters.image }}

Quando viene eseguita la pipeline, selezionare l'immagine del pool. Se non si effettua una selezione, viene usata l'opzione ubuntu-latest predefinita.

parametri di runtime

Usare le condizionali con i parametri

È anche possibile usare i parametri come parte della logica condizionale. Con le istruzioni condizionali, parte di un FILE YAML viene eseguita se soddisfa i if criteri.

Usare i parametri per determinare i passaggi eseguiti

Questa pipeline aggiunge un secondo parametro booleano, test, che può essere usato per controllare se eseguire o meno i test nella pipeline. Quando il valore di test è true, il passaggio che restituisce Esecuzione di tutti i test viene eseguito.

parameters:
- name: image
  displayName: Pool Image
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest
- name: test
  displayName: Run Tests?
  type: boolean
  default: false

trigger: none

jobs:
- job: build
  displayName: Build and Test
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber)
  - ${{ if eq(parameters.test, true) }}:
    - script: echo "Running all the tests"

Usare i parametri per impostare la configurazione usata

È anche possibile usare i parametri per impostare quali processi vengono eseguiti. In questo esempio le architetture diverse vengono compilate a seconda del valore del config parametro, ovvero un string tipo. Per impostazione predefinita, entrambe le x86 architetture e x64 vengono compilate.

parameters:
- name: configs
  type: string
  default: 'x86,x64'

trigger: none

jobs:
- ${{ if contains(parameters.configs, 'x86') }}:
  - job: x86
    steps:
    - script: echo Building x86...
- ${{ if contains(parameters.configs, 'x64') }}:
  - job: x64
    steps:
    - script: echo Building x64...
- ${{ if contains(parameters.configs, 'arm') }}:
  - job: arm
    steps:
    - script: echo Building arm...

Escludere selettivamente una fase

È anche possibile usare i parametri per impostare se una fase viene eseguita. In questo esempio è presente una pipeline con quattro fasi e processi diversi per ogni fase. La fase Test delle prestazioni viene eseguita se il parametro runPerfTests è true. Il valore predefinito di runPerfTests è false, quindi senza aggiornamenti, vengono eseguite solo tre delle quattro fasi.

parameters:
- name: runPerfTests
  type: boolean
  default: false

trigger: none

stages:
- stage: Build
  displayName: Build
  jobs:
  - job: Build
    steps:
    - script: echo running Build


- stage: UnitTest
  displayName: Unit Test
  dependsOn: Build
  jobs:
  - job: UnitTest
    steps:
    - script: echo running UnitTest


- ${{ if eq(parameters.runPerfTests, true) }}:
  - stage: PerfTest
    displayName: Performance Test
    dependsOn: Build
    jobs:
    - job: PerfTest
      steps:
      - script: echo running PerfTest


- stage: Deploy
  displayName: Deploy
  dependsOn: UnitTest
  jobs:
  - job: Deploy
    steps:
    - script: echo running UnitTest

Eseguire il ciclo dei parametri

È anche possibile scorrere in ciclo i parametri stringa, number e booleani.

Script
PowerShell

In questo esempio si esegue il ciclo dei parametri e si stampano il nome e il valore di ogni parametro. Esistono quattro parametri diversi e ognuno rappresenta un tipo diverso. myStringName è una stringa a riga singola. myMultiString è una stringa a più righe. myNumber is a number. myBoolean è un valore booleano. Nella sezione passaggi le attività script generano la chiave e il valore di ogni parametro.

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true

steps: 
- ${{ each parameter in parameters }}:
  - script: echo ${{ parameter.Key }} 
  - script: echo ${{ parameter.Value }}

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

In questo esempio si esegue il ciclo dei parametri e si stampano il nome e il valore di ogni parametro. Esistono quattro parametri diversi e ognuno rappresenta un tipo diverso. myStringName è una stringa a riga singola. myMultiString è una stringa a più righe. myNumber is a number. myBoolean è un valore booleano. Nella sezione passaggi è possibile scorrere i parametri in un'attività di PowerShell e impostare ogni parametro come variabile di ambiente.

# start.yaml

parameters:
- name: myStringName
  type: string
  default: a string value
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true

steps: 
  - task: PowerShell@2
    env:
      ${{ each parameter in parameters }}:
        ${{ parameter.Key }}: ${{ parameter.Value }}
    inputs:
      filePath: test_script.ps1
      pwsh: true

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

# test_script.ps1

Write-Host "Hello, World!"
Write-Host $env:myStringName

Verificare la presenza di un oggetto parametro vuoto

È possibile usare l'espressione per verificare se un parametro dell'oggetto length() non ha alcun valore.

parameters:
- name: foo
  type: object
  default: []

steps:
- checkout: none
- ${{ if eq(length(parameters.foo), 0) }}:
  - script: echo Foo is empty
    displayName: Foo is empty

Tipi di dati dei parametri

Tipo di dati	Note
`string`	string
`number`	può essere limitato a , in caso contrario viene accettata qualsiasi stringa simile a `values:`un numero
`boolean`	`true` o `false`
`object`	qualsiasi struttura YAML
`step`	un singolo passaggio
`stepList`	sequenza di passaggi
`job`	un singolo processo
`jobList`	sequenza di processi
`deployment`	un singolo processo di distribuzione
`deploymentList`	sequenza di processi di distribuzione
`stage`	una singola fase
`stageList`	sequenza di fasi

I tipi di dati stepList, job, jobList, deployment, deploymentList, stage e stageList usano tutti il formato di schema YAML standard. Questo esempio include string, number, boolean, object, step e stepList.

parameters:
- name: myString
  type: string
  default: a string
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true
- name: myObject
  type: object
  default:
    foo: FOO
    bar: BAR
    things:
    - one
    - two
    - three
    nested:
      one: apple
      two: pear
      count: 3
- name: myStep
  type: step
  default:
    script: echo my step
- name: mySteplist
  type: stepList
  default:
    - script: echo step one
    - script: echo step two

trigger: none

jobs: 
- job: stepList
  steps: ${{ parameters.mySteplist }}
- job: myStep
  steps:
    - ${{ parameters.myStep }}