通过

在经典发布管道中使用变量

  • 项目

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

在经典发布管道中使用变量是在整个管道中交换和传输数据的一种便捷方式。 每个变量都存储为字符串，其值可以在管道运行之间更改。

与仅在模板分析时可用的运行时参数不同，经典发布管道中的变量可在整个部署过程中访问

在经典发布管道的每个阶段设置部署应用程序的任务时，变量可以帮助：

  • 简化自定义：定义一次通用部署管道，并轻松地针对不同的阶段对其进行调整。 例如，使用变量来表示 Web 部署的连接字符串，并根据需要为每个阶段调整其值。 这些变量称为自定义变量。

  • 利用上下文信息：访问有关发布上下文的详细信息，例如阶段、项目或运行部署的代理。 例如，脚本可能需要生成位置进行下载，或者需要代理的工作目录来创建临时文件。 这些变量称为默认变量。

注意

有关 YAML 管道的详细信息，请参阅用户定义的变量和预定义变量。

默认变量

默认变量为正在运行的任务和脚本提供有关执行上下文的基本信息。 这些变量允许你访问有关运行它们的系统、发布、阶段或代理的详细信息。

除 System.Debug 之外，默认变量都是只读的，它们的值由系统自动设置。

下表描述了一些最重要的变量。 若要查看完整列表，请参阅查看所有变量的当前值。

系统变量

变量名称 说明
System.TeamFoundationServerUri Azure Pipelines 中服务连接的 URL。 在脚本或任务中使用它来调用 Azure Pipelines REST API。

示例：https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri Team Foundation 集合或 Azure Pipelines 的 URL。 在脚本或任务中使用它来调用其他服务（如 Build 和 Version 控制）上的 REST API。

示例：https://dev.azure.com/fabrikam/
System.CollectionId 此生成或发布所属的集合的 ID。

示例： 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId 当前发布所属的发布管道的 ID。

示例： 1
System.TeamProject 此生成或发布所属的项目的名称。

示例：Fabrikam
System.TeamProjectId 此生成或发布所属的项目的 ID。

示例： 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory 在部署发布期间将项目下载到的目录。 如果目录需要将项目下载到代理，则会在每次部署之前清除该目录。 与 Agent.ReleaseDirectory 和 System.DefaultWorkingDirectory 相同。

示例：C:\agent\_work\r1\a
System.DefaultWorkingDirectory 在部署发布期间将项目下载到的目录。 如果目录需要将项目下载到代理，则会在每次部署之前清除该目录。 与 Agent.ReleaseDirectory 和 System.ArtifactsDirectory 相同。

示例：C:\agent\_work\r1\a
System.WorkFolder 此代理的工作目录，在其中为每个生成或发布创建子文件夹。 与 Agent.RootDirectory 和 Agent.WorkFolder 相同。

示例：C:\agent\_work
System.Debug 这是唯一可以由用户设置的系统变量。 将此设置为 true，即可在调试模式下运行发布，以帮助查找错误。

示例： true

发布变量

变量名称 说明
Release.AttemptNumber 此发布在此阶段中部署的次数。

示例： 1
Release.DefinitionEnvironmentId 相应发布管道中阶段的 ID。

示例： 1
Release.DefinitionId 当前发布所属的发布管道的 ID。

示例： 1
Release.DefinitionName 当前发布所属的发布管道的名称。

示例：fabrikam-cd
Release.Deployment.RequestedFor 触发（启动）当前正在进行的部署的标识的显示名称。

示例： Mateo Escobedo
Release.Deployment.RequestedForEmail 触发（启动）当前正在进行的部署的标识的电子邮件地址。

示例： mateo@fabrikam.com
Release.Deployment.RequestedForId 触发（启动）当前正在进行的部署的标识的 ID。

示例： 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID 部署的 ID。 每个作业唯一。

示例：254
Release.DeployPhaseID 运行部署的阶段的 ID。

示例：127
Release.EnvironmentId 当前正在进行部署的发布中的阶段实例的 ID。

示例：276
Release.EnvironmentName 当前正在进行部署的阶段的名称。

示例：Dev
Release.EnvironmentUri 当前正在进行部署的发布中的阶段实例的 URI。

示例：vstfs://ReleaseManagement/Environment/276
Release.Environments.{stage-name}.status 阶段的部署状态。

示例：InProgress
Release.PrimaryArtifactSourceAlias 主项目源的别名。

示例： fabrikam\_web
Release.Reason 部署的原因。 支持的值是：
ContinuousIntegration - 生成完成后，发布在持续部署中启动。
Manual - 发布已手动启动。
None - 部署原因尚未指定。
Schedule - 发布从计划开始。
Release.ReleaseDescription 发布时提供的文本说明。

示例：Critical security patch
Release.ReleaseId 当前发布记录的标识符。

示例：118
Release.ReleaseName 当前发布的名称。

示例：Release-47
Release.ReleaseUri 当前发布的 URI。

示例： vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL 此发布的 URL。

示例：https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor 触发发布的标识的显示名称。

示例： Mateo Escobedo
Release.RequestedForEmail 触发发布的标识的电子邮件地址。

示例： mateo@fabrikam.com
Release.RequestedForId 触发发布的标识的 ID。

示例： 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload 指定是否跳过将项目下载到代理的布尔值。

示例：FALSE
Release.TriggeringArtifact.Alias 触发发布的项目的别名。 手动计划或触发发布时，此为空。

示例： fabrikam\_app

发布阶段变量

变量名称 说明
Release.Environments.{stage name}.Status 指定阶段内此发布的部署状态。

示例： NotStarted

代理变量

变量名称 说明
Agent.Name 注册到代理池的代理的名称。 这很可能不同于计算机名称。

示例：fabrikam-agent
Agent.MachineName 配置代理的计算机的名称。

示例：fabrikam-agent
Agent.Version 代理软件的版本。

示例：2.109.1
Agent.JobName 正在运行的作业的名称，例如“Release”或“Build”。

示例：Release
Agent.HomeDirectory 安装代理的文件夹。 此文件夹包含代理的代码和资源。

示例：C:\agent
Agent.ReleaseDirectory 在部署发布期间将项目下载到的目录。 如果目录需要将项目下载到代理，则会在每次部署之前清除该目录。 与 System.ArtifactsDirectory 和 System.DefaultWorkingDirectory 相同。

示例：C:\agent\_work\r1\a
Agent.RootDirectory 此代理的工作目录，在其中为每个生成或发布创建子文件夹。 与 Agent.WorkFolder 和 System.WorkFolder 相同。

示例：C:\agent\_work
Agent.WorkFolder 此代理的工作目录，在其中为每个生成或发布创建子文件夹。 与 Agent.RootDirectory 和 System.WorkFolder 相同。

示例：C:\agent\_work
Agent.DeploymentGroupId 注册到部署组的代理的 ID。 这仅适用于部署组作业。

示例： 1

发布项目变量

对于发布中引用的每个项目，可以使用以下项目变量。 请注意，并非所有变量都适用于每种项目类型。 下表列出了默认项目变量，并提供了基于项目类型的值示例。 如果示例为空，则表示该变量不适用于该项目类型。

将 {alias} 占位符替换为针对项目源别名指定的值，或替换为针对发布管道生成的默认值。

变量名称 说明
Release.Artifacts.{alias}.DefinitionId 生成管道或存储库的标识符。示例：

Azure Pipelines：1
GitHub：fabrikam/asp
Release.Artifacts.{alias}.DefinitionName 生成管道或存储库的名称。示例：

Azure Pipelines：fabrikam-ci
TFVC：$/fabrikam
Git：fabrikam
GitHub：fabrikam/asp (main)
Release.Artifacts.{alias}.BuildNumber 生成号或提交标识符。示例：

Azure Pipelines：20170112.1
Jenkins：20170112.1
TFVC：Changeset 3
Git：38629c964
GitHub：38629c964
Release.Artifacts.{alias}.BuildId 生成标识符。示例：

Azure Pipelines：130
Jenkins：130
GitHub：38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts.{alias}.BuildURI 生成的 URL。示例：

Azure Pipelines：vstfs://build-release/Build/130
GitHub：https://github.com/fabrikam/asp
Release.Artifacts.{alias}.SourceBranch 从中生成源的分支的完整路径和名称。示例：

Azure Pipelines：refs/heads/main
Release.Artifacts.{alias}.SourceBranchName 从中生成源的分支的唯一名称。示例：

Azure Pipelines：main
Release.Artifacts.{alias}.SourceVersion 生成的提交。示例：

Azure Pipelines：bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts.{alias}.Repository.Provider 从中生成源的存储库的类型。示例：

Azure Pipelines：Git
Release.Artifacts.{alias}.RequestedForID 触发生成的帐户的标识符。示例：

Azure Pipelines：2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts.{alias}.RequestedFor 请求生成的帐户的名称。示例：

Azure Pipelines：Mateo Escobedo
Release.Artifacts.{alias}.Type 项目源的类型，例如“Build”。示例：

Azure Pipelines：Build
Jenkins：Jenkins
TFVC：TFVC
Git：Git
GitHub：GitHub
Release.Artifacts.{alias}.PullRequest.TargetBranch 作为拉取请求目标的分支的完整路径和名称。 仅当发布由拉取请求流触发时，才会初始化此变量。示例：

Azure Pipelines：refs/heads/main
Release.Artifacts.{alias}.PullRequest.TargetBranchName 作为拉取请求目标的分支的唯一名称。 仅当发布由拉取请求流触发时，才会初始化此变量。示例：

Azure Pipelines：main

主项目变量

在经典发布管道中，如果使用多个项目，可以将其中一个指定为主要项目。 对于指定的主要项目，Azure Pipelines 会填充以下变量。

变量名称 与以下项相同
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

使用默认变量

可以通过两种方式使用默认变量作为发布管道或脚本中任务的参数。

可以直接使用默认变量作为任务的输入。 例如，若要将 Release.Artifacts.{Artifact alias}.DefinitionName 作为参数传递给具有 ASPNET4.CI 别名的项目的 PowerShell 任务，可以使用 $(Release.Artifacts.ASPNET4.CI.DefinitionName)。

显示如何使用默认变量作为参数的屏幕截图。

若要在脚本中使用默认变量，必须先将默认变量名称中的 . 替换为 _。 例如，若要在 PowerShell 脚本中输出 ASPNET4.CI 作为其别名的项目的 Release.Artifacts.{Artifact alias}.DefinitionName 的值，请使用$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME。 请注意，原始别名 ASPNET4.CI 替换为 ASPNET4_CI。

显示如何在内联 PowerShell 脚本中使用默认变量的屏幕截图。

自定义变量

可以在各种范围内定义自定义变量。

  • 变量组：使用变量组在项目中的所有定义之间共享值。 如果要在整个项目内的定义、阶段和任务中使用相同的值，并从单个位置进行管理，这非常有用。 在管道>库中定义和管理变量组。

  • 发布管道变量：使用发布管道变量跨发布管道中的所有阶段共享值。 这非常适合需要跨阶段和任务保持一致值的场景，并且能够从单个位置进行更新。 在发布管道的变量选项卡中定义和管理这些变量。 在“管道变量”页中，添加变量时，将范围下拉列表设置为发布。

  • 阶段变量：使用阶段变量在发布管道的特定阶段共享值。 这对于不同于阶段到阶段但跨阶段的所有任务保持一致的值非常有用。 在发布管道的变量选项卡中定义和管理这些变量。 在“管道变量”页中，添加变量时，将范围下拉列表设置为适当的环境。

在项目、发布管道和阶段级别内使用自定义变量有助于：

  • 避免重复值，从而更容易通过一次更改更新所有引用。

  • 通过防止用户查看或修改敏感值来保护它们。 要将变量标记为安全（机密），请选择变量旁边的 挂锁 图标。

    重要

    隐藏（机密）变量的值安全地存储在服务器上，用户在保存后无法查看这些值。 在部署期间，Azure Pipelines 会在任务引用这些值时对其进行解密，并通过安全的 HTTPS 通道将它们传递给代理。

注意

创建自定义变量可以覆盖标准变量。 例如，如果在 Windows 代理上定义自定义 Path 变量，它将覆盖 $env:Path 变量，这可能会阻止 PowerShell 正常运行。

使用自定义变量

若要在任务中使用自定义变量，可将变量名称括在括号中，然后在前面加上 $ 字符。 例如，如果有一个名为 adminUserName 的变量，则可以将其当前值作为 $(adminUserName) 插入到任务中。

注意

来自不同组的变量链接到同一范围内的管道（例如，作业或阶段）可能会发生冲突，导致不可预测的结果。 为了避免这种情况，请确保所有变量组中的变量都有唯一的名称。

在脚本中定义和修改变量

若要定义或修改脚本中的变量，请使用 task.setvariable 日志记录命令。 更新的变量值的范围限定为正在执行的作业，并且不会跨作业或阶段持续存在。 请注意，变量名称将转换为大写，并将“.”和" "替换为“_”。

例如，Agent.WorkFolder 将变为 AGENT_WORKFOLDER。

  • 在 Windows 上，以 %AGENT_WORKFOLDER% 或 $env:AGENT_WORKFOLDER 的方式访问此变量。
  • 在 Linux 和 macOS 上，使用 $AGENT_WORKFOLDER。

提示

可以在以下计算机上运行脚本：

批处理脚本

设置 sauce 和 secret.Sauce 变量

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

读取变量

参数

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

脚本

@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)

从中读取变量的控制台输出：

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)

查看所有变量的当前值

  1. 选择“管道”>“发布”，然后选择发布管道。

  2. 打开发布的摘要视图，然后选择感兴趣的阶段。 在步骤列表中，选择“初始化作业”。

    显示初始化作业步骤的屏幕截图。

  3. 这将打开此步骤的日志。 向下滚动以查看代理对此作业使用的值。

    显示代理使用的变量的屏幕截图。

在调试模式下运行发布

在调试模式下运行发布可以通过在发布执行期间显示其他信息来帮助诊断和解决问题或故障。 可以为整个发布启用调试模式，也可以仅针对特定发布阶段中的任务启用调试模式。

  • 若要为整个发布启用调试模式，请将名为 System.Debug 的变量和值 true 添加到发布管道的变量选项卡。

  • 若要为特定阶段启用动调试模式，请从该阶段的快捷菜单中打开 配置阶段对话框，并将名为 System.Debug 且值为 true 的变量添加到变量选项卡。

  • 或者，创建一个变量组，其中包含名为 System.Debug 且值为 true 的变量，并将此变量组链接到发布管道。

提示

如果遇到与 Azure ARM 服务连接相关的错误，请参阅操作说明：排查 Azure 资源管理器服务连接问题，了解更多详细信息。

相关内容