Variáveis de lançamento e artefatos clássicos
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
As variáveis clássicas de lançamento e artefatos são uma maneira prática de trocar e transportar dados em todo o pipeline. Cada variável é armazenada como uma cadeia de caracteres e seu valor pode ser alterado entre as execuções do pipeline.
As variáveis são diferentes dos parâmetros de runtime, que só estão disponíveis no momento da análise do modelo.
À medida que você compõe as tarefas para implantar seu aplicativo em cada fase nos seus processos de CI/CD do DevOps, as variáveis ajudarão você a:
Definir um pipeline de implantação mais genérico uma vez e personalizá-lo facilmente para cada fase. Por exemplo, uma variável pode ser usada para representar a cadeia de conexão para implantação da Web e o valor dessa variável pode ser alterado de uma fase para outra. Elas são variáveis personalizadas.
Use informações sobre o contexto da versão, fase, artefato ou agente específico no qual o pipeline de implantação está sendo executado. Por exemplo, seu script pode precisar de acesso ao local do build para baixá-lo ou ao diretório de trabalho no agente para criar arquivos temporários. Elas são 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 informações sobre o contexto de execução são disponibilizadas para executar tarefas por meio de variáveis padrão. Suas tarefas e scripts podem usar essas variáveis para encontrar informações sobre o sistema, versão, fase ou agente em que estão sendo executados. Com exceção de System.Debug, essas variáveis são somente leitura e seus valores são 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.
Dica
Você pode exibir os valores atuais de todas as variáveis para uma versão e usar uma variável padrão para executar uma versão no modo de depuração.
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 |
Versão
| 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 origem do artefato primário 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 da versão 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 disparou a versão. Exemplo: Mateo Escobedo |
| Release.RequestedForEmail | O endereço de email da identidade que disparou a versão. Exemplo: mateo@fabrikam.com |
| Release.RequestedForId | A ID da identidade que disparou a versão. 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 |
Release-stage
| 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 |
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 |
Artefato Geral
Para cada artefato referenciado em uma versão, você pode usar as variáveis de artefato a seguir. Nem todas as variáveis são significativas para cada tipo de artefato. A tabela a seguir lista as variáveis de artefato padrão e fornece exemplos dos valores que elas têm, dependendo do tipo de artefato. Se um exemplo estiver vazio, isso significa que a variável não foi preenchida para esse tipo de artefato.
Substitua o espaço {alias} reservado pelo valor especificado para o alias do artefato ou pelo 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 build ou repositório. Exemplo do Azure Pipelines: 1Exemplo do GitHub: fabrikam/asp |
| Release.Artifacts.{alias}.DefinitionName | O nome do pipeline de build ou repositório. Exemplo do Azure Pipelines: fabrikam-ciExemplo do TFVC: $/fabrikamExemplo do Git: fabrikamExemplo do GitHub: fabrikam/asp (main) |
| Release.Artifacts.{alias}.BuildNumber | O número de build ou o identificador de commit. Exemplo do Azure Pipelines: 20170112.1Exemplo do Jenkins/TeamCity: 20170112.1Exemplo do TFVC: Changeset 3Exemplo do Git: 38629c964Exemplo do GitHub: 38629c964 |
| Release.Artifacts.{alias}.BuildId | O identificador de build. Exemplo do Azure Pipelines: 130Exemplo do Jenkins/TeamCity: 130Exemplo do GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts.{alias}.BuildURI | A URL do build. Exemplo do Azure Pipelines: vstfs://build-release/Build/130Exemplo do GitHub: https://github.com/fabrikam/asp |
| Release.Artifacts.{alias}.SourceBranch | O caminho completo e o nome do branch no qual a origem foi compilada. Exemplo do Azure Pipelines: refs/heads/main |
| Release.Artifacts.{alias}.SourceBranchName | O nome somente do branch no qual a origem foi compilada. Exemplo do Azure Pipelines: main |
| Release.Artifacts.{alias}.SourceVersion | O commit que foi compilado. Exemplo do Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7 |
| Release.Artifacts.{alias}.Repository.Provider | O tipo de repositório no qual a origem foi compilada. Exemplo do Azure Pipelines: Git |
| Release.Artifacts.{alias}.RequestedForID | O identificador da conta que disparou o build. Exemplo do Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.Artifacts.{alias}.RequestedFor | O nome da conta que solicitou o build. Exemplo do Azure Pipelines: Mateo Escobedo |
| Release.Artifacts.{alias}.Type | O tipo de origem do artefato, como Build. Exemplo do Azure Pipelines: BuildExemplo do Jenkins: JenkinsExemplo do TeamCity: TeamCityExemplo do TFVC: TFVCExemplo do Git: GitExemplo do 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 disparada por um fluxo de solicitação de pull. Exemplo do 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 disparada por um fluxo de solicitação de pull. Exemplo do Azure Pipelines: main |
Confira também Alias de origem do artefato
Artefato Primário
Você designa um dos artefatos como artefato primário em um pipeline de lançamento. Para o artefato primário designado, o Azure Pipelines preenche as variáveis a seguir.
| 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 nos seus scripts.
Você pode usar diretamente uma variável padrão como uma entrada para uma tarefa.
Por exemplo, para passar Release.Artifacts.{Artifact alias}.DefinitionName para a origem do artefato cujo alias é ASPNET4.CI para uma tarefa, você usaria $(Release.Artifacts.ASPNET4.CI.DefinitionName).
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 da variável de artefato Release.Artifacts.{Artifact alias}.DefinitionName para a origem do artefato cujo alias é ASPNET4.CI em um script do PowerShell, você usaria $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME.
Observe que o nome original do alias de origem do artefato, ASPNET4.CI, é substituído por ASPNET4_CI.
Exibir os valores atuais de todas as variáveis
Abra a exibição de pipelines do resumo da versão e escolha a fase em que você está interessado. Na lista de etapas, escolha Inicializar trabalho.
Isso abrirá o log desta etapa. Role para baixo para ver os valores usados pelo agente para este trabalho.
Executar um lançamento no modo de depuração
Mostrar informações adicionais à medida uma versão é executada e nos arquivos de log executando toda a versão ou apenas as tarefas em uma fase de versão individual, no modo de depuração. Isso pode ajudar a resolve problemas e falhas.
Para iniciar o modo de depuração para uma versão inteira, adicione uma variável chamada
System.Debugcom o valortrueà guia Variáveis de um pipeline de lançamento.Para iniciar o modo de depuração para uma única fase, abra a caixa de diálogo Configurar fase no menu de atalho da fase e adicione uma variável chamada
System.Debugcom o valortrueà guia Variáveis.Como alternativa, crie um grupo de variáveis que contenha uma variável chamada
System.Debugcom o valortruee vincule esse grupo de variáveis a um pipeline de lançamento.
Dica
Se você receber um erro relacionado a uma conexão de serviço do Azure RM, confira Instruções: solucionar problemas de conexões de serviço do Azure Resource Manager.
Variáveis personalizadas
As variáveis personalizadas podem ser definidas em vários escopos.
Compartilhe valores em todas as definições em um projeto usando grupos de variáveis. Escolha um grupo de variáveis quando precisar usar os mesmos valores em todas as definições, fases e tarefas em um projeto e quiser alterar os valores em um único lugar. Você define e gerencia grupos de variáveis na guia Biblioteca.
Compartilhe os valores em todas as fases usando as variáveis de pipeline de lançamento. Escolha uma variável do pipeline de lançamento quando precisar usar o mesmo valor em todas as fases e tarefas no pipeline de lançamento e quiser alterar o valor em um só lugar. Você define e gerencia essas variáveis na guia Variáveis em um pipeline de lançamento. Na página Variáveis de Pipeline, abra a lista suspensa Escopo e selecione "Versão". Por padrão, quando você adiciona uma variável, ela é definida como Escopo da versão.
Compartilhe valores em todas as tarefas em uma fase específica usando as variáveis de fase. Use uma variável no nível da fase para valores que variam de fase para fase (e são os mesmos em todas as tarefas em uma fase). Você define e gerencia essas variáveis na guia Variáveis de um pipeline de lançamento. Na página Variáveis de Pipeline, abra a lista suspensa Escopo e selecione a fase necessária. Ao adicionar uma variável, defina o Escopo como o ambiente apropriado.
O uso de variáveis personalizadas no projeto, no pipeline de lançamento e no escopo da fase ajuda você a:
Evite a duplicação de valores, facilitando a atualização de todas as ocorrências como uma operação.
Armazene os valores confidenciais de modo que não possam ser vistos ou alterados pelos usuários dos pipelines de lançamento. Designe uma propriedade de configuração para ser uma variável segura (segredo) selecionando o ícone de
(cadeado) ao lado da variável.Importante
Os valores das variáveis ocultas (segredo) são armazenados com segurança no servidor e não podem ser exibidos pelos usuários após serem salvos. Durante uma implantação, o serviço de lançamento do Azure Pipelines descriptografa esses valores quando referenciados pelas tarefas e 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, a variável de ambiente Caminho do PowerShell. Se você criar uma variável personalizada Path em um agente do Windows, ela substituirá a variável $env:Path e o PowerShell não poderá ser executado.
Usar variáveis personalizadas
Para usar variáveis personalizadas nas suas tarefas de build e lançamento, basta colocar o nome da variável entre parênteses precedido por um caractere $. Por exemplo, se você tiver uma variável chamada adminUserName, poderá inserir o valor atual dessa variável em um parâmetro de uma tarefa como $(adminUserName).
Observação
Variáveis em diferentes grupos vinculados a um pipeline no mesmo escopo (por exemplo, trabalho ou fase) colidirão e o resultado pode ser imprevisível. Use nomes diferentes para variáveis em todos os seus grupos de variáveis.
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.
Observe que o valor da variável atualizada tem como escopo o trabalho que está sendo executado e não flui entre trabalhos ou fases.
Os nomes das variáveis são transformados em maiúsculas e os caracteres "." e " " são substituídos por "_".
Por exemplo, Agent.WorkFolder torna-se AGENT_WORKFOLDER.
No Windows, você acessa isso como %AGENT_WORKFOLDER% ou $env:AGENT_WORKFOLDER.
No Linux e no macOS, você usa $AGENT_WORKFOLDER.
Dica
Você pode executar um script em um:
- Agente do Windows usando uma tarefa de script do Lote ou uma tarefa de script do PowerShell.
- Agente macOS ou Linux usando uma tarefa de script de shell.
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)
Definir as variáveis 
Definir as variáveis 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)
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de