Parâmetros de runtime

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Os parâmetros de runtime permitem que você tenha mais controle sobre quais valores podem ser passados para um pipeline. Com parâmetros de runtime, você pode:

  • Fornecer valores diferentes para scripts e tarefas em runtime
  • Tipos de parâmetro de controle, intervalos permitidos e padrões
  • Selecionar dinamicamente trabalhos e estágios com expressões de modelo

Você pode especificar parâmetros em modelos e no pipeline. Os parâmetros têm tipos de dados como e string e podem ser restritos a um subconjunto de valores. A seção parameters em um YAML define quais parâmetros estão disponíveis.

Os parâmetros só estão disponíveis no momento da análise do modelo. Os parâmetros são expandidos pouco antes da execução do pipeline para que os valores cercados por ${{ }} sejam substituídos por valores de parâmetro. Use variáveis se precisar que seus valores estejam mais amplamente disponíveis durante a execução de pipeline.

Observação

Essas diretrizes não se aplicam a pipelines clássicos. Para parâmetros em pipelines clássicos, confira Parâmetros de processo (clássico).

Os parâmetros devem conter um nome e um tipo de dados. Os parâmetros não podem ser opcionais. Um valor padrão precisa ser atribuído no arquivo YAML ou quando você executa o pipeline. Se você não atribuir um valor padrão ou definir default como false, o primeiro valor disponível será usado.

Use templateContext para passar propriedades extras para fases, etapas e trabalhos que são usados como parâmetros em um modelo.

Usar parâmetros em pipelines

Defina parâmetros de runtime no início de um YAML.

Esse pipeline de exemplo inclui um parâmetro image com três agentes hospedados como opções string. Na seção trabalhos, o valor pool especifica o agente do parâmetro usado para executar o trabalho. O trigger é definido como nenhum para que você possa selecionar o valor de image ao disparar manualmente o pipeline para execução.

parameters:
- name: image
  displayName: Pool Image
  type: string
  default: ubuntu-latest
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest

trigger: none

jobs:
- job: build
  displayName: build
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber) with ${{ parameters.image }}

Quando o pipeline é executado, você seleciona a Imagem do Pool. Se você não fizer uma seleção, a opção padrão ubuntu-latest será usada.

Parâmetros de runtime

Usar condicionais com parâmetros

Você também pode usar parâmetros como parte da lógica condicional. Com condicionais, parte de um YAML será executada se atender aos critérios if.

Usar parâmetros para determinar quais etapas são executadas

Esse pipeline adiciona um segundo parâmetro booliano, test, que pode ser usado para controlar se os testes devem ou não ser executados no pipeline. Quando o valor de test é true, a etapa que gera Executar todos os testes é executada.

parameters:
- name: image
  displayName: Pool Image
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest
- name: test
  displayName: Run Tests?
  type: boolean
  default: false

trigger: none

jobs:
- job: build
  displayName: Build and Test
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber)
  - ${{ if eq(parameters.test, true) }}:
    - script: echo "Running all the tests"

Usar parâmetros para definir qual configuração é usada

Você também pode usar parâmetros para definir quais trabalhos são executados. Neste exemplo, diferentes arquiteturas são compiladas dependendo do valor do parâmetro config, que é um tipo string. Por padrão, as arquiteturas x86 e x64 são criadas.

parameters:
- name: configs
  type: string
  default: 'x86,x64'

trigger: none

jobs:
- ${{ if contains(parameters.configs, 'x86') }}:
  - job: x86
    steps:
    - script: echo Building x86...
- ${{ if contains(parameters.configs, 'x64') }}:
  - job: x64
    steps:
    - script: echo Building x64...
- ${{ if contains(parameters.configs, 'arm') }}:
  - job: arm
    steps:
    - script: echo Building arm...

Excluir seletivamente uma fase

Você também pode usar parâmetros para definir se uma fase é executada. Neste exemplo, há um pipeline com quatro fases e trabalhos diferentes para cada fase. A fase teste de desempenho será executada se o parâmetro runPerfTests for true. O valor padrão de runPerfTests é false, portanto, sem nenhuma atualização, apenas três dos quatro estágios são executados.

parameters:
- name: runPerfTests
  type: boolean
  default: false

trigger: none

stages:
- stage: Build
  displayName: Build
  jobs:
  - job: Build
    steps:
    - script: echo running Build


- stage: UnitTest
  displayName: Unit Test
  dependsOn: Build
  jobs:
  - job: UnitTest
    steps:
    - script: echo running UnitTest


- ${{ if eq(parameters.runPerfTests, true) }}:
  - stage: PerfTest
    displayName: Performance Test
    dependsOn: Build
    jobs:
    - job: PerfTest
      steps:
      - script: echo running PerfTest


- stage: Deploy
  displayName: Deploy
  dependsOn: UnitTest
  jobs:
  - job: Deploy
    steps:
    - script: echo running UnitTest

Executar um loop por meio de parâmetros

Você também pode executar um loop pelos parâmetros de cadeia de caracteres, número e booliano.

Neste exemplo, você executa um loop pelos parâmetros e imprime o nome e o valor de cada parâmetro. Há quatro parâmetros diferentes e cada um representa um tipo diferente. myStringName é uma cadeia de caracteres de linha única. myMultiString é uma cadeia de caracteres de várias linhas. myNumber is a number. myBoolean é um valor booliano. Na seção de etapas, as tarefas de script geram a chave e o valor de cada parâmetro.

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- 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

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

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

Verificar se há um objeto de parâmetro vazio

Você pode usar a length()expressão para verificar se um parâmetro de objeto não tem valor.

parameters:
- name: foo
  type: object
  default: []

steps:
- checkout: none
- ${{ if eq(length(parameters.foo), 0) }}:
  - script: echo Foo is empty
    displayName: Foo is empty

Tipos de dados do parâmetro

Tipo de dados Observações
string string
number pode ser restrito a values:, caso contrário, qualquer cadeia de caracteres semelhante a número será aceita
boolean true ou false
object qualquer estrutura do YAML
step uma etapa única
stepList sequência de etapas
job um trabalho único
jobList sequência de trabalhos
deployment um trabalho de implantação única
deploymentList sequência de trabalhos de implantação
stage uma fase única
stageList sequência de fases

Os tipos de dados de fase, stepList, trabalho, jobList, implantação, deploymentList, fase e stageList usam o formato de esquema YAML padrão. Este exemplo inclui cadeia de caracteres, número, booliano, objeto, etapa e 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 }}