命名限制和约定

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

Azure DevOps 中的大多数组件必须遵循命名限制和约定。 限制有助于保证一致的用户体验，并提供与其他应用程序的兼容性。

常见限制包括不超过名称的字符长度、不包含特殊字符以及保持对象集中名称的唯一性。

重要

使用 API 而不是用户界面（UI）时，API 允许你直接指定名称，其中包括可能在 UI 中限制的字符。

最佳做法：

• 遵循 UI 限制来保持一致性并防止意外问题。
• 以编程方式验证名称并适当处理任何特殊字符。

一般注意事项

本文中的长度限制由允许的 Unicode 字符数来衡量。 代理字符由两个 Unicode 字符组成，根据长度限制计算为两个字符。 有关详细信息，请参阅 关于 Unicode 和字符集。

与其他操作系统文件一样，也不允许使用 ASCII 控制字符（ASCII 1-31）和代理项组合。 有关应用于文件名的操作系统限制的一般信息，请参阅 命名文件、路径和命名空间。

注意

• 有关可定义的项数的限制，请参阅 “工作跟踪”、“流程”和“项目限制”。

系统保留名称

避免使用系统保留名称，如以下示例所示：

• AUX
• 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、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 控件或格式字符，如换行符、段落分隔符、回车符或其他不匹配的代理项字符。
范围	由于全局列表在所有项目中都可用，因此它们不得包含项目级别定义的元素，例如特定于项目的组帐户定义。

Azure Pipelines

Azure Pipeline 定义必须符合以下限制。

限制类型	限制
作业名称	- 只能包含字母数字字符和 '_'。 - 不得以数字开头。 - 必须具有唯一的名称。 - 不得包含关键字，例如：“deployment”。
阶段名称	- 只能包含字母数字字符和 '_'。 - 不得以数字开头。 - 不得包含关键字，例如：“deployment”。
表达式	必须以a-Z或后跟a-Z0-9，或__AND。

有关详细信息，请参阅 Azure Pipelines 文档。

Azure Repos (Git)

每个 Azure DevOps 项目可以包含多个 Git 存储库。 分配给 Git 存储库的名称必须符合以下限制。 有关详细信息，请参阅 Azure Repos Git 文档。 有关其他 Git 项（如分支和标记）的命名限制的详细信息，请参阅 git check-ref-format。

重要

尽管可以在存储库名称中包含空格，但我们不建议这样做。

限制类型	限制
长度	不能包含超过 64 个 Unicode 字符。
唯一性	不能与项目中的任何其他 Git 存储库名称相同。
特殊字符	- 不能包含任何 Unicode 控制字符或代理项字符。 - 不得包含以下可打印字符： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得以下划线 _开头。 - 不得以句点 .开头或结尾。 - 不得为 系统保留名称。

Azure Repos (TFVC)

Team Foundation 版本控制（TFVC）为文件和跨团队管理这些文件所需的命令提供中央存储库。 它还提供可自定义的签入策略、分支、合并、搁置和其他许多功能。 有关详细信息，请参阅 Azure Repos TFVC 文档

版本控制路径必须符合以下限制。 另 请参阅“优化工作区”。

限制类型	限制
服务器源代码管理文件夹路径长度	- 不能包含单个文件夹或文件名的 259 个以上的 Unicode 字符。 - 不能包含目录的 388 个以上的 Unicode 字符。 - 不能包含合并目录和文件名的 399 个以上的 Unicode 字符。
本地文件夹路径长度	- 不能包含目录的 248 个以上的 Unicode 字符。 - 不能包含组合目录和文件名的 260 个以上的 Unicode 字符。
Web 门户和特定于 REST 的长度限制	对于合并的项目名称、目录和文件名，不能包含超过 215 个 Unicode 字符。

在 Web 门户和 REST API 中，某些操作的路径长度比 Visual Studio 更严格，TF.exe客户端。 这些操作包括“编辑”、“重命名”和“删除”，因为 Web 门户/REST 在等待更改时使用随机生成的工作区进行并发。

TFVC 文件

版本控制系统存储许多不同类型的文件。 在开发计算机上 设置 Team Foundation 版本控制提供了有关如何添加现有 Visual Studio 项目或解决方案的详细信息。

添加到 Team Foundation 版本控制的文件和文件夹必须符合以下限制。

限制类型	限制
文件和文件夹	- 名称不能包含以下可打印字符： \ / : * ? " < > ; - 文件夹不得在活动工作区的映射目录之外。
文件名	- 不得以 a $. - 不得包含以下可打印字符： \ / : * ? " < > ; |。

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 控制字符或代理项字符。 - 不得包含以下可打印字符： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得以下划线 _开头。 - 不得以句点 .开头或结尾。

安全组

使用 Azure DevOps 安全组，可以向一组用户应用某些权限或权限。

本地组可能包含 Active Directory 组帐户、Azure DevOps 安全组、Windows 用户帐户、Windows 组帐户或任何这些类型的混合体。 有关详细信息，请参阅 将 Active Directory/Microsoft Entra 用户或组添加到内置安全组。

安全组必须符合以下限制。

限制类型	限制
安全组帐户名称长度	不能包含超过 256 个 Unicode 字符。
唯一性	- 项目级组帐户不能与同一项目中的任何其他组名称匹配。 - 集合级组帐户必须与项目集合中组帐户的任何其他名称不匹配。
保留组名称	不得在项目或服务器级别使用$NAMESPACE进行命名。
特殊字符	- 不能包含任何 Unicode 控制字符或代理项字符。 - 不得包含以下可打印字符： / \ [ ] : < > + = ; ? * |。 - 不得在 ASCII 值范围 1-31 中包含不可打印字符。 - 不得在一段时间内 .结束。 - 不得包含逗号 ,。

团队名称

团队名称标识一组个人或组，这些个人或组共同协作作为项目中的团队。 团队成员使用此名称连接到团队，或针对为团队定义的成员进行查询。

团队名称必须符合允许将它们呈现为有效 URL 的一部分的约定。 每个团队名称在单个项目中必须是唯一的。 但是，在项目集合中的不同项目中使用相同的团队名称没有任何限制。 有关详细信息，请参阅 添加另一个团队或团队层次结构。

团队名称必须符合以下限制。

限制类型	限制
长度	不能包含超过 64 个 Unicode 字符。
唯一性	不能与项目中的任何其他名称相同。
保留名称	不得为 系统保留名称。
特殊字符	- 不能包含任何 Unicode 控制字符或代理项字符。 - 不得包含以下可打印字符： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得包含省略号 ... 或双句点 ..。 - 不得以下划线 _开头。 - 不得以句点 .开头或结尾。

用户帐户名称

用户帐户标识添加到项目或项目集合的人员。 用户帐户可能与 Active Directory 中的条目相对应，Microsoft Entra ID、Windows 服务器组。

添加到组织或集合的用户帐户必须符合以下限制。 若要将用户帐户添加到项目，请参阅 将用户添加到项目或团队。

限制类型	限制
帐户名称长度	不能包含超过 256 个 Unicode 字符。
唯一性	必须与添加到项目集合的任何其他用户帐户不匹配。
保留组名称	不得在项目或服务器级别使用 a $NAMESPACE 命名。
特殊字符	- 不得包含以下可打印字符： "/ \ [ ] : < > + = ; ? * |。 - 不得在 ASCII 值范围 1-31 中包含不可打印字符。 - 不得以句点 . 或美元符号 $结束。 - 不得包含逗号 ,。 - 不得包含以下 Unicode 类别：LineSeparator、ParagraphSeparator、Control、Format、OtherNotAssigned。

Wiki 页面和文件名

每个 Wiki 页面对应于 Wiki Git 存储库中的一个文件。 分配给 Wiki 页面标题的名称必须符合以下限制。

限制类型	限制
文件名	完全限定的页面路径不应超过 235 个字符。
唯一性	页面标题区分大小写，在 Wiki 层次结构中必须是唯一的。
特殊字符	- 不得包含任何 Unicode 控制字符或代理字符。 - 不得包含以下可打印字符： / \ #。 - 不得以句点 .开头或结尾。
文件大小	不得超过最大 18 MB。
附件文件大小	不得超过最大 19 MB。

Wiki 页面标题中的特殊字符

可以指定包含一个或多个这些特殊字符 : < > * ? | -的页面标题。 例如，可以将 Markdown 文件命名为“FAQ？”或“设置指南”。 这些字符具有以下 URI 编码字符串：

字符	编码字符串
:	%3A
<	%3C
>	%3E
*	%2A
?	%3F
|	%7C
-	%2D
"	%22

相关文章

• Azure Artifacts 计数和大小限制
• 工作跟踪、进程和项目限制
• 自定义工作跟踪对象以支持团队的过程
• 自定义过程模板