Parameter template

Anda dapat menentukan parameter dan jenis datanya dalam templat dan mereferensikan parameter tersebut dalam alur. Dengan templateContext, Anda juga dapat meneruskan properti ke tahapan, langkah, dan pekerjaan yang digunakan sebagai parameter dalam templat.

Anda juga dapat menggunakan parameter di luar templat. Anda hanya dapat menggunakan literal untuk nilai default parameter. Pelajari selengkapnya tentang parameter dalam skema YAML.

Parameter Passing

Parameter harus berisi nama dan jenis data. Dalam azure-pipelines.yml, ketika parameter yesNo diatur ke nilai boolean, build berhasil. Ketika yesNo diatur ke string seperti apples, build gagal.

# 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

Menggunakan templateContext untuk meneruskan properti ke templat

Anda dapat menggunakan templateContext untuk meneruskan lebih banyak properti ke tahapan, langkah, dan pekerjaan yang digunakan sebagai parameter dalam templat. Secara khusus, Anda dapat menentukan templateContext dalam jobListjenis data parameter , , deploymentListatau stageList .

Anda dapat menggunakan templateContext untuk mempermudah penyiapan lingkungan saat memproses setiap pekerjaan. Dengan menggabungkan pekerjaan dan objek properti lingkungannya bersama-sama, templateContext dapat membantu Anda memiliki YAML yang lebih mudah dirawat dan lebih mudah dipahami.

Dalam contoh ini, parameter testSet di testing-template.yml memiliki jenis jobListdata . Templat testing-template.yml membuat variabel testJob baru menggunakan setiap kata kunci. Templat kemudian mereferensikan testJob.templateContext.expectedHTTPResponseCode, yang akan diatur dan diteruskan azure-pipeline.yml ke templat.

Saat kode respons adalah 200, templat membuat permintaan REST. Ketika kode respons adalah 500, templat menghasilkan semua variabel lingkungan untuk penelusuran kesalahan.

templateContext dapat berisi properti.

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

Parameter untuk memilih templat saat runtime

Anda dapat memanggil templat yang berbeda dari YAML alur tergantung pada kondisi. Dalam contoh ini, experimental.yml YAML berjalan ketika parameter experimentalTemplate benar.

#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

Jenis data parameter

Jenis Data	Catatan
string	string
number	dapat dibatasi untuk values:, jika tidak, string seperti angka apa pun diterima
boolean	true atau false
object	struktur YAML apa pun
step	satu langkah
stepList	urutan langkah-langkah
job	satu pekerjaan
jobList	urutan pekerjaan
deployment	satu pekerjaan penyebaran
deploymentList	urutan pekerjaan penyebaran
stage	satu tahap
stageList	urutan tahapan

Langkah, stepList, pekerjaan, jobList, penyebaran, deploymentList, tahap, dan jenis data stageList semuanya menggunakan format skema YAML standar. Contoh ini mencakup string, angka, boolean, objek, langkah, dan 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

Anda dapat melakukan iterasi melalui objek dan mencetak setiap string dalam objek.

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

Selain itu, Anda dapat melakukan iterasi melalui elemen berlapis dalam objek.

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

Anda juga dapat langsung mereferensikan kunci objek dan nilai yang sesuai.

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'

Parameter yang diperlukan

Anda dapat menambahkan langkah validasi di awal templat Anda untuk memeriksa parameter yang Anda butuhkan.

Berikut adalah contoh yang memeriksa solution parameter menggunakan 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 }}

Untuk menunjukkan bahwa templat gagal jika tidak memiliki parameter yang diperlukan:

# 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