テンプレート パラメーター

テンプレートでパラメーターとそのデータ型を指定し、パイプラインでそれらのパラメーターを参照できます。 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、jobList、deploymentList パラメーターのデータ型内で 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 パラメータが true の場合に experimentalTemplate YAML が実行されます。

#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

パラメーターのデータ型

step、stepList、job、jobList、deployment、deploymentList、stage、stringList、stageListのデータ型はすべて、標準の YAML スキーマ形式を使用します。 この例には、 string、 number、 boolean、 object、 step、および 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', only one default
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myStringlist # Define a parameter named 'myStringlist'
  type: stringList # The parameter type is stringList
  displayName: Regions
  values: # Allowed values for 'myStringlist'
    - WUS
    - CUS
    - EUS
  default: # Default values
    - WUS
    - CUS
    
- 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

- job: stringList  # Define a job named 'stringList'
  steps:
  - ${{ each region in parameters.myStringlist }}:
      - script: echo ${{region}}

パラメーターとそのデータ型の反復処理

Azure Pipelines では、文字列、オブジェクト、数値、ブール値など、さまざまなデータ型のパラメーターを反復処理できます。 この柔軟性により、パラメーター値に基づく動的パイプライン動作が可能になります。 パラメーターを反復処理し、さまざまなデータ型を処理する方法を示す例を次に示します。

単純なパラメーターの反復処理

文字列、数値、ブール値などの単純なパラメーターをループ処理できます。 この例では、パイプラインはパラメーターの一覧を反復処理し、その名前と値を出力します。

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- name: myNumber
  type: number
  default: 2
- name: myBoolean
  type: boolean
  default: true

steps: 
- ${{ each parameter in parameters }}:
  - script: echo ${{ parameter.Key }} 
  - script: echo ${{ parameter.Value }}

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

オブジェクトの反復処理

オブジェクトを使用すると、入れ子になった要素などの複雑なパラメーター構造を定義できます。 オブジェクトを反復処理して、キーと値、または入れ子になったプロパティにアクセスできます。

例: オブジェクト キーと値の反復処理

次のテンプレート ファイルでは、 myObject パラメーターを既定のキーと値のペアを持つオブジェクトとして定義します。 ジョブはキーを反復処理し、その値を出力します。

# object-keys-template.yml

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'

パイプラインは、 myObject の既定値をカスタム値でオーバーライドします。

# azure-pipelines.yml

trigger:
- main

extends:
  template: object-keys-template.yml
  parameters:
    myObject:
      key1: 'customValue1'
      key2: 'customValue2'
      key3: 'customValue3'

例: 入れ子になったオブジェクトの反復処理

テンプレートは、入れ子になった配列を持つオブジェクトを含む listOfFruits パラメーターを定義し、入れ子になったループを使用して各フルーツとその関連する色を処理します。

# File: nested-objects-template.yml

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

パイプライン ファイルは、既定値をカスタム フルーツ データでオーバーライドする方法を示しています。

# File: azure-pipelines.yml

trigger:
- main

extends:
  template: nested-objects-template.yml
  parameters:
    listOfFruits:
    - fruitName: 'banana'
      colors: ['yellow']
    - fruitName: 'grape'
      colors: ['purple', 'green']

stepList パラメーターを使用してステップのリストを動的に含める

この例では、ビルド プロセスにステップのリストを動的に含めるために、stepList パラメーター型を使用します。

• メイン パイプライン (azure-pipelines.yml) では、build と deploy という 2 つのジョブを定義します。
• build ジョブではテンプレート (build.yml) を使用し、stepList パラメーターを使用してビルド タスクのリストを渡します。
• build.yml テンプレートには、build_tasks パラメーターで定義されているステップが動的に含められます。

#azure-pipelines.yml

trigger:
- main

jobs:
  - job: build
    displayName: 'Build .NET Core Application'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - checkout: self

      - template: build.yml
        parameters:
          build_tasks:
            - task: DotNetCoreCLI@2
              displayName: 'Restore'
              inputs:
                command: 'restore'
                projects: '**/*.csproj'  

            - task: DotNetCoreCLI@2
              displayName: 'Build'
              inputs:
                command: 'build'
                arguments: '--no-restore'
                projects: '**/*.csproj' 

  - job: deploy
    displayName: 'Pack for Azure App Service deployment'
    dependsOn: build
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - download: current
        artifact: drop

build.yml テンプレート:

• stepList 型と既定の空のリストを使用して、パラメーター build_tasks を定義します。
• .NET Core SDK を 8.x に設定します。
• build_tasks パラメーター内の各ステップを反復処理します。
• build_tasks リストで定義されている各ステップを実行します。

#build.yml

parameters:
  - name: build_tasks
    type: stepList
    default: []

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '8.x'

  - ${{ each step in parameters.build_tasks }}:
      - ${{ step }}

  - task: DotNetCoreCLI@2
    displayName: 'Publish'
    inputs:
      command: 'publish'
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
      projects: '**/*.csproj'

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Artifact'
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'