Vorlagenparameter

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 yesNo in azure-pipelines.yml 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 in den Parameterdatentypen jobList, deploymentList oder stageList auch templateContext 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 }}:
  - ${{ if eq(testJob.templateContext.expectedHTTPResponseCode, 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) }}:
    - job:
      steps:
      - powershell: 'Get-ChildItem -Path Env:\'
      - ${{ testJob.steps }}

#azure-pipeline.yml

trigger: none

pool:
  vmImage: ubuntu-latest

extends:
  template: testing-template.yml
  parameters:
    testSet:
    - job: positive_test
      templateContext:
        expectedHTTPResponseCode: 200
      steps:
      - script: echo "Run positive test" 
    - job: negative_test
      templateContext:
        expectedHTTPResponseCode: 500
      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) }}:
  - template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:
  - template: stable.yml

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
  type: string
  default: a string
- 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
- name: myObject
  type: object
  default:
    foo: FOO
    bar: BAR
    things:
    - one
    - two
    - three
    nested:
      one: apple
      two: pear
      count: 3
- name: myStep
  type: step
  default:
    script: echo my step
- name: mySteplist
  type: stepList
  default:
    - script: echo step one
    - script: echo step two

trigger: none

jobs: 
- job: stepList
  steps: ${{ parameters.mySteplist }}
- job: myStep
  steps:
    - ${{ parameters.myStep }}

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 }}:
  - script: echo ${{ value }}

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 }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Erforderliche Parameter

Sie können am Anfang Ihrer Vorlage einen Validierungsschritt hinzufügen, um nach den benötigten Parametern zu suchen.

Hier sehen Sie ein Beispiel, das mithilfe von Bash auf den Parameter solution überprüft (mit dem es auf jeder Plattform funktioniert):

# 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: msbuild@1
  inputs:
    solution: ${{ parameters.solution }}
- task: vstest@2
  inputs:
    solution: ${{ parameters.solution }}

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

# 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