命名限制和约定

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

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

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

备注

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

一般注意事项

本文中的长度限制由允许的 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 级。

Attachments

附加到工作项的文件必须符合以下限制。

限制类型	限制
文件大小	不得超过最大大小： - 默认最大大小：4，096 KB。 - 绝对最大大小：2 GB。

板列和泳道名称

看板将积压工作转换为交互式招牌，提供可视工作流。 随着工作从创意阶段进行到完成，你将更新面板上的项。 每一列代表一个工作阶段，每张卡片代表该工作阶段的一个用户故事（蓝色卡片）或 bug（红色卡片）。

通过添加、删除或重命名 列 和 泳道来自定义看板。 列支持全面工作流。 泳道允许你管理不同类别的工作，作为板上的水平通道。

列和泳道名称必须符合以下限制。

限制类型	限制
长度	不能超过 256 个 Unicode 字符。
唯一性	- 列名称不得与看板上的任何其他列名相同。 - 泳道名称不得与看板上的任何其他泳道名称相同。
特殊字符	不能包含任何 Unicode 控制字符或代理项字符。

字段名

每个工作项类型包含一个或多个工作项字段。 这些字段根据工作项类型定义为工作项存储的信息。 每个工作项字段都有一个关联的字段引用名称。 字段引用名称唯一标识每个字段，分配后无法更改。 有关现成的工作项字段的详细信息，请参阅 工作项字段索引。

工作项字段名称必须符合以下限制。

限制类型	限制
长度	不能包含超过 128 个 Unicode 字符。
唯一性	- 字段名称必须至少包含一个字母字符。 - 不得包含以下任何一个字符： .,;':~\/\*|?"&%$!+=()[]{}<>-。 - 不得包含前导空格或尾随空格。 - 不得包含两个或多个连续空格。
特殊字符	在组织或项目集合中必须是唯一的。 工作项字段名称的范围限定为项目集合。 如果重命名字段名称，将针对集合中所有项目内定义的所有工作项和 WIT 对其进行更改。

字段引用名称和可移植性

工作项类型定义语言包括 字段引用名称的概念。 字段引用名称有助于在 Team Foundation 项目集合之间移植定义，并允许第三方集成查找和引用特定字段。 这些名称是全局唯一的，正如 .NET Framework 应用程序中的命名空间是全局唯一的一样。

System 命名空间仅用于定义 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

工作项标记

工作项标记对应于一两个关键字 (keyword) 短语，用于筛选工作跟踪工具（如积压工作、板和查询）或定义查询。 有关详细信息，请参阅 添加工作项标记以对列表和版块进行分类和筛选。

标记名称必须符合以下限制。

限制类型	限制
长度	- 不能包含超过 400 个 Unicode 字符。 - 不得为 null 或为空。
特殊字符	- 不得包含分隔符： , 或 ;。 - 不得包含 Unicode 控件或格式字符，如换行符、段落分隔符、回车符或其他不匹配的代理字符。
范围	因为全局列表在所有项目中都可用，所以不能包含在项目级别定义的元素，例如项目特定的组帐户定义。

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 检查-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 版本控制的文件和文件夹必须符合以下限制。

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

TFVC 标签

在 Team Foundation 版本控制 (TFVC) 中，标签是应用于一组特定修订的名称。 可以在版本控制中将标签附加到一组不相关的文件，这样就可以检索文件或将其作为一个组进行处理。 下表描述了对标签名称的限制。

限制类型	限制
长度	不能包含超过 64 个 Unicode 字符。
特殊字符	- 不能以空格 ( ) 或句点 .结尾。 - 不得包含以下可打印字符： \ / : * ? " < > | ; @。

TFVC 货架集

通过使用搁置集，你可以暂时保留一批挂起的更改，并可以选择在以后从你的工作区移除这些挂起的更改。 你可以在以后将搁置集中的更改还原到你的工作区中或将这些更改放入其他用户的工作区。

搁置集名称必须符合以下限制。

限制类型	限制
长度	不能包含超过 64 个 Unicode 字符。
特殊字符	不得包含以下可打印字符： \ / : * ? " < > | ;。

TFVC 工作区

工作区是 Team Foundation 版本控制中的文件和文件夹的客户端副本， (TFVC) 。 创建多个工作区时，客户端计算机上可以有同一版本控制文件夹的不同版本。 创建和使用工作区 提供了更多详细信息。

工作区名称必须符合以下限制。

限制类型	限制
长度	不能包含超过 64 个 Unicode 字符。
特殊字符	- 不得以空格 ( )结尾。 - 不得包含以下可打印字符： \ / : * ? " < > | ;。

组织名称

重要

目前，只能在组织名称中使用英文字母表的字母。 以字母或数字开头的组织名称，后跟字母、数字或连字符。 组织名称不能包含超过 50 个 Unicode 字符，并且必须以字母或数字结尾。

流程和流程模板

进程定义工作项跟踪系统以及连接到项目后有权访问的其他子系统的构建基块。

备注

术语：“流程”和“过程模板”都是指用于创建项目的相互依赖的文件集。 有关详细信息，请参阅 关于进程和进程模板，其中描述了可用的三个默认进程之间的差异。

定义或自定义的过程必须符合以下限制。

限制类型	限制
长度	不能超过 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 组帐户或这些类型的任意混合。 有关详细信息，请参阅 将 AD/Azure AD 用户或组添加到内置安全组。

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

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

团队名称

团队名称标识在项目中以团队身份共同协作的一组个人或组。 团队成员使用此名称连接到团队或查询为团队定义的成员。

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

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

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

用户帐户名称

用户帐户标识添加到项目或项目集合的人员。 用户帐户可能对应于 Active Directory、Azure Active Directory、Windows 服务器组中的条目。

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

限制类型	限制
帐户名称长度	不能超过 256 个 Unicode 字符。
唯一性	不得与添加到项目集合的任何其他用户帐户匹配。
保留的组名	不得在项目或服务器级别使用$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 项目计数和大小限制
• 工作跟踪、进程和项目限制
• 自定义工作跟踪对象以支持团队的进程
• 自定义过程模板