经典版本和项目变量

  • 项目

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

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

变量不同于运行时参数，后者仅在模板分析时可用。

在编写用于将应用程序部署到 DevOps CI/CD 过程的每个阶段的任务时，变量将帮助你：

  • 定义一次较为通用的部署管道，然后在每个阶段对其进行轻松自定义。 例如，变量可用于表示 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。 在脚本或任务中使用它来调用其他服务（如生成和版本控制）上的 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-stage

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

示例： NotStarted

Agent

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

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

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

示例：2.109.1
Agent.JobName 正在运行的作业的名称，例如“发布”或“生成”。

示例：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/TeamCity 示例：20170112.1
TFVC 示例：Changeset 3
Git 示例：38629c964
GitHub 示例：38629c964
Release.Artifacts.{alias}.BuildId 生成标识符。

Azure Pipelines 示例：130
Jenkins/TeamCity 示例：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 项目源的类型，例如“生成”。

Azure Pipelines 示例：Build
Jenkins 示例：Jenkins
TeamCity 示例：TeamCity
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
生成类型 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

使用默认变量

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

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

使用 PowerShell 脚本任务的自变量中的项目变量

若要在脚本中使用默认变量，必须先将默认变量名称中的 . 替换为 _。 例如，若要在 PowerShell 脚本中打印别名为 ASPNET4.CI 的项目源的项目变量 Release.Artifacts.{Artifact alias}.DefinitionName 的值，可以使用 $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME。

使用内联 PowerShell 脚本中的项目变量

请注意，项目源别名的原始名称 ASPNET4.CI 将替换为 ASPNET4_CI。

查看所有变量的当前值

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

    打开发布日志

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

    查看发布中的变量值

在调试模式下运行发布

通过在调试模式下运行整个发布，或仅运行单个发布阶段中的任务，在发布执行过程和日志文件中显示其他信息。 这可以帮助你解决问题和故障。

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

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

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

提示

如果收到与 Azure RM 服务连接相关的错误，请参阅如何：排查 Azure 资源管理器服务连接问题。

自定义变量

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

  • 使用变量组在项目中的所有定义之间共享值。 如果需要在项目中的所有定义、阶段和任务中使用相同的值，并且希望能够在单个位置更改这些值，请选择变量组。 在“库”选项卡中定义和管理变量组。

  • 使用“发布管道变量”在所有阶段之间共享值。 如果需要在发布管道的所有阶段和任务中使用相同的值，并且希望能够在单个位置更改该值，请选择发布管道变量。 在发布管道的“变量”选项卡中定义和管理这些变量。 在“管道变量”页中，打开“范围”下拉列表，然后选择“发布”。 默认情况下，添加变量时，该变量设置为“发布范围”。

  • 使用阶段变量在一个特定阶段内的所有任务之间共享值。 对因阶段而异的值使用阶段级变量（对于阶段中的所有任务都是相同的）。 在发布管道的“变量”选项卡中定义和管理这些变量。 在“管道变量”页中，打开“范围”下拉列表，然后选择所需阶段。 添加变量时，将“范围”设置为适当的环境。

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

  • 避免重复值，以便更轻松地将所有匹配项更新为一个操作。

  • 以发布管道用户无法查看或更改的方式存储敏感值。 通过选择变量旁边的挂锁（挂锁）图标，将配置属性指定为安全（机密）变量。

    重要

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

注意

创建自定义变量可以覆盖标准变量。 例如，PowerShell Path 环境变量。 如果在 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)