Parametry szablonu

Parametry i ich typy danych można określić w szablonie i odwoływać się do tych parametrów w potoku. Za pomocą szablonuContext można również przekazywać właściwości do etapów, kroków i zadań, które są używane jako parametry w szablonie.

Można również użyć parametrów spoza szablonów. Literały można używać tylko dla wartości domyślnych parametrów. Dowiedz się więcej o parametrach w schemacie YAML.

Przekazywanie parametrów

Parametry muszą zawierać nazwę i typ danych. W azure-pipelines.ymlsystemie, gdy parametr yesNo jest ustawiony na wartość logiczną, kompilacja zakończy się powodzeniem. Gdy yesNo parametr jest ustawiony na ciąg, taki jak apples, kompilacja kończy się niepowodzeniem.

# 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

Przekazywanie właściwości do szablonów przy użyciu szablonu TemplateContext

Możesz użyć templateContext polecenia , aby przekazać więcej właściwości do etapów, kroków i zadań, które są używane jako parametry w szablonie. W szczególności można określić templateContext typ jobListdanych , deploymentListlub stageList parametru.

Możesz użyć templateContext polecenia , aby ułatwić konfigurowanie środowisk podczas przetwarzania każdego zadania. Dzięki połączeniu zadania i jego właściwości środowiska można łatwiej templateContext zrozumieć kod YAML.

W tym przykładzie parametr testSet w testing-template.yml pliku ma typ jobListdanych . testing-template.yml Szablon tworzy nową zmienną testJob przy użyciu każdego słowa kluczowego. Następnie szablon odwołuje się testJob.templateContext.expectedHTTPResponseCodedo elementu , który zostanie ustawiony azure-pipeline.yml i przekazany do szablonu.

Gdy kod odpowiedzi to 200, szablon wysyła żądanie REST. Gdy kod odpowiedzi to 500, szablon zwraca wszystkie zmienne środowiskowe na potrzeby debugowania.

templateContext może zawierać właściwości.

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

Parametry wybierania szablonu w czasie wykonywania

W zależności od warunku można wywoływać różne szablony z potoku YAML. W tym przykładzie experimental.yml kod YAML jest uruchamiany, gdy parametr experimentalTemplate ma wartość true.

#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

Typy danych parametrów

Typ danych	Uwagi
string	string
number	może być ograniczony do values:, w przeciwnym razie akceptowany jest dowolny ciąg przypominający liczbę
boolean	true lub false
object	dowolna struktura YAML
step	pojedynczy krok
stepList	sekwencja kroków
job	pojedyncze zadanie
jobList	sekwencja zadań
deployment	pojedyncze zadanie wdrożenia
deploymentList	sekwencja zadań wdrażania
stage	pojedynczy etap
stageList	sekwencja etapów

Wszystkie typy danych stepList, jobList, jobList, deployment, deploymentList, stage i stageList używają standardowego formatu schematu YAML. Ten przykład obejmuje ciąg, liczbę, wartość logiczną, obiekt, krok i listę kroków.

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

Można iterować przez obiekt i drukować każdy ciąg w obiekcie.

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

Ponadto można iterować przez zagnieżdżone elementy w obiekcie.

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

Możesz również bezpośrednio odwoływać się do kluczy obiektu i odpowiadających im wartości.

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'

Parametry wymagane

Możesz dodać krok weryfikacji na początku szablonu, aby sprawdzić wymagane parametry.

Oto przykład, który sprawdza parametr przy użyciu powłoki solution 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 }}

Aby pokazać, że szablon nie powiedzie się, jeśli brakuje wymaganego parametru:

# 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