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
Sie können Parameter an Vorlagen übergeben.
Im Abschnitt parameters
wird definiert, welche Parameter in der Vorlage verfügbar sind und wie ihre Standardwerte lauten.
Vorlagen werden direkt vor dem Ausführen der Pipeline erweitert, sodass in ${{ }}
eingeschlossene Werte durch die von der umschließenden Pipeline empfangenen Parameter ersetzt werden. Daher können nur vordefinierte Variablen in Parametern verwendet werden.
Informationen zum Verwenden von Parametern für mehrere Pipelines finden Sie in den Anweisungen zum Erstellen einer Variablengruppe.
Auftrags-, Stage- und Schrittvorlagen mit Parametern
# File: templates/npm-with-params.yml
parameters:
name: '' # defaults for any parameters that aren't specified
vmImage: ''
jobs:
- job: ${{ parameters.name }}
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: npm install
- script: npm test
Wenn Sie die Vorlage in Ihrer Pipeline nutzen, geben Sie Werte für die Vorlagenparameter an.
# File: azure-pipelines.yml
jobs:
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Linux
vmImage: 'ubuntu-latest'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: macOS
vmImage: 'macOS-10.13'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Windows
vmImage: 'windows-latest'
Sie können auch Parameter mit Schritt- oder Stagevorlagen verwenden. Beispiel für Schritte mit Parametern:
# File: templates/steps-with-params.yml
parameters:
runExtendedTests: 'false' # defaults for any parameters that aren't specified
steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, 'true') }}:
- script: npm test --extended
Wenn Sie die Vorlage in Ihrer Pipeline nutzen, geben Sie Werte für die Vorlagenparameter an.
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
Hinweis
Skalare Parameter werden immer als Zeichenfolgen behandelt.
Beispielsweise gibt eq(parameters['myparam'], true)
fast immer true
zurück, auch wenn der Parameter myparam
das Wort false
ist.
Nicht leere Zeichenfolgen werden in einen booleschen Kontext in true
umgewandelt.
Dieser Ausdruck kann umgeschrieben werden, um Zeichenfolgen explizit zu vergleichen: eq(parameters['myparam'], 'true')
.
Parameter sind nicht auf skalare Zeichenfolgen beschränkt. Solange für die Stelle, an der der Parameter erweitert wird, ein Mapping erwartet wird, kann der Parameter ein Mapping sein. Ebenso können Sequenzen an Stellen übergeben werden, an denen Sequenzen erwartet werden. Beispiel:
# azure-pipelines.yml
jobs:
- template: process.yml
parameters:
pool: # this parameter is called `pool`
vmImage: ubuntu-latest # and it's a mapping rather than a string
# process.yml
parameters:
pool: {}
jobs:
- job: build
pool: ${{ parameters.pool }}