运行和生成编号

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

本文介绍如何构造 Azure Pipelines 内部版本号和运行编号，以及如何在管道中自定义它们。

运行编号用于标识管道或生成的特定执行。 内部版本号是运行编号的同义词。

如果未在 YAML 管道中指定生成名称，或者在经典管道中将 Name 字段留空，则运行将获取一个唯一的整数作为其名称。 你可以为运行提供对团队有意义的更有用的名称。 可以在生成名称中使用标记、变量和下划线字符的组合。

在 YAML 管道中，调用 name 生成名称属性，并且必须位于管道的根级别。 在 YAML 文件的根级别指定的项目是管道属性。

注意

属性 name 在模板文件中不起作用。

以下示例代码输出自定义的内部版本号，如 project_def_master_20240828.1。

name: $(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r)

steps:
  - script: echo '$(Build.BuildNumber)'

运行次数

Azure Pipelines 中运行编号的默认值为 $(Date:yyyyMMdd).$(Rev:r)。 $(Rev:r) 是一种仅在生成号字段中工作的特殊变量格式。 生成完成后，如果内部版本号中没有其他任何更改，整数 Rev 值将增加一个。

$(Rev:r)1在内部版本号的任何其他部分发生更改时重置。 例如，如果将内部版本号格式配置为 $(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r)，则生成号将在日期更改时重置。

如果以前的内部版本号为 MyBuild_20230621.1，则当天的下一个内部版本号为 MyBuild_20230621.2。 第二天的第一个内部版本号是 MyBuild_20230622.1。

$(Rev:r) 如果更改内部版本号以指示版本更改，则也会重置 1 为< 例如，如果生成格式为 1.0.$(Rev:r) 和最后一个内部版本号 1.0.3，如果将内部版本号更改为，则下一个内部版本号 1.1.$(Rev:r)为 1.1.1。

示例

请考虑以下用于生成运行的数据：

• 项目名称：Fabrikam
• 管道名称：CIBuild
• 分支：main
• 生成 ID/运行 ID：752
• 日期：2024 年 5 月 6 日
• 时间：晚上 9：07：03
• 今天早些时候完成了一次运行。

如果指定以下内部版本号格式，则 2024 年 5 月 6 日的第二个运行命名 为 Fabrikam_CIBuild_main_20240506.2。

$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:.r)

令牌

下表显示了每个令牌如何根据前面的示例解析。 只能使用这些令牌来定义运行编号。 它们在管道中的其他任何位置都不起作用。

令牌	示例值	备注
$(Build.DefinitionName)	CIBuild	管道名称不能包含无效或空格字符。
$(Build.BuildId)	752	$(Build.BuildId) 是一个内部不可变 ID，也称为“运行 ID”，在 Azure DevOps 组织中是唯一的。
$(DayOfMonth)	6
$(DayOfYear)	126
$(Hours)	21
$(Minutes)	7
$(Month)	5
$(Rev:r)	2	第三次每日运行是 3等。 用于 $(Rev:r) 确保每个已完成的生成都具有唯一的名称。
$(Date:yyyyMMdd)	20240506	可以指定其他日期格式，例如 $(Date:MMddyy)。
$(Seconds)	3
$(SourceBranchName)	主要
$(TeamProject)	Fabrikam
$(Year:yy)	24
$(Year:yyyy)	2024

重要

如果要在运行编号中显示前缀零，可以向令牌添加更多 r 字符 Rev 。 例如，指定 $(Rev:rr) 是否希望 Rev 数字以 01开头 02，等等。

如果使用零填充 Rev 作为版本号方案的一部分，请注意，某些管道任务或常用工具（如 NuGet 包）会删除前导零。 此行为会导致生成的项目中的版本号不匹配。

表达式

如果使用表达式设置生成号，则无法使用某些标记，因为在计算表达式时未设置这些标记的值。 这些令牌包括 $(Build.BuildId)、$(Build.BuildURL) 和 $(Build.BuildNumber)。

变量

可以在内部版本号中使用用户定义的和预定义变量。 例如，如果定义 My.Variable，可以指定以下数字格式：

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)

在前面的示例中，前四个变量是预定义的。 有关如何定义用户变量的信息，请参阅 在管道中设置变量。

常见问题解答

运行编号的大小以及可以使用哪些字符？

运行编号最多可以包含 255 个字符。 不能使用字符"、/、、:、<>'、、|、?、或@*，不能以数字结尾。.

生成号时间值以何种时区表示？

时区为 UTC。

如何使用条件动态设置生成号？

可以使用变量作为运行号的一部分。 在下面的示例中，变量 why 用作运行编号的一部分，其值会根据该变量的变化 Build.Reason而变化。

variables:
  - name: why
    ${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
      value: pr
    ${{ elseif eq(variables['Build.Reason'], 'Manual' ) }}:
      value: manual
    ${{ elseif eq(variables['Build.Reason'], 'IndividualCI' ) }}:
      value: indivci
    ${{ else }}:
      value: other

name: $(TeamProject)_$(SourceBranchName)_$(why)_$(Date:yyyyMMdd).$(Rev:.r)

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo '$(Build.BuildNumber)'

如何在脚本中引用运行编号变量？

可以定义包含运行编号的新变量，或直接调用运行编号。 在以下示例中， $(MyRunNumber) 是包含运行编号的新变量。 可以使用 MyRunNumber 或 $(Build.BuildNumber).

# Set MyRunNumber
variables: 
  MyRunNumber: '1.0.0-CI+$(Build.BuildNumber)'

steps:
- script: echo $(MyRunNumber)
- script: echo $(Build.BuildNumber)

相关内容

定义变量