Vorlagenparameter

2025-06-10

Sie können Parameter und deren Datentypen in einer Vorlage angeben und in einer Pipeline auf diese Parameter verweisen. Verwenden Sie templateContext, um zusätzliche Eigenschaften an Stages, Schritte und Aufträge zu übergeben, die als Parameter in einer Vorlage verwendet werden.

Sie können Parameter auch außerhalb von Vorlagen verwenden. Für Parameterstandardwerte können Sie nur Literale verwenden. Weitere Informationen zu Parametern im YAML-Schema.

Übergeben von Parametern

Parameter müssen einen Namen und einen Datentyp enthalten. Wenn der Parameter azure-pipelines.yml in yesNo auf einen booleschen Wert festgelegt ist, läuft der Buildvorgang erfolgreich ab. Wenn yesNo auf eine Zeichenfolge wie apples festgelegt ist, tritt beim Build ein Fehler auf.

# File: simple-param.yml
parameters:
- name: yesNo # name of the parameter; required
  type: boolean # data type of the parameter; required
  default: false

steps:
- script: echo ${{ parameters.yesNo }}

# File: azure-pipelines.yml
trigger:
- main

extends:
  template: simple-param.yml
  parameters:
      yesNo: false # set to a non-boolean value to have the build fail

Verwenden von templateContext zum Übergeben von Eigenschaften an Vorlagen

Sie können mit templateContext weitere Eigenschaften an Stages, Schritte und Aufträge übergeben, die als Parameter in einer Vorlage verwendet werden. Insbesondere können Sie templateContext innerhalb der Parameterdatentypen jobList, deploymentList oder stageList angeben.

Sie können mit templateContext das Einrichten von Umgebungen bei der Verarbeitung der einzelnen Aufträge vereinfachen. Durch das Bündeln eines Auftrags mit dessen Umgebungseigenschaftenobjekt können Sie mithilfe von templateContext YAML besser verwaltbar und einfacher verständlich gestalten.

In diesem Beispiel weist der Parameter testSet in testing-template.yml den Datentyp jobList auf. Die Vorlage testing-template.yml erstellt eine neue Variable testJob mit dem Schlüsselwort each. Die Vorlage verweist dann auf testJob.templateContext.expectedHTTPResponseCode, das in azure-pipeline.yml festgelegt und an die Vorlage übergeben wird.

Wenn der Antwortcode 200 lautet, stellt die Vorlage eine REST-Anforderung. Beim Antwortcode 500 gibt die Vorlage alle Umgebungsvariablen zum Debuggen aus.

templateContext kann Eigenschaften enthalten.

#testing-template.yml

parameters: 
- name: testSet
  type: jobList

jobs:
- ${{ each testJob in parameters.testSet }}:  # Iterate over each job in the 'testSet' parameter
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 200) }}: # Check if the HTTP response is 200
    - job:
      steps: 
      - powershell: 'Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ | Format-Table -Property Title, pubDate'
      - ${{ testJob.steps }}    
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 500) }}: # Check if the HTTP response is 500
    - job:
      steps:
      - powershell: 'Get-ChildItem -Path Env:\' # Run a PowerShell script to list environment variables
      - ${{ testJob.steps }} # Include additional steps from the 'testJob' object

#azure-pipeline.yml

trigger: none

pool:
  vmImage: ubuntu-latest

extends:
  template: testing-template.yml 
  parameters:
    testSet:  # Define the 'testSet' parameter to pass to the template
    - job: positive_test # Define a job named 'positive_test'
      templateContext:
        expectedHTTPResponseCode: 200 # Set the expected HTTP response code to 200 for this job
      steps:
      - script: echo "Run positive test" 
    - job: negative_test # Define a job named 'negative_test'
      templateContext:
        expectedHTTPResponseCode: 500 # Set the expected HTTP response code to 500 for this job
      steps:
      - script: echo "Run negative test"

Parameter zum Auswählen einer Vorlage zur Laufzeit

Je nach Bedingung können Sie verschiedene Vorlagen aus dem YAML-Code einer Pipeline aufrufen. In diesem Beispiel wird die YAML-Datei experimental.yml ausgeführt, wenn der Parameter experimentalTemplate TRUE ist.

#azure-pipeline.yml
parameters:
- name: experimentalTemplate 
  displayName: 'Use experimental build process?'
  type: boolean
  default: false

steps:
- ${{ if eq(parameters.experimentalTemplate, true) }}: # Check if 'experimentalTemplate' is true
  - template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:  # Check if 'experimentalTemplate' is not true
  - template: stable.yml

Parameterdatentypen

Datentyp	Notizen
`string`	Zeichenfolge
`stringList`	eine Liste von Elementen, mehrere können ausgewählt werden. In Vorlagen nicht verfügbar
`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 Job
`jobList`	Sequenz von Aufträgen
`deployment`	ein einzelner Bereitstellungsauftrag
`deploymentList`	Sequenz von Bereitstellungsaufträgen
`stage`	eine einzelne Stufe
`stageList`	Abfolge von Phasen

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.

Hinweis

Der stringList Datentyp ist in Vorlagen nicht verfügbar. Verwenden Sie stattdessen den object Datentyp in Vorlagen.

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

Sie können ein Objekt durchlaufen und jede Zeichenfolge im Objekt drucken.

parameters:
- name: listOfStrings  
  type: object
  default: 
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}: # Iterate over each value in the 'listOfStrings' parameter
  - script: echo ${{ value }} # Output the current value in the iteration

Darüber hinaus können Sie geschachtelte Elemente innerhalb eines Objekts durchlaufen.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow'] 

steps:
- ${{ each fruit in parameters.listOfFruits }} : # Iterate over each fruit in the 'listOfFruits'
  - ${{ each fruitColor in fruit.colors}} : # Iterate over each color in the current fruit's colors
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }} # Echo the current fruit's name and color

Sie können auch direkt auf die Schlüssel und die entsprechenden Werte eines Objekts verweisen.

parameters:
  - name: myObject
    type: object
    default:
      key1: 'value1'
      key2: 'value2'
      key3: 'value3'

jobs:
- job: ExampleJob
  displayName: 'Example object parameter job'
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: |
      echo "Keys in myObject:"
      echo "Key1: ${{ parameters.myObject.key1 }}"
      echo "Key2: ${{ parameters.myObject.key2 }}"
      echo "Key3: ${{ parameters.myObject.key3 }}"
    displayName: 'Display object keys and values'

Erforderliche Parameter

Pipelines melden automatisch einen Fehler, wenn ein Parameter fehlt. Sie können am Anfang der Vorlage einen Überprüfungsschritt hinzufügen, um nach den erforderlichen Parametern zu suchen und entsprechende Maßnahmen zu ergreifen.

Hier ist ein Beispiel, das mithilfe von Bash nach dem Parameter solution sucht:

# File: steps/msbuild.yml

parameters:
- name: 'solution'
  default: ''
  type: string

steps:
- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi
  env:
    SOLUTION: ${{ parameters.solution }}
  displayName: Check for required parameters
- task: VSBuild@1
  inputs:
    solution: ${{ parameters.solution }}
- task: VSTest@3
  inputs:
    testSelector: 'testAssemblies' 
    testAssemblyVer2: ${{ parameters.solution }} 
    searchFolder: '$(System.DefaultWorkingDirectory)'

So zeigen Sie, dass bei der Vorlage ein Fehler auftritt, wenn der erforderliche Parameter fehlt.

# File: azure-pipelines.yml

# This will fail since it doesn't set the "solution" parameter to anything,
# so the template will use its default of an empty string
steps:
- template: steps/msbuild.yml