Runtimeparameters

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

Met runtimeparameters hebt u meer controle over welke waarden aan een pijplijn kunnen worden doorgegeven. Met runtimeparameters kunt u het volgende doen:

• Verschillende waarden opgeven voor scripts en taken tijdens runtime
• Parametertypen, toegestane bereiken en standaardinstellingen voor besturingsparameters
• Taken en fasen dynamisch selecteren met sjabloonexpressies

U kunt parameters opgeven in sjablonen en in de pijplijn. Parameters hebben gegevenstypen, zoals getal en tekenreeks, en ze kunnen worden beperkt tot een subset van waarden. In parameters de sectie in een YAML wordt gedefinieerd welke parameters beschikbaar zijn.

Parameters zijn alleen beschikbaar tijdens het parseren van sjablonen. Parameters worden vlak voordat de pijplijn wordt uitgevoerd uitgevouwen, zodat waarden die worden omgeven ${{ }} door parameterwaarden worden vervangen. Gebruik variabelen als u wilt dat uw waarden breder beschikbaar zijn tijdens de pijplijnuitvoering.

Notitie

Deze richtlijnen zijn niet van toepassing op klassieke pijplijnen. Zie Procesparameters (klassiek) voor parameters in klassieke pijplijnen.

Parameters moeten een naam en gegevenstype bevatten. Parameters kunnen niet optioneel zijn. Er moet een standaardwaarde worden toegewezen aan uw YAML-bestand of wanneer u de pijplijn uitvoert. Als u geen standaardwaarde toewijst of instelt default op false, wordt de eerste beschikbare waarde gebruikt.

Gebruik templateContext om extra eigenschappen door te geven aan fasen, stappen en taken die worden gebruikt als parameters in een sjabloon.

Parameters gebruiken in pijplijnen

Runtimeparameters instellen aan het begin van een YAML.

Deze voorbeeldpijplijn bevat een image parameter met drie gehoste agents als string opties. In de sectie Taken geeft de pool waarde de agent op van de parameter die wordt gebruikt om de taak uit te voeren. De trigger waarde is ingesteld op geen, zodat u de waarde kunt selecteren van image wanneer u de pijplijn handmatig activeert om uit te voeren.

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

Wanneer de pijplijn wordt uitgevoerd, selecteert u de poolinstallatiekopieën. Als u geen selectie maakt, wordt de standaardoptie ubuntu-latest gebruikt.

Voorwaardelijk gebruik met parameters

U kunt ook parameters gebruiken als onderdeel van voorwaardelijke logica. Met voorwaardelijke voorwaarden wordt een deel van een YAML uitgevoerd als deze voldoet aan de if criteria.

Parameters gebruiken om te bepalen welke stappen worden uitgevoerd

Met deze pijplijn wordt een tweede Booleaanse parameter toegevoegd, testdie kan worden gebruikt om te bepalen of tests in de pijplijn al dan niet moeten worden uitgevoerd. Wanneer de waarde test waar is, wordt de stap uitgevoerd waarop alle tests worden uitgevoerd.

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"

Parameters gebruiken om in te stellen welke configuratie wordt gebruikt

U kunt ook parameters gebruiken om in te stellen welke taak wordt uitgevoerd. In dit voorbeeld bouwen verschillende architecturen, afhankelijk van de waarde van config de parameter, een string type. Standaard bouwen zowel de architectuur als x64 de x86 architectuur.

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

Selectief een fase uitsluiten

U kunt ook parameters gebruiken om in te stellen of een fase wordt uitgevoerd. In dit voorbeeld is er een pijplijn met vier fasen en verschillende taken voor elke fase. De fase Prestatietest wordt uitgevoerd als de parameter runPerfTests waar is. De standaardwaarde is runPerfTests onwaar, dus zonder updates worden slechts drie van de vier fasen uitgevoerd.

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

Parameters doorlopen

U kunt ook de parameters tekenreeks, getal en Booleaanse waarde doorlopen.

Script

In dit voorbeeld doorloopt u parameters en drukt u de naam en waarde van elke parameter af. Er zijn vier verschillende parameters en elk vertegenwoordigt een ander type. myStringName is een tekenreeks met één regel. myMultiString is een tekenreeks met meerdere regels. myNumber is een getal. myBoolean is een Booleaanse waarde. In de stappensectie voeren de scripttaken de sleutel en waarde van elke parameter uit.

# 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 dit voorbeeld doorloopt u parameters en drukt u de naam en waarde van elke parameter af. Er zijn vier verschillende parameters en elk vertegenwoordigt een ander type. myStringName is een tekenreeks met één regel. myMultiString is een tekenreeks met meerdere regels. myNumber is een getal. myBoolean is een Booleaanse waarde. In de sectie Stappen doorloopt u parameters in een PowerShell-taak en stelt u elke parameter in als een omgevingsvariabele.

# 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

Controleren op een leeg parameterobject

U kunt de length() expressie gebruiken om te controleren of een objectparameter geen waarde heeft.

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

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

Dynamisch een lijst met stappen opnemen met de parameter StepList

In dit voorbeeld wordt het stepList parametertype gebruikt om dynamisch een lijst met stappen in het buildproces op te nemen.

• De hoofdpijplijn (azure-pipelines.yml) definieert twee taken: bouwen en implementeren.
• De buildtaak maakt gebruik van een sjabloon (build.yml) en geeft een lijst met buildtaken door met behulp van de stepList parameter.
• De build.yml sjabloon bevat dynamisch de stappen die in de build_tasks parameter zijn gedefinieerd.

#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

De build.yml sjabloon:

• Hiermee definieert u de parameter build_tasks met het type stepList en een standaard lege lijst.
• Stelt de .NET Core SDK in op 6.x.
• Herhaalt elke stap in de build_tasks parameter.
• Hiermee wordt elke stap uitgevoerd die in de build_tasks lijst is gedefinieerd.

#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'

Parametergegevenstypen

Gegevenstype	Opmerkingen
string	tekenreeks
number	kan worden beperkt tot values:, anders wordt een willekeurige tekenreeks geaccepteerd die lijkt op een getal
boolean	true of false
object	elke YAML-structuur
step	één stap
stepList	reeks stappen
job	één taak
jobList	reeks taken
deployment	één implementatietaak
deploymentList	volgorde van implementatietaken
stage	één fase
stageList	reeks fasen

De stap, stepList, job, jobList, deployment, deploymentList, stage en stageList-gegevenstypen maken allemaal gebruik van de standaard YAML-schema-indeling. Dit voorbeeld bevat tekenreeks, getal, booleaanse waarde, object, stap en 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