Параметры шаблона
Параметры и их типы данных можно указать в шаблоне и ссылаться на эти параметры в конвейере. С помощью templateContext можно также передать свойства этапам, шагам и заданиям, которые используются в качестве параметров в шаблоне.
Кроме того , можно использовать параметры за пределами шаблонов. Можно использовать только литералы для значений по умолчанию параметров. Дополнительные сведения о параметрах схемы YAML.
Передача параметров
Параметры должны содержать имя и тип данных. В azure-pipelines.yml
случае, если параметр yesNo
имеет логическое значение, сборка завершается успешно. Если yesNo
задано значение строки, например apples
, сборка завершается ошибкой.
# 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 для передачи свойств шаблонам
Можно использовать templateContext
для передачи дополнительных свойств этапам, шагам и заданиям, которые используются в качестве параметров в шаблоне. В частности, можно указать templateContext
в типе deploymentList
jobList
данных параметра или stageList
параметре.
Вы можете использовать templateContext
, чтобы упростить настройку сред при обработке каждого задания. Объединяя задание и объект свойств среды вместе, templateContext
вы можете повысить удобство обслуживания и упростить понимание YAML.
В этом примере параметр testSet
имеет testing-template.yml
тип jobList
данных. testing-template.yml
Шаблон создает новую переменную testJob
с помощью каждого ключевого слова. Затем шаблон ссылается на testJob.templateContext.expectedHTTPResponseCode
объект, который получает набор azure-pipeline.yml
и передается в шаблон.
Если код ответа равен 200, шаблон выполняет запрос REST. Если код ответа равен 500, шаблон выводит все переменные среды для отладки.
templateContext
может содержать свойства.
#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"
Параметры для выбора шаблона во время выполнения
Можно вызывать разные шаблоны из YAML конвейера в зависимости от условия. В этом примере experimental.yml
YAML запускается, когда параметр experimentalTemplate
имеет значение 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
Типы данных параметров
Тип данных | Примечания. |
---|---|
string |
строка |
number |
может быть ограничено, в противном случае принимается любая строка, похожая на values: число |
boolean |
true или false |
object |
любая структура YAML |
step |
один шаг |
stepList |
последовательность шагов |
job |
одно задание |
jobList |
последовательность заданий |
deployment |
одно задание развертывания |
deploymentList |
последовательность заданий развертывания |
stage |
один этап |
stageList |
последовательность этапов |
Шаг, stepList, job, jobList, deployment, deploymentList, stage и stageList все типы данных используют стандартный формат схемы YAML. Этот пример включает строку, число, логическое значение, объект, шаг и 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
Вы можете выполнить итерацию по объекту и распечатать каждую строку в объекте.
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
Кроме того, можно итерировать вложенные элементы в объекте.
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
Вы также можете напрямую ссылаться на ключи объекта и соответствующие значения.
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'
Обязательные параметры
Вы можете добавить шаг проверки в начале шаблона, чтобы проверить необходимые параметры.
Ниже приведен пример проверки параметра 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 }}
Чтобы показать, что шаблон завершается ошибкой, если он отсутствует обязательный параметр:
# 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
Параметры можно передать в шаблоны.
В 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
При использовании шаблона в конвейере укажите значения параметров шаблона.
# 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'
Также можно использовать параметры с шаблонами шагов или этапов. Например, действия с параметрами:
# 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
При использовании шаблона в конвейере укажите значения параметров шаблона.
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
Примечание.
Скалярные параметры всегда рассматриваются как строки.
Например, почти всегда возвращается, eq(parameters['myparam'], true)
даже если myparam
параметр является словомfalse
.true
Непустые строки привязываются к true
логическому контексту.
Это выражение может быть перезаписано для явного сравнения строк: eq(parameters['myparam'], 'true')
Параметры не ограничиваются скалярными строками. Если место, в котором параметр расширяется, ожидает сопоставление, параметр может быть сопоставлением. Аналогичным образом последовательности можно передавать, где ожидаются последовательности. Например:
# 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 }}