Parâmetros do modelo

Você pode especificar parâmetros e seus tipos de dados em um modelo e fazer referência a esses parâmetros em um pipeline. Com templateContext, você também pode passar propriedades para estágios, etapas e trabalhos que são usados como parâmetros em um modelo.

Você também pode usar parâmetros fora dos modelos. Você só pode usar literais para valores padrão de parâmetro. Saiba mais sobre parâmetros no esquema YAML.

Parâmetros de passagem

Os parâmetros devem incluir um nome e um tipo de dados. Em azure-pipelines.yml, se o parâmetro yesNo for definido como um valor booleano, a compilação será bem-sucedida. Se yesNo estiver definido como uma cadeia de caracteres como apples, a compilação falhará.

# 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

Use o contexto de modelos para passar propriedades para templates

Você pode usar templateContext para passar mais propriedades para estágios, etapas e trabalhos que são usados como parâmetros em um modelo. Especificamente, você pode especificar templateContext dentro do tipo de dados jobList, deploymentList ou stageList.

templateContext facilita a configuração de ambientes ao processar cada trabalho. Ao agrupar um trabalho e seu objeto de propriedades de ambiente juntos, templateContext ajuda a criar um YAML mais fácil de manter e mais fácil de entender.

Neste exemplo, o parâmetro testSet in testing-template.yml tem o tipo jobListde dados . O modelo testing-template.yml cria uma nova variável testJob usando cada palavra-chave. Em seguida, o template faz referência ao testJob.templateContext.expectedHTTPResponseCode, que é definido em azure-pipeline.yml e passado para o template.

Quando o código de resposta é 200, o modelo faz uma solicitação REST. Quando o código de resposta é 500, o modelo gera todas as variáveis de ambiente para depuração.

templateContext pode conter propriedades.

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

Parâmetros para selecionar um modelo em tempo de execução

Você pode invocar modelos diferentes de um pipeline YAML dependendo de uma condição. Neste exemplo, o experimental.yml YAML é executado quando o parâmetro 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

Tipos de dados de parâmetros

Os steptipos de dados , stepList, job, jobList, deploymentdeploymentList, stage, stringList, e stageList usam o formato de esquema YAML padrão. Este exemplo inclui string, number, boolean, object, stepe 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}}

Iterando sobre parâmetros e os seus tipos de dados

O Azure Pipelines permite iterar através de parâmetros de vários tipos de dados, como cadeias de caracteres, objetos, números e booleanos. Essa flexibilidade permite o comportamento dinâmico do pipeline com base em valores de parâmetros. Abaixo estão exemplos que demonstram como iterar através de parâmetros e lidar com diferentes tipos de dados.

Iteração através de parâmetros simples

Você pode fazer loop através de parâmetros simples, como strings, números e booleanos. Neste exemplo, o pipeline itera através de uma lista de parâmetros e imprime seus nomes e valores.

# 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

Iteração através de objetos

Os objetos permitem definir estruturas de parâmetros complexas, como elementos aninhados. Você pode iterar através de objetos para acessar suas chaves e valores ou propriedades aninhadas.

Exemplo: iteração através de chaves e valores de objeto

O arquivo de modelo a seguir define o myObject parâmetro como um objeto com pares chave-valor padrão. O trabalho itera através das chaves e imprime seus valores.

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

O pipeline substitui os valores padrão de myObject com valores personalizados.

# azure-pipelines.yml

trigger:
- main

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

Exemplo: iteração através de objetos aninhados

O modelo define um listOfFruits parâmetro contendo objetos com matrizes aninhadas e, em seguida, usa loops aninhados para processar cada fruto e suas cores associadas.

# 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

O arquivo de pipeline mostra como substituir os valores padrão por dados de frutas personalizados.

# File: azure-pipelines.yml

trigger:
- main

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

Inclua dinamicamente uma lista de etapas com o parâmetro stepList

Neste exemplo, o stepList tipo de parâmetro é usado para incluir dinamicamente uma lista de etapas no processo de compilação.

• O pipeline principal (azure-pipelines.yml) define dois trabalhos: construção e implementação.
• O trabalho de compilação usa um modelo (build.yml) e passa uma lista de tarefas de compilação usando o stepList parâmetro.
• O build.yml modelo inclui dinamicamente as etapas definidas no build_tasks parâmetro.

#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

O modelo build.yml:

• Define o parâmetro build_tasks com o tipo stepList e uma lista vazia padrão.
• Define o SDK do .NET Core como 8.x.
• Itera por cada etapa do parâmetro build_tasks.
• Executa cada etapa definida na build_tasks lista.

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