经典版本和项目变量
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
经典发布和项目变量是在整个管道中交换和传输数据的一种便捷方式。 每个变量都存储为字符串,其值可以在管道运行之间更改。
变量不同于运行时参数,后者仅在模板分析时可用。
在编写用于将应用程序部署到 DevOps CI/CD 过程的每个阶段的任务时,变量将帮助你:
定义一次较为通用的部署管道,然后在每个阶段对其进行轻松自定义。 例如,变量可用于表示 Web 部署的连接字符串,并且此变量的值可以从一个阶段更改为另一个阶段。 这些是自定义变量。
使用有关在其中运行部署管道的特定发布、阶段、项目或代理的上下文信息。 例如,脚本可能需要访问生成的位置才能下载它,或者需要访问代理上的工作目录来创建临时文件。 这些是默认变量。
默认变量
执行上下文相关信息通过默认变量提供给运行任务。 任务和脚本可以使用这些变量来查找有关运行它们的系统、发布、阶段或代理的信息。 除 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 脚本中打印别名为 ASPNET4.CI 的项目源的项目变量 Release.Artifacts.{Artifact alias}.DefinitionName
的值,可以使用 $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME
。
请注意,项目源别名的原始名称 ASPNET4.CI
将替换为 ASPNET4_CI
。
查看所有变量的当前值
打开发布摘要的管道视图,然后选择感兴趣的阶段。 在步骤列表中,选择“初始化作业”。
这将打开此步骤的日志。 向下滚动以查看代理对此作业使用的值。
在调试模式下运行发布
通过在调试模式下运行整个发布,或仅运行单个发布阶段中的任务,在发布执行过程和日志文件中显示其他信息。 这可以帮助你解决问题和故障。
若要为整个发布启动调试模式,请将名为
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)