经典发布和项目变量

项目
08/06/2022

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

注意

在 Microsoft Team Foundation Server (TFS) 2018 和更低版本中，生成和发布管道被称为“定义”，运行被称为“生成”，服务连接被称为“服务终结点”，阶段被称为“环境”，而作业被称为“阶段” 。

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

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

注意

这是一篇介绍经典发布和项目变量的参考文章。若要了解 YAML 管道中的变量，请参阅用户定义的变量。从发布管道迁移到 YAML 管道时， Release.* 不会填充变量。

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

定义一次更通用的部署管道，然后轻松为每个阶段自定义它。例如，变量可用于表示 Web 部署的连接字符串，并且此变量的值可以从一个阶段更改为另一个阶段。这些是 自定义变量。
使用有关运行部署管道的特定发布、阶段、项目或代理的上下文的信息。例如，脚本可能需要访问生成的位置以下载它，或者访问代理上的工作目录来创建临时文件。这些是 默认变量。

提示

可以查看发布的所有变量的当前值，并使用默认变量在调试模式下运行发布。

默认变量

有关执行上下文的信息可用于通过默认变量运行任务。任务和脚本可以使用这些变量查找有关它们在其中运行的系统、发布、阶段或代理的信息。除了 System.Debug 之外，这些变量是只读的，并且它们的值由系统自动设置。下表描述了一些最重要的变量。若要查看完整列表，请参阅查看所有变量的当前值。

系统

变量名称	说明
System.TeamFoundationServerUri	TFS 或 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。 TFS 2015 中不可用。示例：`6c6f3423-1c84-4625-995a-f7f143a1e43d`
System.DefinitionId	当前版本所属的发布管道的 ID。 TFS 2015 中不可用。示例：`1`
System.TeamProject	此生成或发布所属的项目的名称。示例：`Fabrikam`
System.TeamProjectId	此生成或发布所属的项目 ID。 TFS 2015 中不可用。示例：`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	此版本在此阶段部署的次数。 TFS 2015 中不可用。示例：`1`
Release.DefinitionEnvironmentId	相应发布管道中阶段的 ID。 TFS 2015 中不可用。示例：`1`
Release.DefinitionId	当前版本所属的发布管道的 ID。 TFS 2015 中不可用。示例：`1`
Release.DefinitionName	当前发布所属的发布管道的名称。示例：`fabrikam-cd`
Release.Deployment.RequestedFor	触发 (的标识的显示名称在当前正在进行的部署) 启动。 TFS 2015 中不可用。示例：`Mateo Escobedo`
Release.Deployment.RequestedForEmail	触发 (的标识的电子邮件地址) 当前正在进行的部署。 TFS 2015 中不可用。示例：`mateo@fabrikam.com`
Release.Deployment.RequestedForId	触发 (的标识的 ID) 当前正在进行中的部署。 TFS 2015 中不可用。示例：`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。{阶段名称}。地位	此版本在指定阶段内部署的状态。 TFS 2015 中不可用。示例：`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。这仅适用于部署组作业。 TFS 2018 Update 1 中不可用。示例：`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}。类型	项目源的类型，例如生成。 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。{主项目别名}。DefinitionId
Build.DefinitionName	Release.Artifacts。{主项目别名}。DefinitionName
Build.BuildNumber	Release.Artifacts。{主项目别名}。BuildNumber
Build.BuildId	Release.Artifacts。{主项目别名}。BuildId
Build.BuildURI	Release.Artifacts。{主项目别名}。BuildURI
Build.SourceBranch	Release.Artifacts。{主项目别名}。SourceBranch
Build.SourceBranchName	Release.Artifacts。{主项目别名}。SourceBranchName
Build.SourceVersion	Release.Artifacts。{主项目别名}。SourceVersion
Build.Repository.Provider	Release.Artifacts。{主项目别名}。Repository.Provider
Build.RequestedForID	Release.Artifacts。{主要项目别名}。RequestedForID
Build.RequestedFor	Release.Artifacts。{主要项目别名}。RequestedFor
Build.Type	Release.Artifacts。{主要项目别名}。类型
Build.PullRequest.TargetBranch	Release.Artifacts。{主要项目别名}。PullRequest.TargetBranch
Build.PullRequest.TargetBranchName	Release.Artifacts。{主要项目别名}。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替换。

查看所有变量的当前值

打开发布摘要的管道视图，然后选择感兴趣的阶段。在步骤列表中，选择 “初始化作业”。
这将打开此步骤的日志。向下滚动以查看代理为此作业使用的值。

在调试模式下运行发布

在发布执行时显示其他信息，并在日志文件中通过运行整个版本，或仅以调试模式在单个发布阶段执行任务。这有助于解决问题和故障。

若要为整个版本启动调试模式，请将具有值true命名System.Debug的变量添加到发布管道的“变量”选项卡。
若要启动单个阶段的调试模式，请从阶段的快捷菜单中打开 “配置阶段 ”对话框，并将名为 System.Debug “变量”的 true 变量添加到 “变量 ”选项卡。
或者，创建包含具有值true命名System.Debug的变量的变量组，并将此变量组链接到发布管道。

提示

如果收到与 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。

提示

可以在以下项上运行脚本：

使用 Batch 脚本任务或 PowerShell 脚本任务的 Windows 代理。
使用 Shell 脚本任务进行 macOS 或 Linux 代理。

批处理脚本

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)

PowerShell 脚本

sauce设置和secret.Sauce变量

Write-Host "##vso[task.setvariable variable=sauce]crushed tomatoes"
Write-Host "##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with
            garlic"

读取变量

参数

-sauceArgument "$(sauce)" -secretSauceArgument "$(secret.Sauce)"

脚本

Param(
   [string]$sauceArgument,
   [string]$secretSauceArgument
)
Write-Host No problem reading $env:SAUCE or $sauceArgument
Write-Host But I cannot read $env:SECRET_SAUCE
Write-Host But I can read $secretSauceArgument "(but the log is redacted so I do not
           spoil the secret)"

sauce设置和secret.Sauce变量

#!/bin/bash
echo "##vso[task.setvariable variable=sauce]crushed tomatoes"
echo "##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic"

读取变量

参数

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

脚本

#!/bin/bash
echo "No problem reading $SAUCE"
echo "But I cannot read $SECRET_SAUCE"

读取变量的控制台输出：

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)