Compartilhar via


Usar variáveis nos pipelines de lançamento clássico

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

O uso de variáveis nos pipelines clássicos de lançamento é uma maneira conveniente de trocar e transportar dados em todo o pipeline. Cada variável é armazenada como uma cadeia de caracteres e o seu valor pode mudar entre as execuções do pipeline.

Ao contrário dos parâmetros de tempo de execução, que só estão disponíveis no momento da análise do modelo, as variáveis nos pipelines de lançamento clássicos podem ser acessadas durante todo o processo de implantação

Ao configurar tarefas para implantar seu aplicativo em cada estágio do pipelines clássicos de lançamento, as variáveis podem ajudá-lo a:

  • Simplificar a personalização: defina um pipeline de implantação genérico uma vez e adapte-o facilmente para diferentes estágios. Por exemplo, use uma variável para representar a cadeia de conexão de uma implantação da Web e ajuste o seu valor conforme for necessário para cada estágio. São conhecidas como variáveis personalizadas.

  • Aproveite as informações contextuais: acesse detalhes sobre o contexto da versão, como um estágio, um artefato, ou o agente executando a implantação. Por exemplo, seus scripts podem exigir o local de compilação para o download ou o diretório de trabalho do agente para criar arquivos temporários. Eles são chamados de variáveis padrão.

Observação

Para pipelines YAML, confira variáveis definidas pelo usuário e variáveis predefinidas para obter mais detalhes.

Variáveis padrão

As variáveis padrão disponibilizam informações essenciais sobre o contexto de execução para as suas tarefas e scripts em execução. Essas variáveis permitem que você acesse detalhes sobre o sistema, lançamento, estágio, ou o agente no qual elas estão sendo executadas.

Com exceção de System.Debug, as variáveis padrão são somente leitura, com seus valores definidos automaticamente pelo sistema.

Algumas das variáveis mais significativas são descritas nas tabelas a seguir. Para exibir a lista completa, confira Exibir os valores atuais de todas as variáveis.

Variáveis do sistema

Nome da variável Descrição
System.TeamFoundationServerUri A URL da conexão de serviço no Azure Pipelines. Use isso nos scripts ou nas tarefas para chamar APIs REST do Azure Pipelines.

Exemplo: https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri A URL da coleção do Team Foundation ou do Azure Pipelines. Use isso nos scripts ou nas tarefas para chamar APIs REST em outros serviços, como controle de Build e Versão.

Exemplo: https://dev.azure.com/fabrikam/
System.CollectionId A ID da coleção à qual esse build ou versão pertence.

Exemplo: 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId A ID do pipeline de lançamento à qual a versão atual pertence.

Exemplo: 1
System.TeamProject O nome do projeto ao qual este build ou versão pertence.

Exemplo: Fabrikam
System.TeamProjectId A ID do projeto à qual este build ou versão pertence.

Exemplo: 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory O diretório no qual os artefatos são baixados durante a implantação de uma versão. O diretório será limpo antes de cada implantação, se exigir que os artefatos sejam baixados no agente. O mesmo que Agent.ReleaseDirectory e System.DefaultWorkingDirectory.

Exemplo: C:\agent\_work\r1\a
System.DefaultWorkingDirectory O diretório no qual os artefatos são baixados durante a implantação de uma versão. O diretório será limpo antes de cada implantação, se exigir que os artefatos sejam baixados no agente. O mesmo que Agent.ReleaseDirectory e System.ArtifactsDirectory.

Exemplo: C:\agent\_work\r1\a
System.WorkFolder O diretório de trabalho para esse agente, em que as subpastas são criadas para cada build ou versão. O mesmo que Agent.RootDirectory e Agent.WorkFolder.

Exemplo: C:\agent\_work
System.Debug Essa é a única variável do sistema que pode ser definida pelos usuários. Defina isso como true para executar a versão no modo de depuração para ajudar na localização de falhas.

Exemplo: true

Variáveis de lançamento

Nome da variável Descrição
Release.AttemptNumber O número de vezes que esta versão é implantada nesta fase.

Exemplo: 1
Release.DefinitionEnvironmentId A ID da fase no pipeline de lançamento correspondente.

Exemplo: 1
Release.DefinitionId A ID do pipeline de lançamento à qual a versão atual pertence.

Exemplo: 1
Release.DefinitionName O nome do pipeline de lançamento ao qual a versão atual pertence.

Exemplo: fabrikam-cd
Release.Deployment.RequestedFor O nome de exibição da identidade que disparou (iniciou) a implantação em andamento no momento.

Exemplo: Mateo Escobedo
Release.Deployment.RequestedForEmail O endereço de email da identidade que disparou (iniciou) a implantação em andamento no momento.

Exemplo: mateo@fabrikam.com
Release.Deployment.RequestedForId A ID da identidade que disparou (iniciou) a implantação em andamento no momento.

Exemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID A ID da implantação. Exclusivo por trabalho.

Exemplo: 254
Release.DeployPhaseID A ID da fase em que a implantação está em execução.

Exemplo: 127
Release.EnvironmentId A ID da instância de fase em uma versão para a qual a implantação está em andamento no momento.

Exemplo: 276
Release.EnvironmentName O nome da fase para o qual a implantação está em andamento no momento.

Exemplo: Dev
Release.EnvironmentUri O URI da instância de fase em uma versão para a qual a implantação está em andamento no momento.

Exemplo: vstfs://ReleaseManagement/Environment/276
Release.Environments.{stage-name}.status O status de implantação da fase.

Exemplo: InProgress
Release.PrimaryArtifactSourceAlias O alias da fonte primária do artefato.

Exemplo: fabrikam\_web
Release.Reason O motivo da implantação. Os valores com suporte são:
ContinuousIntegration – a versão iniciada na Implantação Contínua após a conclusão de um build.
Manual – a versão iniciada manualmente.
None – o motivo da implantação não foi especificado.
Schedule – a versão foi iniciada em um agendamento.
Release.ReleaseDescription A descrição do texto fornecida no momento da versão.

Exemplo: Critical security patch
Release.ReleaseId O identificador do registro de versão atual.

Exemplo: 118
Release.ReleaseName O nome da versão atual.

Exemplo: Release-47
Release.ReleaseUri O URI do lançamento atual.

Exemplo: vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL A URL desta versão.

Exemplo: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor O nome de exibição da identidade que acionou o lançamento.

Exemplo: Mateo Escobedo
Release.RequestedForEmail O endereço de email da identidade que acionou o lançamento.

Exemplo: mateo@fabrikam.com
Release.RequestedForId O ID da identidade que disparou o lançamento.

Exemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload Valor booliano que especifica se deseja ou não ignorar o download de artefatos para o agente.

Exemplo: FALSE
Release.TriggeringArtifact.Alias O alias do artefato que disparou a versão. Ele fica vazio quando a versão foi agendada ou disparada manualmente.

Exemplo: fabrikam\_app

Variáveis do estágio de lançamento

Nome da variável Descrição
Release.Environments.{stage name}.Status O status da implantação desta versão em uma fase especificada.

Exemplo: NotStarted

Variáveis do agente

Nome da variável Descrição
Agent.Name O nome do agente conforme registrado no pool de agentes. É provável que seja diferente do nome do computador.

Exemplo: fabrikam-agent
Agent.MachineName O nome do computador em que o agente foi configurado.

Exemplo: fabrikam-agent
Agent.Version A versão do software do agente.

Exemplo: 2.109.1
Agent.JobName O nome do trabalho em execução, como Versão ou Build.

Exemplo: Release
Agent.HomeDirectory A pasta em que o agente foi instalado. Essa pasta contém o código e os recursos do agente.

Exemplo: C:\agent
Agent.ReleaseDirectory O diretório no qual os artefatos são baixados durante a implantação de uma versão. O diretório será limpo antes de cada implantação, se exigir que os artefatos sejam baixados no agente. O mesmo que System.ArtifactsDirectory e System.DefaultWorkingDirectory.

Exemplo: C:\agent\_work\r1\a
Agent.RootDirectory O diretório de trabalho para esse agente, em que as subpastas são criadas para cada build ou versão. O mesmo que Agent.WorkFolder e System.WorkFolder.

Exemplo: C:\agent\_work
Agent.WorkFolder O diretório de trabalho para esse agente, em que as subpastas são criadas para cada build ou versão. O mesmo que Agent.RootDirectory e System.WorkFolder.

Exemplo: C:\agent\_work
Agent.DeploymentGroupId A ID do grupo de implantação com o qual o agente está registrado. Só está disponível em trabalhos de grupo de implantação.

Exemplo: 1

Variáveis de artefatos de lançamento

Para cada artefato referenciado em uma versão, você pode usar as variáveis de artefato a seguir. Observe que nem todas as variáveis se aplicam a todos os tipos de artefatos. A tabela a seguir lista as variáveis de artefato padrão e fornece exemplos dos seus valores, baseado no tipo de artefato. Se um exemplo estiver vazio, isso indica que a variável não é aplicável a esse tipo de artefato.

Substitua {alias} com o valor que você especificou para a fonte de artefato alias ou com o valor padrão gerado para o pipeline de lançamento.

Nome da variável Descrição
Release.Artifacts.{alias}.DefinitionId O identificador do pipeline de compilação ou repository.Examples:

Azure Pipelines: 1
GitHub: fabrikam/asp
Release.Artifacts.{alias}.DefinitionName O nome do pipeline de compilação ou do repository.Examples:

Azure Pipelines: fabrikam-ci
TFVC: $/fabrikam
Git: fabrikam
GitHub: fabrikam/asp (main)
Release.Artifacts.{alias}.BuildNumber O número de compilação ou o commit de identifier.Examples:

Azure Pipelines: 20170112.1
Jenkins: 20170112.1
TFVC: Changeset 3
Git: 38629c964
GitHub: 38629c964
Release.Artifacts.{alias}.BuildId O compilador de identifier.Examples:

Azure Pipelines: 130
Jenkins: 130
GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts.{alias}.BuildURI A URL para build.Examples:

Azure Pipelines: vstfs://build-release/Build/130
GitHub: https://github.com/fabrikam/asp
Release.Artifacts.{alias}.SourceBranch O caminho completo e o nome do branch no qual a origem foi build.Examples:

Azure Pipelines: refs/heads/main
Release.Artifacts.{alias}.SourceBranchName O nome apenas do branch no qual a origem foi build.Examples:

Azure Pipelines: main
Release.Artifacts.{alias}.SourceVersion O commit que foi build.Examples:

Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts.{alias}.Repository.Provider O tipo de repositório no qual a origem foi build.Examples:

Azure Pipelines: Git
Release.Artifacts.{alias}.RequestedForID O identificador da conta que acionou build.Examples:

Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts.{alias}.RequestedFor O nome da conta que solicitou build.Examples:

Azure Pipelines: Mateo Escobedo
Release.Artifacts.{alias}.Type O tipo de origem do artefato, como Build.Examples

Azure Pipelines: Build
Jenkins: Jenkins
TFVC: TFVC
Git: Git
GitHub: GitHub
Release.Artifacts.{alias}.PullRequest.TargetBranch O caminho completo e o nome do branch que é o destino de uma solicitação de pull. Essa variável será inicializada somente se a versão for acionada por uma solicitação pull flow.Examples:

Azure Pipelines: refs/heads/main
Release.Artifacts.{alias}.PullRequest.TargetBranchName O nome somente do branch que é o destino de uma solicitação de pull. Essa variável será inicializada somente se a versão for acionada por uma solicitação pull flow.Examples:

Azure Pipelines: main

Variáveis de artefato primária

Em pipelines de lançamento clássicos, se você estiver usando vários artefatos, poderá designar um como o artefato primário. O Azure Pipelines preencherá as seguintes variáveis para o artefato primário designado.

Nome da variável Mesmo que
Build.DefinitionId Release.Artifacts.{Primary artifact alias}.DefinitionId
Build.DefinitionName Release.Artifacts.{Primary artifact alias}.DefinitionName
Build.BuildNumber Release.Artifacts.{Primary artifact alias}.BuildNumber
Build.BuildId Release.Artifacts.{Primary artifact alias}.BuildId
Build.BuildURI Release.Artifacts.{Primary artifact alias}.BuildURI
Build.SourceBranch Release.Artifacts.{Primary artifact alias}.SourceBranch
Build.SourceBranchName Release.Artifacts.{Primary artifact alias}.SourceBranchName
Build.SourceVersion Release.Artifacts.{Primary artifact alias}.SourceVersion
Build.Repository.Provider Release.Artifacts.{Primary artifact alias}.Repository.Provider
Build.RequestedForID Release.Artifacts.{Primary artifact alias}.RequestedForID
Build.RequestedFor Release.Artifacts.{Primary artifact alias}.RequestedFor
Build.Type Release.Artifacts.{Primary artifact alias}.Type
Build.PullRequest.TargetBranch Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName

Usar variáveis padrão

Você pode usar as variáveis padrão de duas maneiras: como parâmetros para tarefas em um pipeline de lançamento ou em seus scripts.

Você pode usar uma variável padrão diretamente como uma entrada para uma tarefa. Por exemplo, para passar Release.Artifacts.{Artifact alias}.DefinitionName como um argumento para uma tarefa do PowerShell para um artefato com ASPNET4.CI como seu alias, você usaria $(Release.Artifacts.ASPNET4.CI.DefinitionName).

Uma captura de tela que mostra como usar uma variável padrão como argumento.

Para usar uma variável padrão no seu script, primeiro você deve substituir o . nos nomes de variáveis padrão por _. Por exemplo, para imprimir o valor de Release.Artifacts.{Artifact alias}.DefinitionName para um artefato com ASPNET4.CI como seu alias em um script do PowerShell, use $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME. Observe que o alias original, ASPNET4.CI, é substituído por ASPNET4_CI.

Uma captura de tela que mostra como usar uma variável padrão em um script do PowerShell em linha.

Variáveis personalizadas

As variáveis personalizadas podem ser definidas em vários escopos.

  • Grupos de variáveis: use grupos de variáveis para compartilhar valores em todas as definições de um projeto. Isso é útil quando você deseja usar os mesmos valores em definições, estágios e tarefas em um projeto e gerenciá-los em um único local. Defina e gerencie grupos de variáveis na Biblioteca de >pipelines.

  • Variáveis de pipeline de lançamento: use variáveis de pipeline de lançamento para compartilhar valores em todos os estágios de um pipeline de lançamento. Isso é o ideal para os cenários em que você precisa de um valor consistente entre estágios e tarefas, com a capacidade de atualizá-lo de um único local. Defina e gerencia essas variáveis na guia Variáveis de um pipeline de lançamento. Na página Variáveis do pipeline, defina a lista suspensa de escopo para Lançamento ao adicionar uma variável.

  • Variáveis de estágio: use variáveis de estágio para compartilhar valores em um estágio específico de um pipeline de lançamento. Isso é útil para valores que diferem de estágio para estágio, mas são consistentes em todas as tarefas dentro de um estágio. Defina e gerencia essas variáveis na guia Variáveis de um pipeline de lançamento. Na página Variáveis de pipeline, defina a lista suspensa do escopo como o ambiente apropriado ao adicionar uma variável.

O uso de variáveis personalizadas nos níveis do projeto, do pipeline de lançamento e do estágio ajuda a:

  • Evite a duplicação de valores, facilitando a atualização de todas as ocorrências com uma única alteração.

  • Proteja os valores confidenciais impedindo que sejam visualizados ou modificados pelos usuários. Para marcar uma variável como segura (secreta), selecione o cadeado o ícone ao lado da variável.

    Importante

    Os valores das variáveis ocultas (secretas) são armazenados com segurança no servidor e não podem ser visualizados pelos usuários após serem salvos. Durante a implantação, o Azure Pipelines descriptografa esses valores quando são referenciados por tarefas e os passa para o agente por meio de um canal HTTPS seguro.

Observação

A criação de variáveis personalizadas pode substituir variáveis padrão. Por exemplo, se você definir uma variável Path em um agente Windows, ele substituirá a variável $env:Path o que pode impedir que o PowerShell seja executado corretamente.

Usar variáveis personalizadas

Para usar variáveis personalizadas em suas tarefas, coloque o nome da variável entre parênteses e preceda-o com um caractere $. Por exemplo, se você tiver uma variável chamada adminUserName, poderá inserir seu valor atual em uma tarefa como $(adminUserName).

Observação

As variáveis de diferentes grupos vinculadas a um pipeline no mesmo escopo (por exemplo, trabalho ou estágio) podem entrar em conflito, levando a resultados imprevisíveis. Para evitar isso, certifique-se de que as variáveis em todos os seus grupos de variáveis possuam um único nome.

Definir e modificar suas variáveis em um script

Para definir ou modificar uma variável de um script, use o comando de log task.setvariable. O valor da variável atualizada tem como escopo o trabalho que está sendo executado e não persiste entre trabalhos ou estágios. Observe que os nomes das variáveis são transformados em maiúsculas, com "." e " " substituídos por "_".

Por exemplo, Agent.WorkFolder se tornará AGENT_WORKFOLDER.

  • No Windows, você acessa a variável como %AGENT_WORKFOLDER% ou $env:AGENT_WORKFOLDER.
  • No Linux e no macOS, use $AGENT_WORKFOLDER.

Dica

Você pode executar um script em:

Script de lote

Definir as variáveis sauce e secret.Sauce

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

Ler as variáveis

Argumentos

"$(sauce)" "$(secret.Sauce)"

Script

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)

Saída do console da leitura das variáveis:

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)

Exibir os valores atuais de todas as variáveis

  1. Selecione Pipelines>Versões e, em seguida, selecione o pipeline de lançamento.

  2. Abra a visualização de resumo do seu lançamento e selecione o estágio em que está interessado. Na lista de etapas, escolha Inicializar trabalho.

    Uma captura de tela que exibe a etapa de inicialização do trabalho.

  3. Isso abrirá os logs desta etapa. Role para baixo para ver os valores usados pelo agente para este trabalho.

    Uma captura de tela que exibe as variáveis usadas pelo agente.

Executar um lançamento no modo de depuração

A execução de uma versão no modo de depuração pode ajudá-lo a diagnosticar e resolver problemas ou falhas, exibindo informações adicionais durante a execução do lançamento. Você pode habilitar o modo de depuração para todo o lançamento ou apenas para as tarefas dentro de um estágio de lançamento específico.

  • Para iniciar o modo de depuração para um lançamento inteiro, adicione uma variável chamada System.Debug com o valor true para a guia de Variáveis de um pipeline de lançamento.

  • Para habilitar o modo de depuração em um estágio específico, abra Configurar estágio no menu de atalho do estágio e adicione uma variável chamada System.Debug com o valor true para a guia de Variáveis.

  • Como alternativa, crie um grupo de variáveis que contenha uma variável chamada System.Debug com o valor true e vincule esse grupo de variáveis a o pipeline de lançamento.

Dica

Se você encontrar um erro relacionado às conexões do serviço ARM do Azure, consulte Como solucionar problemas de conexões de serviço do Azure Resource Manager para obter mais detalhes.