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 conter um nome e um tipo de dados. No azure-pipelines.yml, quando o parâmetro yesNo é definido como um valor booleano, a compilação é bem-sucedida. Quando yesNo é definido como uma cadeia de caracteres como apples, a compilação falha.

# 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 templateContext para passar propriedades para modelos

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 jobListtipo de dados , deploymentListou stageList parâmetro.

Você pode usar templateContext para facilitar a configuração de ambientes ao processar cada trabalho. Ao agrupar um trabalho e seu objeto de propriedades de ambiente juntos, templateContext pode ajudá-lo a ter 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 modelo faz referência ao testJob.templateContext.expectedHTTPResponseCode, que é definido azure-pipeline.yml e passado para o modelo.

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 chamar 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 tipos de dados step, stepList, job, jobList, deployment, deploymentList, stage e stageList usam o formato de esquema YAML padrão. Este exemplo inclui string, number, boolean, object, step e 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

Você pode iterar através de um objeto e imprimir cada cadeia de caracteres no objeto.

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

Além disso, você pode iterar através de elementos aninhados dentro de um objeto.

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

Você também pode fazer referência direta às chaves de um objeto e aos valores correspondentes.

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'

Parâmetros obrigatórios

Você pode adicionar uma etapa de validação no início do modelo para verificar os parâmetros necessários.

Aqui está um exemplo que verifica o solution parâmetro usando 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 }}

Para mostrar que o modelo falha se estiver faltando o parâmetro necessário:

# 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

Você pode passar parâmetros para modelos. A parameters seção define quais parâmetros estão disponíveis no modelo e seus valores padrão. Os modelos são expandidos imediatamente antes da execução do pipeline para que os valores cercados por ${{ }} sejam substituídos pelos parâmetros que ele recebe do pipeline de delimitação. Como resultado, apenas variáveis predefinidas podem ser usadas em parâmetros.

Para usar parâmetros em vários pipelines, veja como criar um grupo de variáveis.

Modelos de trabalho, estágio e etapa com parâmetros

# 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

Ao consumir o modelo em seu pipeline, especifique valores para os parâmetros do modelo.

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

Você também pode usar parâmetros com modelos de etapa ou estágio. Por exemplo, etapas com parâmetros:

# 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

Ao consumir o modelo em seu pipeline, especifique valores para os parâmetros do modelo.

# File: azure-pipelines.yml

steps:
- script: npm install

- template: templates/steps-with-params.yml  # Template reference
  parameters:
    runExtendedTests: 'true'

Os parâmetros não estão limitados a cadeias escalares. Desde que o local onde o parâmetro se expande espere um mapeamento, o parâmetro pode ser um mapeamento. Da mesma forma, as sequências podem ser passadas onde as sequências são esperadas. Por exemplo:

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