Laufzeitparameter

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

Laufzeitparameter ermöglichen Ihnen mehr Kontrolle darüber, welche Werte an eine Pipeline übergeben werden können. Mit Laufzeitparametern haben Sie folgende Möglichkeiten:

• Unterschiedliche Werte für Skripts und Aufgaben zur Laufzeit bereitstellen
• Steuern von Parametertypen, zulässigen Bereichen und Standardwerten
• Aufträge und Stages mit Vorlagenausdrücken dynamisch auswählen

Sie können Parameter in Vorlagen und in der Pipeline angeben. Parameter verfügen über Datentypen wie Anzahl und Zeichenfolge, und sie können auf eine Teilmenge von Werten beschränkt werden. Der parameters-Abschnitt in einem YAML definiert, welche Parameter verfügbar sind.

Parameter sind nur zum Zeitpunkt der Vorlagenanalyse verfügbar. Parameter werden unmittelbar vor der Ausführung der Pipeline erweitert, sodass von ${{ }} umgebene Werte durch Parameterwerte ersetzt werden. Verwenden Sie Variablen, wenn Ihre Werte während der Pipelineausführung breiter aufgestellt verfügbar sein sollen.

Hinweis

Diese Anleitung gilt nicht für klassische Pipelines. Informationen zu Parametern in klassischen Pipelines finden Sie unter Prozessparameter (klassisch).

Parameter müssen einen Namen und einen Datentyp enthalten. Parameter können nicht optional sein. Ein Standardwert muss in Ihrer YAML-Datei oder beim Ausführen der Pipeline zugewiesen werden. Wenn Sie keinen Standardwert zuweisen oder auf defaultfestlegenfalse, wird der erste verfügbare Wert verwendet.

Verwenden Sie templateContext, um zusätzliche Eigenschaften an Stages, Schritte und Aufträge zu übergeben, die als Parameter in einer Vorlage verwendet werden.

Parameter in Pipelines verwenden

Legen Sie Laufzeitparameter am Anfang einer YAML-Datei fest.

Diese Beispielpipeline enthält einen image-Parameter mit drei gehosteten Agents als string-Optionen. Im Auftragsbereich gibt der pool-Wert den Agent aus dem Parameter an, der zum Ausführen des Auftrags verwendet wird. trigger ist auf „none“ festgelegt, sodass Sie den Wert von image auswählen können, wenn Sie die Ausführung Ihrer Pipeline manuell auslösen.

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

Wählen Sie auf der Seite "Pipelineausführung" die Option "Pipeline ausführen" aus, um die Pipeline auszuführen. Die Option zum Auswählen des Poolimages wird angezeigt. Wenn Sie keine Auswahl treffen, wird die Standardoption ubuntu-latest verwendet. Sie haben nicht die Möglichkeit, ein Poolimage auszuwählen, wenn Sie Ihre Pipeline aus dem YAML-Editor ausführen.

Bedingungen mit Parametern verwenden

Sie können Parameter auch als Teil der bedingten Logik verwenden. Mit Bedingungen wird ein Teil eine YAML-Datei ausgeführt, wenn er die if-Kriterien erfüllt.

Parameter zum Bestimmen der auszuführenden Schritte verwenden

Diese Pipeline fügt einen zweiten booleschen Parameter test hinzu, mit dessen Hilfe gesteuert werden kann, ob Tests in der Pipeline ausgeführt werden sollen oder nicht. Wenn der Wert von test „true“ ist, wird der Schritt ausgeführt, der Alle Tests ausführen ausgibt.

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"

Parameter zum Festlegen der verwendeten Konfiguration verwenden

Sie können Parameter auch verwenden, um festzulegen, welcher Auftrag ausgeführt wird. In diesem Beispiel werden verschiedene Architekturen abhängig vom Wert des config-Parameters erstellt, der dem string-Typ entspricht. Standardmäßig wird sowohl die x86- als auch die x64-Architektur erstellt.

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

Eine Stage selektiv ausschließen

Sie können Parameter auch verwenden, um festzulegen, ob eine Stage ausgeführt wird. In diesem Beispiel gibt es eine Pipeline mit vier Stages und unterschiedlichen Aufträgen für jede Stage. Die Stage „Leistungstest“ wird ausgeführt, wenn der Parameter runPerfTests „true“ ist. Der Standardwert von runPerfTests ist „false“, sodass ohne Updates nur drei der vier Stages ausgeführt werden.

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

Parameter durchlaufen

Sie können auch ihre Zeichenfolgen-, Zahlen- und booleschen Parameter durchlaufen.

Skript

In diesem Beispiel durchlaufen Sie Parameter und geben den Namen und den Wert der einzelnen Parameter aus. Es gibt vier verschiedene Parameter, die jeweils einen anderen Typ darstellen. myStringName ist eine einzeilige Zeichenfolge. myMultiString ist eine mehrzeilige Zeichenfolge. myNumber is a number. myBoolean ist ein boolescher Wert. Im Bereich „Schritte“ geben die Skriptaufgaben den Schlüssel und den Wert der einzelnen Parameter aus.

# 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 diesem Beispiel durchlaufen Sie Parameter und geben den Namen und den Wert der einzelnen Parameter aus. Es gibt vier verschiedene Parameter, die jeweils einen anderen Typ darstellen. myStringName ist eine einzeilige Zeichenfolge. myMultiString ist eine mehrzeilige Zeichenfolge. myNumber is a number. myBoolean ist ein boolescher Wert. Im Abschnitt „Schritte“ durchlaufen Sie Parameter in einer PowerShell-Aufgabe und legen jeden Parameter als Umgebungsvariable fest.

# 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

Nach einem leeren Parameterobjekt suchen

Sie können den Ausdruck length() verwenden, um zu überprüfen, ob ein Objektparameter über keinen Wert verfügt.

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

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

Eine Liste von Schritten mit dem stepList-Parameter dynamisch einschließen

In diesem Beispiel wird der Parametertyp stepList verwendet, um dynamisch eine Liste der Schritte in den Buildprozess einzuschließen.

• Die Hauptpipeline (azure-pipelines.yml) definiert zwei Aufträge: Erstellen und Bereitstellen.
• Der Buildauftrag verwendet eine Vorlage (build.yml) und übergibt eine Liste von Buildaufgaben mithilfe des Parameters stepList.
• Die Vorlage build.yml schließt die im Parameter build_tasks definierten Schritte dynamisch ein.

#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

Die build.yml-Vorlage:

• Definiert den Parameter build_tasks mit dem stepList-Typ und einer standardmäßigen leeren Liste.
• Legt das .NET Core SDK auf 6.x fest.
• Durchläuft die einzelnen Schritte im Parameter build_tasks.
• Führt jeden in der build_tasks-Liste definierten Schritt aus.

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

Parameterdatentypen

Datentyp	Notizen
string	Zeichenfolge
number	kann auf values: beschränkt sein, andernfalls wird eine beliebige zahlenähnliche Zeichenfolge akzeptiert
boolean	true oder false
object	beliebige YAML-Struktur
step	ein einzelner Schritt
stepList	Sequenz von Schritten
job	ein einzelner Auftrag
jobList	Sequenz von Aufträgen
deployment	ein einzelner Bereitstellungsauftrag
deploymentList	Sequenz von Bereitstellungsaufträgen
stage	eine einzelne Stage
stageList	Sequenz von Stages

Die Datentypen „step“, „stepList“, „jobList“, „deployment“, „deploymentList“, „stage“ und „stageList“ verwenden alle standardmäßige YAML-Schemaformate. Dieses Beispiel umfasst „string“, „number“, „boolean“, „object“, „step“ und „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