Delen via


Sjabloonparameters

U kunt parameters en de bijbehorende gegevenstypen opgeven in een sjabloon en verwijzen naar deze parameters in een pijplijn. Met templateContext kunt u eigenschappen ook doorgeven aan fasen, stappen en taken die worden gebruikt als parameters in een sjabloon.

U kunt ook parameters buiten sjablonen gebruiken. U kunt alleen letterlijke waarden gebruiken voor standaardwaarden voor parameters. Meer informatie over parameters in het YAML-schema.

Parameters doorgeven

Parameters moeten een naam en gegevenstype bevatten. Wanneer azure-pipelines.ymlde parameter yesNo is ingesteld op een Booleaanse waarde, slaagt de build. Wanneer yesNo deze is ingesteld op een tekenreeks zoals apples, mislukt de build.

# 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

TemplateContext gebruiken om eigenschappen door te geven aan sjablonen

U kunt templateContext meer eigenschappen doorgeven aan fasen, stappen en taken die worden gebruikt als parameters in een sjabloon. U kunt met name opgeven templateContext binnen het jobListgegevenstype , deploymentListof stageList parametergegevenstype.

U kunt het eenvoudiger templateContext maken om omgevingen in te stellen bij het verwerken van elke taak. Door een taak en het bijbehorende object met omgevingseigenschappen samen te bundelen, templateContext kunt u beter onderhouden en beter inzicht krijgen in YAML.

In dit voorbeeld heeft de parameter testSet testing-template.yml het gegevenstype jobList. Met de sjabloon testing-template.yml wordt een nieuwe variabele testJob gemaakt met behulp van elk trefwoord. De sjabloon verwijst vervolgens naar de testJob.templateContext.expectedHTTPResponseCode, die wordt ingesteld azure-pipeline.yml en doorgegeven aan de sjabloon.

Wanneer de antwoordcode 200 is, maakt de sjabloon een REST-aanvraag. Wanneer de antwoordcode 500 is, voert de sjabloon alle omgevingsvariabelen uit voor foutopsporing.

templateContext kan eigenschappen bevatten.

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

Parameters voor het selecteren van een sjabloon tijdens runtime

U kunt verschillende sjablonen aanroepen vanuit een YAML-pijplijn, afhankelijk van een voorwaarde. In dit voorbeeld wordt de experimental.yml YAML uitgevoerd wanneer de parameter experimentalTemplate waar is.

#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

Parametergegevenstypen

Gegevenstype Opmerkingen
string tekenreeks
number kan worden beperkt tot values:, anders wordt een willekeurige tekenreeks geaccepteerd die lijkt op een getal
boolean true of false
object elke YAML-structuur
step één stap
stepList reeks stappen
job één taak
jobList reeks taken
deployment één implementatietaak
deploymentList volgorde van implementatietaken
stage één fase
stageList reeks fasen

De stap, stepList, job, jobList, deployment, deploymentList, stage en stageList-gegevenstypen maken allemaal gebruik van de standaard YAML-schema-indeling. Dit voorbeeld bevat tekenreeks, getal, booleaanse waarde, object, stap en 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

U kunt een object herhalen en elke tekenreeks in het object afdrukken.

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

Daarnaast kunt u geneste elementen in een object herhalen.

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

U kunt ook rechtstreeks verwijzen naar de sleutels en bijbehorende waarden van een object.

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'

Vereiste parameters

U kunt aan het begin van de sjabloon een validatiestap toevoegen om te controleren op de parameters die u nodig hebt.

Hier volgt een voorbeeld waarmee wordt gecontroleerd op de solution parameter met behulp van Bash:

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

Als u wilt weergeven dat de sjabloon mislukt als de vereiste parameter ontbreekt:

# 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

U kunt parameters doorgeven aan sjablonen. In parameters de sectie wordt gedefinieerd welke parameters beschikbaar zijn in de sjabloon en de bijbehorende standaardwaarden. Sjablonen worden uitgevouwen vlak voordat de pijplijn wordt uitgevoerd, zodat waarden die worden omgeven ${{ }} door de parameters die worden ontvangen van de omsluitpijplijn worden vervangen. Als gevolg hiervan kunnen alleen vooraf gedefinieerde variabelen worden gebruikt in parameters.

Als u parameters in meerdere pijplijnen wilt gebruiken, raadpleegt u hoe u een variabelegroep maakt.

Taak-, fase- en stapsjablonen met parameters

# 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

Wanneer u de sjabloon in uw pijplijn gebruikt, geeft u waarden op voor de sjabloonparameters.

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

U kunt ook parameters gebruiken met stap- of fasesjablonen. Bijvoorbeeld stappen met parameters:

# 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

Wanneer u de sjabloon in uw pijplijn gebruikt, geeft u waarden op voor de sjabloonparameters.

# File: azure-pipelines.yml

steps:
- script: npm install

- template: templates/steps-with-params.yml  # Template reference
  parameters:
    runExtendedTests: 'true'

Notitie

Scalaire parameters worden altijd behandeld als tekenreeksen. Retourneert bijvoorbeeld eq(parameters['myparam'], true) bijna altijd true, zelfs als de myparam parameter het woord falseis. Niet-lege tekenreeksen worden omgezet true in een Booleaanse context. Deze expressie kan opnieuw worden geschreven om tekenreeksen expliciet te vergelijken: eq(parameters['myparam'], 'true').

Parameters zijn niet beperkt tot scalaire tekenreeksen. Zolang de locatie waar de parameter wordt uitgebreid een toewijzing verwacht, kan de parameter een toewijzing zijn. Op dezelfde manier kunnen reeksen worden doorgegeven waar sequenties worden verwacht. Voorbeeld:

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