Runtime parameters (Parâmetros de runtime)

Serviços de DevOps do Azure | Azure DevOps Server 2022 | Azure DevOps Server 2020

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

• Fornecer valores diferentes para scripts e tarefas em tempo de execução
• Tipos de parâmetros de controle, intervalos permitidos e padrões
• Selecione 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 número e cadeia de caracteres, e podem ser restritos a um subconjunto de valores. A parameters seção 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 imediatamente 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 do pipeline.

Nota

Estas orientações não se aplicam aos gasodutos clássicos. Para parâmetros em pipelines clássicos, consulte 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 em seu arquivo YAML ou quando você executa seu 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 estágios, etapas e trabalhos que são usados como parâmetros em um modelo.

Usar parâmetros em pipelines

Defina parâmetros de tempo de execução no início de um YAML.

Este pipeline de exemplo inclui um image parâmetro com três agentes hospedados como string opções. Na seção jobs, o pool valor especifica o agente a partir do parâmetro usado para executar o trabalho. O trigger é definido como none para que você possa selecionar o valor de image quando você acionar manualmente o pipeline para ser executado.

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, selecione a Imagem do Pool. Se você não fizer uma seleção, a opção ubuntu-latest padrão será usada.

Use condicionais com parâmetros

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

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

Esse pipeline adiciona um segundo parâmetro booleano, 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 Executando 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 qual trabalho é executado. Neste exemplo, diferentes arquiteturas são construídas dependendo do valor do config parâmetro, que é um string tipo. Por padrão, as arquiteturas e x64 são x86 compiladas.

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 um estágio

Você também pode usar parâmetros para definir se um estágio é executado. Neste exemplo, há um pipeline com quatro estágios e trabalhos diferentes para cada estágio. O estágio de teste de desempenho é executado se o parâmetro runPerfTests for true. O valor padrão de runPerfTests é false, portanto, sem atualizações, 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

Percorrer os parâmetros

Você também pode fazer loop através de sua cadeia de caracteres, número e parâmetros booleanos.

Script

Neste exemplo, você faz um loop pelos parâmetros e imprime o nome e o valor de cada parâmetro. Existem 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 é um número. myBoolean é um valor booleano. Na seção de etapas, as tarefas de script produzem 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

PowerShell

Neste exemplo, você faz um loop pelos parâmetros e imprime o nome e o valor de cada parâmetro. Existem 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 é um número. myBoolean é um valor booleano. Na seção de etapas, você percorre parâmetros em uma tarefa do PowerShell e define cada parâmetro como uma variável de ambiente.

# 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: 
  - task: PowerShell@2
    env:
      ${{ each parameter in parameters }}:
        ${{ parameter.Key }}: ${{ parameter.Value }}
    inputs:
      filePath: test_script.ps1
      pwsh: true

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

# test_script.ps1

Write-Host "Hello, World!"
Write-Host $env:myStringName

Verificar se há um objeto de parâmetro vazio

Você pode usar a length() expressão para verificar se um parâmetro object 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

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: build e deploy.
• 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 build.yml modelo:

• Define o parâmetro build_tasks com o tipo stepList e uma lista vazia padrão.
• Define o SDK do .NET Core como 6.x.
• Itera em cada etapa do build_tasks parâmetro.
• 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: '6.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'

Tipos de dados de parâmetros

Tipo de dados	Notas
string	string
number	pode ser restrito a , caso contrário, qualquer cadeia de caracteres semelhante a values:um número é aceita
boolean	true ou false
object	qualquer estrutura YAML
step	Um único passo
stepList	Sequência de passos
job	um único emprego
jobList	Sequência de trabalhos
deployment	Um único trabalho de implantação
deploymentList	Sequência de trabalhos de implantação
stage	uma única etapa
stageList	Sequência de estágios

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