Laufzeitparameter

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

Laufzeitparameter bieten Ihnen mehr Kontrolle über die Werte, die Sie an eine Pipeline übergeben. Mit Laufzeitparametern können Sie:

• Unterschiedliche Werte für Skripts und Aufgaben zur Laufzeit bereitstellen
• Steuerelementparametertypen, zulässige Bereiche und Standardwerte
• 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 während der Vorlagenanalyse verfügbar. Sie werden erweitert, bevor die Pipeline ausgeführt wird, und ersetzen Werte, die von ${{ }} umgeben waren, durch Parameterwerte. Verwenden Sie Variablen , wenn Ihre Werte während der gesamten Pipelineausführung verfügbar sein müssen.

Parameter müssen einen Namen und einen Datentyp enthalten. Sie können parameter nicht optional festlegen. Sie müssen ihrer YAML-Datei oder beim Ausführen der Pipeline einen Standardwert zuweisen. Wenn Sie keinen Standardwert zuweisen oder auf defaultfestlegenfalse, wird der erste verfügbare Wert verwendet.

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

Was ist der Unterschied zwischen Parametern und Variablen?

In der folgenden Tabelle werden die wichtigsten Unterschiede zwischen Parametern und Variablen in Azure-Pipelines hervorgehoben.

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 können kein Poolimage auswä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 hinzu, der steuert, testob Tests in der Pipeline ausgeführt werden sollen. 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 ist runPerfTests "false", sodass nur drei der vier Phasen ausgeführt werden, es sei denn, Sie aktualisieren den Wert.

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

Nach einem leeren Parameterobjekt suchen

Verwenden Sie den length()Ausdruck , um zu überprüfen, ob ein Objektparameter keinen Wert aufweist.

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

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

Parameterdatentypen

Alle step, stepList, job, jobList, deployment, deploymentList, stage, stringList und stageList Datentypen verwenden das standardmäßige YAML-Schemaformat. Dieses Beispiel enthält string, , number, boolean, object, stepund 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', only one default
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myStringlist # Define a parameter named 'myStringlist'
  type: stringList # The parameter type is stringList
  displayName: Regions
  values: # Allowed values for 'myStringlist'
    - WUS
    - CUS
    - EUS
  default: # Default values
    - WUS
    - CUS
    
- 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

- job: stringList  # Define a job named 'stringList'
  steps:
  - ${{ each region in parameters.myStringlist }}:
      - script: echo ${{region}}

Bewährte Methoden zur Parametersicherheit

Wenn Sie Laufzeitparameter in Azure Pipelines verwenden, übergeben Sie geheime oder vertrauliche Werte nicht als Parametereingaben. Parameterwerte werden während der Vorlagenanalyse erweitert und könnten in Pipelineprotokollen oder Ausgaben sichtbar werden.

Überprüfen und einschränken Sie immer zulässige Parameterwerte, um die Einfügung unerwarteter oder unsicherer Eingaben zu verhindern. Befolgen Sie das Prinzip der geringsten Berechtigungen, wenn Sie Zugriff auf Pipelineressourcen gewähren.

Verwenden Sie für Anmeldeinformationen, Token oder andere vertrauliche Daten Pipelinevariablen, die als geheime Schlüssel gekennzeichnet sind und in Azure Key Vault, der Pipeline-Benutzeroberfläche oder variablen Gruppen gespeichert sind. Weitere Einzelheiten finden Sie unter Geheimnisse in Azure Pipelines schützen.