命名限制和慣例

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

Azure DevOps 中的大部分元件都必須遵循命名限制和慣例。 限制有助於保證一致的用戶體驗，並提供與其他應用程式的相容性。

常見的限制包括未超過名稱的字元長度、不包含特殊字元，以及維護物件集內名稱的唯一性。

重要

使用 API，而不是使用者介面 （UI），API 可讓您直接指定名稱，其中包含 UI 中可能受限的字元。

最佳做法：

• 請遵循UI限制來維持一致性，並防止非預期的問題。
• 以程式設計方式驗證名稱，並適當地處理任何特殊字元。

一般考量

本文中的長度限制會以允許的 Unicode 字元數目來測量。 Surrogate 字元是由兩個 Unicode 字元所組成，根據長度限制計算為兩個字元。 如需詳細資訊，請參閱 關於 Unicode 和字元集。

與其他操作系統檔案一樣，也不允許 ASCII 控制字元 （ASCII 1-31） 和代理組合。 如需套用至檔名之操作系統限制的一般資訊，請參閱 命名檔案、路徑和命名空間。

注意

• 如需您可以定義的項目數目限制，請參閱 工作追蹤、程式和專案限制。

系統保留名稱

避免使用系統保留名稱，例如下列範例：

• 輔助
• COM1、COM2、COM3、COM4、COM5、COM6、COM7、COM8、COM9、COM10
• CON
• DefaultCollection
• LPT1、LPT2、LPT3、LPT4、LPT5、LPT6、LPT7、LPT8、LPT9
• NUL
• PRN
• SERVER、SignalR
• Web 或 WEB

如需保留名稱的詳細資訊，請參閱 檔名、路徑和命名空間。

Azure Artifacts

通用套件必須符合下列限制。

限制類型	限制
封裝名稱	- 必須是小寫。 - 開頭和結尾必須是字母或數位。 - 必須只包含字母、數位及非連續連字元、底線或句點。
套件版本	必須是小寫，而不需建置元數據。

Azure Boards

您可以使用工作項目來擷取資訊，以規劃和追蹤您的軟體開發專案。 使用工作專案，您可以描述要完成的工作、指派工作、追蹤狀態，以及協調小組內的工作。 不同類型的工作專案，例如用戶劇本、工作、Bug 和問題，都會追蹤不同類型的資訊。 如需詳細資訊，請參閱 Azure Boards 檔。

所有工作專案追蹤物件都會與一或多個名稱相關聯。 大部分都有易記的顯示名稱，但工作項目類型和全域清單除外，這些清單與參考名稱相關聯。 易記名稱是欄位的唯一用戶可見標識碼。 使用易記名稱可確保專案集合中專案和工作項目類型的一致性。 系統會在內部使用參考名稱，而且一旦定義就無法變更它。

有數個與工作專案相關聯的專案限制，包括參考和易記名稱、功能變數名稱和附件大小。

區域和反覆項目路徑

兩個工作專案欄位[ 區域路徑 ] 和 [反復項目路徑]，提供用於群組工作的樹狀結構階層。 區域路徑會依產品、功能或功能區域將工作專案分組。 反覆項目路徑會將工作專案分組為短期衝刺、里程碑或處理這些工作項目的時段。

這些多節點欄位會使用反斜杠 \ 字元來表示樹狀結構中的節點階層。

您指派給這些字段子節點的名稱必須符合下列限制。

限制類型	限制
節點長度	不能包含超過 255 個字元。
保留名稱	- 不得只包含句點 . 或兩個句點 ..。 - 不得為系統保留的名稱，例如 PRN、COM1、COM2、COM3、COM4、COM5、COM6、COM7、COM8、COM9、COM10、LPT1、LPT1、LPT2、LPT3、LPT4、LPT5、LPT6、LPT7、LPT8、LPT9、NUL、CON 或 AUX。 如需保留名稱的詳細資訊，請參閱 檔名、路徑和命名空間。
節點的特殊字元	- 不得包含 Unicode 控制字元。 - 不得包含下列任何一個字元： \ / : * ? " < > | # $ * +。 - 不得包含本機文件系統所禁止的字元。 如需 Windows 字元限制的詳細資訊，請參閱 命名檔案、路徑和命名空間。
路徑長度	不能包含超過 4,000 個 Unicode 字元。
路徑階層深度	深度必須少於14層。

附件

附加至工作項目的檔案必須符合下列限制。

限制類型	限制
檔案大小	不得超過大小上限： - 預設大小上限：4,096 KB。 - 絕對大小上限：2 GB。

板欄和泳道名稱

您的 面板 會將待辦專案變成互動式看板，提供視覺工作流程。 隨著工作從想法到完成，您會更新面板上的專案。 每個數據行都代表工作階段，而每個卡片代表該工作階段的使用者故事（藍卡）或 Bug（紅牌）。

新增、移除或重新命名 數據 行和 泳道，以自定義面板。 數據行可跨板支援工作流程。 泳道可讓您管理不同類別的工作，作為船上的水平車道。

欄和泳道名稱必須符合下列限制。

限制類型	限制
長度	不能包含超過 256 個 Unicode 字元。
唯一性	- 資料行名稱不得與面板上的任何其他數據行名稱相同。 - 泳道名稱不得與船上的任何其他泳道名稱相同。
特殊字元	不得包含任何 Unicode 控制字元或代理字元。

欄位名稱

每個工作項目類型都包含一或多個工作專案欄位。 這些欄位會根據工作項目類型定義儲存工作項目的資訊。 每個工作專案欄位都有相關聯的欄位參考名稱。 欄位參考名稱會唯一識別每個欄位，且指派后就無法變更。 如需現用工作專案欄位的詳細資訊，請參閱 工作專案欄位索引。

工作專案域名必須符合下列限制。

限制類型	限制
長度	不能包含超過 128 個 Unicode 字元。
唯一性	- 功能變數名稱必須至少包含一個字母字元。 - 不得包含下列任何一個字元： . , ; ' : ~ \ / \ * ? " & % $ ! + = () [] {} <> - |。 - 不得包含前置或尾端空格。 - 不得包含兩個或多個連續空格。
特殊字元	組織或專案集合內必須是唯一的。 工作專案功能變數名稱的範圍是專案集合。 如果您重新命名功能變數名稱，則會變更集合中所有項目內定義的所有工作專案和 WIT。

欄位參考名稱和可移植性

工作項目類型定義語言包含欄位參考名稱的概念。 欄位參考名稱可協助您移植 Team Foundation 專案集合之間的定義，以及允許非 Microsoft 整合尋找並參考特定字段。 這些名稱是全域唯一的，就像 .NET Framework 應用程式中的命名空間是全域唯一的。

系統命名空間僅用於定義 Team Foundation 系統函式的必要所有核心系統欄位。 您無法建立自己的 System.X 字段，因為它可能會妨礙功能。

Microsoft 命名空間可用來定義工作項目追蹤欄位。 這些欄位定義於進程範本的工作項目類型定義中。

客戶和合作夥伴可以針對自定義工作項目類型建立自己的欄位命名空間。 如需默認進程範本中定義之系統欄位和欄位的描述，請參閱 工作專案欄位的索引。

重要

• 無法重新命名字段參考名稱。 例如，如果您將功能變數名稱 「Title」 變更為 「Header」，該欄位的欄位參考名稱會保持不變。 欄位的整合和內部表示應該使用字位參考名稱，而不是視域名本身而定。
• 雖然您可以建立自己的 Microsoft.X 欄位，但我們不建議這麼做，因為它可能會妨礙功能或設定功能精靈在升級後成功更新專案的能力。

功能變數名稱參考名稱的範例

下列範例顯示各種命名空間中有效的欄位參考名稱。 客戶和合作夥伴也可以定義自己的命名空間，以支援其自定義工作項目類型。

系統命名空間範例	Microsoft 命名空間範例	其他命名空間範例
System.Id、System.Title、System.CreatedBy、System.CreatedDate、System.ChangedBy、System.ChangedDate、System.State、System.Reason	Microsoft.VSTS.Build.FoundIn、Microsoft.VSTS.Common.Activity、Microsoft.VSTS.Common.Discipline、Microsoft.VSTS.Common.Priority、Microsoft.VSTS.CMMI.TaskType、Microsoft.VSTS.TCM.AutomationStatus、Microsoft.VSTS.TCM.TestSuiteType	虛構的公司 Fabrikam Fiber 可能會定義下列自定義工作專案字段： FabrikamFiber.Common.Severity、FabrikamFiber.Common.Phase、FabrikamFiber.RiskManagement.RiskType、FabrikamFiber.RiskManagement.Resolution 虛構的軟體公司 Contoso Corporation 可能會定義下列工作專案字段： Contoso.Common.BusinessPriority、Contoso.Bug.FoundInPhase、Contoso.Bug.FixInPhase

工作項目標記

工作項目標記會對應至一或兩個關鍵詞片語，以篩選工作追蹤工具，例如待辦專案、面板和查詢或定義查詢。 如需詳細資訊，請參閱 新增工作專案標籤來分類和篩選清單和面板。

標記名稱必須符合下列限制。

限制類型	限制
長度	- 不能包含超過 400 個 Unicode 字元。 - 不得為 Null 或空白。
特殊字元	- 不得包含分隔符： , 或 ;。 - 不得包含 Unicode 控制件或格式字元，例如換行字元、段落分隔符、歸位字元或其他不相符的 Surrogate 字元。
範圍	由於全域清單可在所有項目之間使用，因此不能包含專案層級定義的元素，例如專案特定的群組帳戶定義。

Azure Pipelines

Azure Pipeline 定義必須符合下列限制。

限制類型	限制
作業名稱	- 必須只包含英數位元和 '_'。 - 不得以數字開頭。 - 必須有唯一的名稱。 - 不得包含關鍵詞，例如：“deployment”。
階段名稱	- 必須只包含英數位元和 '_'。 - 不得以數字開頭。 - 不得包含關鍵詞，例如：“deployment”。
運算式	必須以 a-Z 或 _AND開頭，後面接著 a-Z、 0-9或 _。

如需詳細資訊，請參閱 Azure Pipelines 文件。

Azure Repos （Git）

每個 Azure DevOps 專案都可以包含多個 Git 存放庫。 您指派給 Git 存放庫的名稱必須符合下列限制。 若要深入瞭解，請參閱 Azure Repos Git 檔。 如需其他 Git 專案命名限制的詳細資訊，例如分支和標籤，請參閱 git check-ref-format。

重要

雖然您可以在存放庫名稱中包含空格，但我們不建議這麼做。

限制類型	限制
長度	不能包含超過 64 個 Unicode 字元。
唯一性	不得與專案中的任何其他 Git 存放庫名稱相同。
特殊字元	- 不得包含任何 Unicode 控制字元或 Surrogate 字元。 - 不得包含下列可列印字元： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得以底線 _開頭。 - 不得以句號 .開頭或結尾。 - 不得為 系統保留名稱。

Azure Repos （TFVC）

Team Foundation 版本控制 （TFVC） 提供檔案的中央存放庫，以及跨小組管理這些檔案所需的命令。 它也提供可自定義的簽入原則、分支、合併、擱置和其他許多功能。 若要深入瞭解，請參閱 Azure Repos TFVC 檔

版本控制路徑必須符合下列限制。 另 請參閱優化您的工作區。

限制類型	限制
伺服器原始檔控制資料夾路徑長度	- 不能針對單一資料夾或檔名包含超過 259 個字元的 Unicode 字元。 - 不得包含超過 388 個目錄的 Unicode 字元。 - 不能包含合併目錄和檔名超過 399 個 Unicode 字元。
本機資料夾路徑長度	- 不得包含超過 248 個目錄的 Unicode 字元。 - 不能包含合併目錄和檔名超過 260 個字元的 Unicode 字元。
入口網站和 REST 特定的長度限制	合併專案名稱、目錄和檔名的 Unicode 字元不能超過 215 個字元。

在入口網站和 REST API 中，某些作業的路徑長度比 Visual Studio 和TF.exe客戶端還要嚴格。 這些作業包括 [編輯]、[重新命名] 和 [刪除]，而且是因為Web入口網站/REST會在擱置變更時，使用隨機產生的工作區進行並行處理。

TFVC 檔案

版本控制系統會儲存許多不同類型的檔案。 在您的開發計算機上 設定 Team Foundation 版本控制，提供如何新增現有 Visual Studio 專案或解決方案的詳細數據。

您新增至 Team Foundation 版本控制的檔案和資料夾必須符合下列限制。

限制類型	限制
檔案和資料夾	- 名稱不得包含下列可列印字元： \ / : * ? " < > ;。 - 資料夾不得位於使用中工作區的對應目錄之外。
檔案名稱	- 不得以 開頭 $。 - 不得包含下列可列印字元： \ / : * ? " < > ; |。

TFVC 標籤

在 Team Foundation 版本控制 （TFVC） 中，標籤是套用至特定修訂集的名稱。 您可以將標籤附加至版本控制中的一組不相關的檔案，這可讓您擷取檔案，或將其作為群組採取行動。 下表描述標籤名稱的限制。

限制類型	限制
長度	不能包含超過 64 個 Unicode 字元。
特殊字元	- 不能以空格 ( ) 或句號 .結尾。 - 不得包含下列可列印字元： \ / : * ? " < > ; @ |。

TFVC 擱置集

擱置集可讓您暫時擱置一批擱置的變更，然後作為選項，從工作區中移除擱置中的變更。 稍後，您可以將擱置集中的變更還原到您的工作區，或將它們放入其他使用者的工作區。

擱置集名稱必須符合下列限制。

限制類型	限制
長度	不能包含超過 64 個 Unicode 字元。
特殊字元	不得包含下列可列印字元： \ / : * ? " < > & ; |。

TFVC 工作區

工作區是 Team Foundation 版本控制 （TFVC） 中檔案和資料夾的客戶端複本。 當您建立多個工作區時，您可以在用戶端電腦上擁有相同版本控制資料夾的不同版本。 建立和使用工作區可提供 更多詳細數據。

工作區名稱必須符合下列限制。

限制類型	限制
長度	不能包含超過 64 個 Unicode 字元。
特殊字元	- 不得以空格 ( )結尾。 - 不得包含下列可列印字元： \ / : * ? " < > ; |。

組織名稱

重要

當您建立組織名稱時，請遵循下列指導方針。

• 僅使用英文字母中的字母
• 以字母或數字啟動您的組織名稱
• 在初始字元後面使用字母、數位或連字元
• 確定您的組織不超過 50 個 Unicode 字元
• 以字母或數字結尾

如果您使用任何不允許的字元，您會收到下列錯誤訊息：VS850015：不允許使用指定的名稱：{組織名稱}。

進程和進程範本

程式會定義工作專案追蹤系統和其他子系統的建置組塊，而您在聯機至項目之後可以存取這些子系統。

注意

術語：「行程」和「程式範本」都是指用來建立專案的相依性檔案集。 如需詳細資訊，請參閱 關於進程和進程範本，其中說明三個默認進程之間的差異。

您定義或自訂的程式必須符合下列限制。

限制類型	限制
長度	不能包含超過 256 個 Unicode 字元。
唯一性	- 在 Azure DevOps 中必須是唯一的。 - 如果您上傳與現有範本同名的範本，則會覆寫現有的範本。
處理範本檔案大小	不得超過 2 GB（GB）。

專案名稱

專案會建立原始程式碼的存放庫，以及小組規劃、追蹤進度和共同作業的位置。 專案的名稱是用來將小組成員連線至專案的 連接字串 的一部分。

您指派給所建立項目的名稱必須符合下列限制。

限制類型	限制
長度	不能包含超過 64 個 Unicode 字元。
唯一性	不得與專案集合中的任何其他名稱、支援集合的 SharePoint Web 應用程式，或支援集合的 SQL Server Reporting Services 實例相同。
保留名稱	- 不得為 系統保留名稱。 - 不得為 IIS 要求篩選使用的其中一個隱藏區段，例如App_Browsers、App_code、App_Data、App_GlobalResources、App_LocalResources、App_Themes、App_WebResources、bin 或 web.config。
特殊字元	- 不得包含任何 Unicode 控制字元或 Surrogate 字元。 - 不得包含下列可列印字元： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得以底線 _開頭。 - 不得以句號 .開頭或結尾。

安全性群組

透過 Azure DevOps 安全組，您可以將特定許可權或許可權套用至一組使用者。

內部部署群組可能包含 Active Directory 組帳戶、Azure DevOps 安全組、Windows 使用者帳戶、Windows 群組帳戶或任何這些類型的混合。 如需詳細資訊，請參閱 將 Active Directory /Microsoft Entra 使用者或群組新增至內建安全組。

安全組必須符合下列限制。

限制類型	限制
安全組帳戶名稱長度	不能包含超過 256 個 Unicode 字元。
唯一性	- 專案層級的組帳戶不得與相同專案中的任何其他組名相符。 - 集合層級的組帳戶不得符合專案集合中群組帳戶的任何其他名稱。
保留組名	不得以專案或伺服器層級的$NAMESPACE命名。
特殊字元	- 不得包含任何 Unicode 控制字元或 Surrogate 字元。 - 不得包含下列可列印字元： / \ [ ] : < > + = ; ? * |。 - 不得在 ASCII 值範圍 1-31 中包含不可列印的字元。 - 不得以句號 .結束。 - 不得包含逗號 ,。

小組名稱

小組名稱會識別一組個人或群組，這些群組會共同合作為專案中的小組。 小組成員使用此名稱來連線到小組，或查詢針對為小組定義的成員進行查詢。

小組名稱必須符合允許轉譯為有效 URL 一部分的慣例。 每個小組名稱在單一專案中都必須是唯一的。 不過，在專案集合內的不同專案中，使用相同小組名稱沒有任何限制。 如需詳細資訊，請參閱 新增另一個小組或小組階層。

小組名稱必須符合下列限制。

限制類型	限制
長度	不能包含超過 64 個 Unicode 字元。
唯一性	不得與專案中的任何其他名稱相同。
保留名稱	不得為 系統保留名稱。
特殊字元	- 不得包含任何 Unicode 控制字元或 Surrogate 字元。 - 不得包含下列可列印字元： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得包含省略號 ... 或雙句點 ..。 - 不得以底線 _開頭。 - 不得以句號 .開頭或結尾。

用戶帳戶名稱

用戶帳戶會識別新增至專案或專案集合的人員。 用戶帳戶可能會對應至 Active Directory、Microsoft Entra ID、Windows 伺服器群組內的專案。

您新增至組織或集合的用戶帳戶必須符合下列限制。 若要將使用者帳戶新增至專案，請參閱 將使用者新增至專案或小組。

限制類型	限制
帳戶名稱長度	不能包含超過 256 個 Unicode 字元。
唯一性	不得符合新增至專案集合的任何其他用戶帳戶。
保留組名	不得以 $NAMESPACE 項目或伺服器層級的 來命名 。
特殊字元	- 不得包含下列可列印字元： "/ \ [ ] : < > + = ; ? * |。 - 不得在 ASCII 值範圍 1-31 中包含不可列印的字元。 - 不得以句號 . 或美元符號 $結尾。 - 不得包含逗號 ,。 - 不得包含下列 Unicode 類別：LineSeparator、ParagraphSeparator、Control、Format、OtherNotAssigned。

Wiki 頁面和檔名

每個 Wiki 頁面會對應至 Wiki Git 存放庫中的檔案。 您指派給網頁標題的名稱必須符合下列限制。

限制類型	限制
檔案名稱	完整頁面路徑應不超過 235 個字元。
唯一性	網頁標題會區分大小寫，且在 Wiki 階層中必須為唯一。
特殊字元	- 不得包含任何 Unicode 控制字元或 Surrogate 字元。 - 不得包含下列可列印字元： / \ #。 - 不得以句號 .開頭或結尾。
檔案大小	不得超過 18 MB 的上限。
附件檔案大小	不得超過 19 MB 的上限。

Wiki 頁面標題中的特殊字元

您可以指定包含一或多個這些特殊字元 : < > * ? | -的頁面標題。 例如，您可以將 Markdown 檔案命名為「常見問題」或「設定指南」。 這些字元具有下列 URI 編碼字串：

字元	編碼字串
:	%3A
<	%3C
>	%3E
*	%2A
?	%3F
|	%7C
-	%2D
"	22%

相關文章

• Azure Artifacts 計數和大小限制
• 工作追蹤、處理序和專案限制
• 自訂工作追蹤物件以支援小組的程式
• 自定義程式範本