命名限制和约定

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
• 默认集合
• 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。

板列和泳道名称

看板会将积压工作 (backlog) 转变为交互式标识板，并提供可视的工作流。 随着工作从创意阶段进行到完成，你将更新面板上的项。 每一列代表一个工作阶段，每张卡片代表该工作阶段的一个用户故事（蓝色卡片）或 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 控件或格式字符，如换行符、段落分隔符、回车符或其他不匹配的代理项字符。
Scope	由于全局列表在所有项目中都可用，因此它们不得包含项目级别定义的元素，例如特定于项目的组帐户定义。

Azure Pipelines

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

限制类型	限制
作业名称	- 只能包含字母数字字符和 '_'。 - 不能以数字开头。 - 必须具有唯一名称。 - 不得包含诸如“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 控制字符或代理项字符。 - 不得包含以下可打印字符： \ / : * ? " < > ; # $ * { } , + = [ ] |。 - 不得以下划线 _ 开头。 - 不得以句点 .开头或结尾。 - 不能是系统保留名称。

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 字符
• 以字母或数字结尾

如果使用任何不允许的字符，则会收到以下错误消息：VS850015：不允许使用指定的名称：{Organization name}。

流程和流程模板

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

注意

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

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

限制类型	限制
长度	不得包含超过 256 个 Unicode 字符。
唯一性	- 在 Azure DevOps 中必须唯一。 - 如果上传与现有模板同名的模板，则会覆盖现有模板。
处理模板文件大小	不得超过 2 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 字符。
唯一性	不得与添加到项目集合的任何其他用户帐户匹配。
保留组名称	不得在项目或服务器级别使用 $NAMESPACE 进行命名。
特殊字符	- 不得包含以下可打印字符："/ \ [ ] : < > + = ; ? * |。 - 不得在 ASCII 值范围为 1-31 中包含不可打印字符。 - 不得以句点 . 或美元符号 $ 结尾。 - 不得包含逗号 ,。 - 不得包含以下 Unicode 类别：LineSeparator、ParagraphSeparator、Control、Format、OtherNotAssigned。

Wiki 页面和文件名

每个 Wiki 页面对应于 Wiki Git 存储库中的一个文件。 以下限制适用于页面文件名和文件大小：

• 文件名：为页面文件选择名称时，请记住，文件的完全限定路径应为 235 个字符或更少。 页面的完整路径包括存储库 URL、页面文件的文件夹路径和页面文件名。 例如，https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md。

• 唯一性：页面文件名在其 Wiki 存储库层次结构中的文件夹位置内必须是唯一的。 该名称区分大小写。

• 特殊字符：页面文件名对以下特殊字符有限制：

  • 无 Unicode 控制字符或代理字符
  • 无可打印字符：正斜杠、反斜杠/\、哈希#
  • 名称开头或结尾处没有句点 . 符号

• 文件大小：最大页面文件大小为 18 MB。

• 附件文件大小：页面文件的任何附件的最大大小为 19 MB。

允许的特殊字符

页文件名中允许使用多个特殊字符，例如冒号 : 和连字符 -。 例如，可以将 Markdown 文件命名为 FAQ：0525 或 Setup-Guide。

重要

若要避免页面语法和浏览器导航中的错误，请勿在页面文件名中使用空格字符（ ）。 如果基于页面标题命名页面文件，请将页面标题中的任何空格替换为文件名中的连字符（-）。

下表列出了 Wiki 页面文件名中允许的特殊字符和相应的 URI 编码字符串：

字符	符号	URI 字符串
结肠	:	%3A
左尖括号	<	%3C
右尖括号	>	%3E
星号（通配符）	*	%2A
问号	?	%3F
竖线	|	%7C
连字符 （短划线）	-	%2D
双引号	"	%22

例如，文件名 FAQ：0525 编码为 FAQ%3A0525。

相关文章

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