範本參數
您可以在範本中指定參數及其資料類型,並在管線中參考這些參數。 使用 templateContext,您也可以將屬性傳遞至範本中做為參數的階段、步驟和作業。
您也可以 在範本外部使用參數。 您只能針對參數預設值使用常值。 深入瞭解 YAML 架構中的參數。
傳遞參數
參數必須包含名稱和數據類型。 在 中 azure-pipelines.yml
,當 參數 yesNo
設定為布爾值時,組建會成功。 當 設定為 之類的apples
字串時yesNo
,組建會失敗。
# 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
將更多屬性傳遞至範本中做為參數的階段、步驟和作業。 具體來說,您可以在、 deploymentList
或 stageList
參數資料類型內jobList
指定 templateContext
。
您可以使用 templateContext
,在處理每個作業時更輕鬆地設定環境。 藉由將作業及其環境屬性對象結合在一起, templateContext
可協助您擁有更容易維護且更容易瞭解 YAML。
在這裡範例中,中的 testing-template.yml
參數testSet
具有 資料類型 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 }}:
- ${{ 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"
要在運行時間選取範本的參數
視條件而定,您可以從管線 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) }}:
- template: experimental.yml
- ${{ if not(eq(parameters.experimentalTemplate, true)) }}:
- template: stable.yml
參數數據類型
步驟、stepList、job、jobList、deployment、deploymentList、stage 和 stageList 數據類型全都使用標準 YAML 架構格式。 此範例包含字串、數位、布爾值、物件、步驟和 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 }}
您可以逐一查看 物件,並列印 物件中的每個字串。
parameters:
- name: listOfStrings
type: object
default:
- one
- two
steps:
- ${{ each value in parameters.listOfStrings }}:
- script: echo ${{ value }}
此外,您可以逐一查看 物件內的巢狀專案。
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 }}
必要參數
您可以在範本開頭新增驗證步驟,以檢查所需的參數。
以下是使用 Bash 檢查 參數的 solution
範例(可讓它在任何平台上運作):
# 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)
幾乎一律會傳回 true
,即使 myparam
參數是 這個字 false
。
非空白字串會在布林值內容中轉換成 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 }}