Körningsparametrar

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

Med körningsparametrar kan du få mer kontroll över vilka värden som kan skickas till en pipeline. Med körningsparametrar kan du:

• Ange olika värden för skript och uppgifter vid körning
• Kontrollera parametertyper, tillåtna intervall och standardvärden
• Välj jobb och faser dynamiskt med malluttryck

Du kan ange parametrar i mallar och i pipelinen. Parametrar har datatyper som tal och sträng, och de kan begränsas till en delmängd av värden. Avsnittet parameters i en YAML definierar vilka parametrar som är tillgängliga.

Parametrar är endast tillgängliga vid mallparsningstid. Parametrarna expanderas precis innan pipelinen körs så att värden som omges av ${{ }} ersätts med parametervärden. Använd variabler om du behöver dina värden för att vara mer allmänt tillgängliga under pipelinekörningen.

Kommentar

Den här vägledningen gäller inte för klassiska pipelines. Parametrar i klassiska pipelines finns i Processparametrar (klassisk).

Parametrarna måste innehålla ett namn och en datatyp. Parametrar kan inte vara valfria. Ett standardvärde måste tilldelas i YAML-filen eller när du kör pipelinen. Om du inte tilldelar ett standardvärde eller anger default till falseanvänds det första tillgängliga värdet.

Använd templateContext för att skicka extra egenskaper till steg, steg och jobb som används som parametrar i en mall.

Använda parametrar i pipelines

Ange körningsparametrar i början av en YAML.

Den här exempelpipelinen innehåller en image parameter med tre värdbaserade agenter som string alternativ. I avsnittet pool Jobb anger värdet agenten från parametern som används för att köra jobbet. trigger Är inställt på ingen så att du kan välja värdet image för när du manuellt utlöser pipelinen för körning.

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

När pipelinen körs väljer du Poolbild. Om du inte gör något val används standardalternativet ubuntu-latest .

Använda villkor med parametrar

Du kan också använda parametrar som en del av villkorsstyrd logik. Med villkor körs en del av en YAML om den if uppfyller kriterierna.

Använda parametrar för att avgöra vilka steg som körs

Den här pipelinen lägger till en andra boolesk parameter, test, som kan användas för att styra om tester ska köras i pipelinen eller inte. När värdet test för är sant körs det steg som matar ut Att köra alla tester .

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"

Använd parametrar för att ange vilken konfiguration som används

Du kan också använda parametrar för att ange vilket jobb som ska köras. I det här exemplet bygger olika arkitekturer beroende på värdet för config parametern, som är en string typ. Som standard byggs både arkitekturerna x86 och x64 .

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

Selektivt exkludera ett stadium

Du kan också använda parametrar för att ange om en fas körs. I det här exemplet finns det en pipeline med fyra steg och olika jobb för varje steg. Fasen Prestandatest körs om parametern runPerfTests är sann. Standardvärdet runPerfTests för är falskt, så utan uppdateringar körs bara tre av de fyra stegen.

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

Loopa igenom parametrar

Du kan också loopa igenom dina sträng-, nummer- och booleska parametrar.

Skript

I det här exemplet loopar du igenom parametrar och skriver ut namnet och värdet för varje parameter. Det finns fyra olika parametrar och var och en representerar en annan typ. myStringName är en enradssträng. myMultiString är en sträng med flera rader. myNumber är ett tal. myBoolean är ett booleskt värde. I stegavsnittet matar skriptuppgifterna ut nyckeln och värdet för varje parameter.

# 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

I det här exemplet loopar du igenom parametrar och skriver ut namnet och värdet för varje parameter. Det finns fyra olika parametrar och var och en representerar en annan typ. myStringName är en enradssträng. myMultiString är en sträng med flera rader. myNumber är ett tal. myBoolean är ett booleskt värde. I stegavsnittet loopar du igenom parametrar i en PowerShell-uppgift och anger varje parameter som en miljövariabel.

# 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

Sök efter ett tomt parameterobjekt

Du kan använda length() uttrycket för att kontrollera om en objektparameter inte har något värde.

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

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

Inkludera en lista med steg dynamiskt med parametern stepList

I det här exemplet stepList används parametertypen för att dynamiskt inkludera en lista med steg i byggprocessen.

• Huvudpipelinen (azure-pipelines.yml) definierar två jobb: skapa och distribuera.
• Byggjobbet använder en mall (build.yml) och skickar en lista över bygguppgifter med hjälp av parametern stepList .
• Mallen build.yml innehåller dynamiskt de steg som definierats i parametern build_tasks .

#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

Mallen build.yml :

• Definierar parametern build_tasks med stepList-typen och en tom standardlista.
• Anger .NET Core SDK till 6.x.
• Itererar över varje steg i parametern build_tasks .
• Kör varje steg som definierats i build_tasks listan.

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

Parameterdatatyper

Datatyp	Kommentar
string	sträng
number	kan begränsas till values:, annars accepteras en talliknande sträng
boolean	true eller false
object	någon YAML-struktur
step	ett enda steg
stepList	sekvens med steg
job	ett enda jobb
jobList	sekvens med jobb
deployment	ett enda distributionsjobb
deploymentList	sekvens med distributionsjobb
stage	en enda fas
stageList	sekvens av faser

Datatyperna step, stepList, job, jobList, deployment, deploymentList, stage och stageList använder alla yaml-standardschemaformat. I det här exemplet ingår sträng, tal, booleskt värde, objekt, steg och 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