Parametri del runtime

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 i parametri nei modelli e nella pipeline. I parametri hanno tipi di dati come numero e stringa e possono essere limitati a un subset di valori. La parameters sezione in yaml definisce i parametri disponibili.

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

Nota

Queste linee guida non si applicano alle pipeline classiche. Per i parametri nelle pipeline classiche, vedere Parametri di processo (versione classica).

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 non si imposta default su false, viene utilizzato 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. trigger è impostato su nessuno in modo da poter selezionare il valore di image quando si attiva manualmente l'esecuzione della pipeline.

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

Dalla pagina delle esecuzioni pipeline selezionare Esegui pipeline per eseguire la pipeline. Verrà visualizzata l'opzione per selezionare l'immagine del pool. Se non si effettua una selezione, viene usata l'opzione ubuntu-latest predefinita. Non sarà possibile selezionare un'immagine del pool se si esegue la pipeline dall'editor YAML.

Usare le condizionali con i parametri

È anche possibile usare 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 esegue 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 determinare quale processo avviare. In questo esempio, diverse architetture vengono costruite a seconda del valore del parametro config, che è di tipo string. Per impostazione predefinita, sia l'architettura x86 che l'architettura 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 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

Iterare sui parametri

È possibile iterare attraverso i parametri stringa, numerici e booleani.

Script

In questo esempio si scorrono i parametri e si stampa il nome e il valore per ciascun parametro. Esistono quattro parametri diversi e ognuno rappresenta un tipo diverso. myStringName è una stringa a riga singola. myMultiString è una stringa a più righe. myNumber è un numero. myBoolean è un valore booleano. Nella sezione passaggi le attività di script generano l'output della chiave e del 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

PowerShell

In questo esempio si iterano i parametri e si stampa 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 è un numero. myBoolean è un valore booleano. Nella sezione passaggi si esegue il ciclo dei parametri in un'attività di PowerShell e si imposta 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

Includere in modo dinamico un elenco di passaggi con il parametro stepList

In questo esempio, il stepList tipo di parametro viene usato per includere in modo dinamico un elenco di passaggi nel processo di compilazione.

• La pipeline principale (azure-pipelines.yml) definisce due processi: compilazione e distribuzione.
• Il processo di compilazione usa un modello (build.yml) e passa un elenco di attività di compilazione usando il stepList parametro .
• Il build.yml modello include dinamicamente i passaggi definiti nel build_tasks parametro .

#azure-pipelines.yml

trigger:
- main

jobs:
  - job: build
    displayName: 'Build .NET Core Application'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - checkout: self

      - template: build.yml
        parameters:
          build_tasks:
            - task: DotNetCoreCLI@2
              displayName: 'Restore'
              inputs:
                command: 'restore'
                projects: '**/*.csproj'  

            - task: DotNetCoreCLI@2
              displayName: 'Build'
              inputs:
                command: 'build'
                arguments: '--no-restore'
                projects: '**/*.csproj' 

  - job: deploy
    displayName: 'Pack for Azure App Service deployment'
    dependsOn: build
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - download: current
        artifact: drop

Il build.yml modello:

• Definisce il parametro build_tasks con il tipo stepList e un elenco vuoto predefinito.
• Configura il .NET Core SDK alla versione 6.x.
• Scorre ogni fase del parametro build_tasks.
• Esegue ogni passaggio definito nell'elenco build_tasks .

#build.yml

parameters:
  - name: build_tasks
    type: stepList
    default: []

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '6.x'

  - ${{ each step in parameters.build_tasks }}:
      - ${{ step }}

  - task: DotNetCoreCLI@2
    displayName: 'Publish'
    inputs:
      command: 'publish'
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
      projects: '**/*.csproj'

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Artifact'
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'

Tipi di dati dei parametri

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

I tipi di dati step, 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  # Define a parameter named 'myString'
  type: string  # The parameter type is string
  default: a string  # Default value is 'a string'

- name: myMultiString  # Define a parameter named 'myMultiString'
  type: string  # The parameter type is string
  default: default  # Default value is 'default'
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myNumber  # Define a parameter named 'myNumber'
  type: number  # The parameter type is number
  default: 2  # Default value is 2
  values:  # Allowed values for 'myNumber'
  - 1  
  - 2  
  - 4  
  - 8  
  - 16  

- name: myBoolean  # Define a parameter named 'myBoolean'
  type: boolean  # The parameter type is boolean
  default: true  # Default value is true

- name: myObject  # Define a parameter named 'myObject'
  type: object  # The parameter type is object
  default:  # Default value is an object with nested properties
    foo: FOO  # Property 'foo' with value 'FOO'
    bar: BAR  # Property 'bar' with value 'BAR'
    things:  # Property 'things' is a list
    - one  
    - two  
    - three  
    nested:  # Property 'nested' is an object
      one: apple  # Property 'one' with value 'apple'
      two: pear  # Property 'two' with value 'pear'
      count: 3  # Property 'count' with value 3

- name: myStep  # Define a parameter named 'myStep'
  type: step  # The parameter type is step
  default:  # Default value is a step
    script: echo my step 

- name: mySteplist  # Define a parameter named 'mySteplist'
  type: stepList  # The parameter type is stepList
  default:  # Default value is a list of steps
    - script: echo step one  
    - script: echo step two  

trigger: none  

jobs: 
- job: stepList  # Define a job named 'stepList'
  steps: ${{ parameters.mySteplist }}  # Use the steps from the 'mySteplist' parameter

- job: myStep  # Define a job named 'myStep'
  steps:
    - ${{ parameters.myStep }}  # Use the step from the 'myStep' parameter