運行和版本編號

發行項
2025-03-29

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

本文說明如何建構 Azure Pipelines 建置編號和執行編號，以及如何在管線中自定義它們。

執行編號可用來識別管線或組建的特定執行。組建編號與執行編號同義。

如果您在 YAML 管線中未指定組建名稱，或是將經典管線中的名稱欄位保留為空白，則您的執行會取得一個唯一的整數作為其名稱。您可以給運行賦予對您的團隊更有意義的名稱。您可以在組建名稱中使用標記、變數和底線字元的組合。

在 YAML 管線中，會呼叫 name 組建名稱屬性，而且必須位於管線的根層級。 YAML 檔案根層級所指定的項目是管線屬性。

注意

屬性 name 不適用於範本檔案。

下列範例程式代碼會輸出自定義的組建編號，例如 project_def_master_202408281。

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.31.1.$(Rev:r)，則下一個組建編號為 1.1.1。

範例

在進行組建運行時，請考慮以下數據：

項目名稱：Fabrikam
管線名稱：CIBuild
分支: main
組建標識碼/執行標識碼：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)` 是內部且不可變的標識碼，也稱為「執行標識符」，在 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的數字以01、02等開始，請指定$(Rev:rr)。

如果您在版本編號方案中使用零填補 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)

定義變數

共用方式為