链接类型参考指南

项目
04/05/2024

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

可以使用不同的链接类型来管理工作项和其他项目（如生成、提交、拉取请求等）之间的各种关系。在本文中，我们将介绍以下链接类型。

工作链接类型：链接工作项，包括选择测试用例管理工作项
超链接：将工作项连接到任何 URL 或网络共享
外部链接类型：将工作项连接到外部对象，例如代码对象、生成或 Wiki 页面
远程工作链接类型：连接不同组织中定义的工作项
GitHub 链接类型：将工作项连接到 GitHub 存储库提交、问题或拉取请求。

一个特定的字段维护前四种链接类型的链接计数，例如“相关链接计数”、“超链接计数”、“外部链接计数”和“远程链接计数”。

工作链接类型：链接工作项，包括选择测试用例管理工作项
超链接：将工作项连接到任何 URL 或网络共享
外部链接类型：将工作项连接到外部对象，例如代码对象、生成或 Wiki 页面
GitHub 链接类型：将工作项连接到 GitHub 存储库提交或拉取请求。

一个特定的字段维护前三种链接类型的链接计数，例如“相关链接计数”、“超链接计数”和“外部链接计数”。

链接类型根据其拓扑会受到某些限制的约束。使用下表中提供的指南，根据要创建的查询和报表类型，选择要使用的链接类型。若要详细了解不同的拓扑，请参阅链接类型拓扑和限制。

工作链接类型

工作链接类型可以由系统定义、由流程定义，也可以由用户定义（自定义）。下表中列出的链接是系统定义的。

每个工作链接类型都定义了在构造工作项之间的链接时使用的链接标签、拓扑类型和限制。例如，父子链接类型定义了两个标签：父级和子级。该链接类型还支持分层拓扑或树拓扑，可以防止在工作项之间创建循环引用。

工作项链接类型的概念图像。

工作项的相关链接计数对应于使用工作链接类型定义的所有链接的总和。

下表介绍了一些工作项链接类型，可以指定类型来使用 WorkItemLinksFilter XML 元素设定链接控件范围。

名称

引用名称

使用情况

影响-影响者（仅限 CMMI）影响链接类型的概念图像。影响方式链接类型的概念图像。

Microsoft.VSTS.Common.Affects-Forward
Microsoft.VSTS.Common.Affects-Reverse
拓扑类型：依赖项
链接类别：由流程定义

使用此定向链接，可以在任意一组工作项（但不是创建封闭环的工作项）之间创建链接。通常用于跟踪对需求发出的更改请求。

限制和建议：

你可以使用“影响”将更改请求链接到一个且只能一个需求。你可以使用“影响者”来根据需要将需求链接到多个子更改请求。
只能在同一项目中使用“影响-影响者”链接来链接工作项。如果计划使用 Excel 修改或更新工作项数据，建议采用此做法。

子-父
子链接类型的概念图像。
父链接类型的概念图像。

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Hierarchy-Reverse
拓扑类型：树
链接类别：由系统定义

使用此定向链接，可以在单个父项与一个或多个子项之间创建一对多关系。用于在层次结构中组织工作项。可以使用映射函数在积压工作项之间，或使用冲刺 (sprint) 积压工作或任务板在积压工作项和任务之间快速创建此层次结构。

典型用法包括：

保持任务摘要关系。父子链接是为摘要任务及其下属任务创建的。
将任务链接到 PBI、用户情景或要求。支持积压工作 (backlog) 概述、情景概述和需求概述报表。

限制和建议：

使用 Excel 同时批量编辑工作项和父子链接。请参阅使用 Excel 批量添加或修改工作项。
一个工作项只能有一个父级。一个父工作项可以有多个子级。
只能在同一项目中使用“父-子”链接来链接工作项。如果计划使用 Excel 修改或更新工作项数据，建议采用此做法。

重复项-副本 树正向复制的概念图像。树反向复制的概念图像。

System.LinkTypes.Duplicate-Forward
System.LinkTypes.Duplicate-Reverse
拓扑类型：树
链接类别：由系统定义

使用此定向链接，可以在单个父项与一个或多个子项之间创建一对多关系。用于跟踪任务、bug 或相互重复的其他工作项。

限制和建议：

一个工作项只能有一个重复项。
只能在同一项目中使用“重复项或副本”链接来链接工作项。如果计划使用 Excel 修改或更新工作项数据，建议采用此做法。

引用方-引用
测试方式链接类型的概念图像。测试链接类型的概念图像。

Microsoft.VSTS.TestCase.
SharedParameterReferencedBy
拓扑类型：依赖项
链接类别：由流程定义

用于将测试用例链接到共享参数。用于将测试用例链接到共享参数，以支持使用不同的数据重复执行测试的功能。通常，不会将此链接类型添加到范围内的链接控件。

相关
相关链接类型的概念图像。

System.LinkTypes.Related
拓扑类型：网络
链接类别：由系统定义

使用这个非定向链接，可以在任意一组工作项之间创建链接。用于链接位于同一级别（例如定义彼此重叠的功能的两个用户情景）的工作项。相关链接类型创建具有极少限制的简单关系。

关联位于同一级别（例如定义彼此重叠的功能的两个用户情景）上的工作项。
链接在不同项目中定义并由不同的团队管理的工作项。
在两层视图中查找和查看工作项及其相关工作项。
创建具有极少限制的简单关系。

后续-前置
后续依赖项正向的概念图像。前置依赖项反向的概念图像。

System.LinkTypes.Dependency

拓扑类型：依赖项
链接类别：由系统定义
当链接到应在从其链接的工作项之前完成的工作项时，选择“前置”链接类型。当链接到应在从其链接的工作项之后完成的工作项时，选择“后续”链接类型。

使用此定向链接，可以在任意一组工作项（但不是创建封闭环的工作项）之间创建链接。用于跟踪在可以开始其他任务之前必须完成的任务。链接任务在 Azure Boards 中表示为前导/后续链接。

跟踪在可以开始其他任务之前必须完成的任务。
支持一对多关系。
在两层、直接链接查询视图中查找并查看前置工作项及其后续工作项。

限制和建议：

当尝试创建定义循环关系的链接时会出现错误。
只能对同一项目中的工作项创建“前置-后续”链接。可以在不同项目中定义的工作项之间创建前置后续链接。但是，如果将查询导出到 Excel，只会导入那些为定义该查询的项目定义的工作项。

测试方-测试
测试方式链接类型的概念图像。测试链接类型的概念图像。

Microsoft.VSTS.Common.TestedBy-Forward
Microsoft.VSTS.Common.TestedBy-Reverse
拓扑类型：依赖项
链接类别：由流程定义

将测试用例链接到工作项，例如 bug、用户情景、需求和产品积压工作项。用于跟踪测试用户情景（敏捷）、产品积压工作项 (Scrum) 或需求 (CMMI) 的测试用例。还可以链接到其他工作项类型，例如 bug、问题或任务。对于本地 Azure DevOps，有多个 SQL 报表依赖于这些链接。请参阅审阅团队活动以支持有用的报表。

测试用例-共享步骤
测试方式链接类型的概念图像。测试链接类型的概念图像。

Microsoft.VSTS.TestCase.
SharedStepReferencedBy
拓扑类型：依赖项
链接类别：由流程定义

用于将测试用例与共享步骤链接。在测试用例之间共享步骤，可以避免在同一步骤顺序中创建多个条目。

超链接

超链接可以将工作项链接到任何 URL。超链接计数跟踪指向工作项的超链接数。

超链接的概念图像。

链接名称

支持的工具

项目类型

使用情况

Hyperlink

工作项跟踪

Hyperlink

用于将工作项链接到 URL。工作项超链接是项目链接类型 API 中此链接类型的名称。

外部链接类型

外部链接类型是系统定义的链接类型，支持将工作项链接到存储在 Azure DevOps 中的其他对象，如下图所示。工作项的外部链接计数对应于使用外部链接类型定义的所有链接的总和。

外部链接类型的概念图像。

注意

只能使用外部链接类型链接到 Azure DevOps 对象。若要将工作项链接到 Azure DevOps 外部的其他对象，可使用超链接。

下表描述了从工作项或测试用例添加链接类型时可以选择的外部链接类型。

下表描述了从工作项或测试用例添加链接类型时可以选择的外部链接类型。此外，还可指定其中一种链接类型，使用 ExternalLinksFilter XML 元素设定链接控件范围。

链接名称

支持的工具

项目类型

使用情况

分支

Git

分支

用于将工作项链接到分支。

管道/生成

生成

用于将工作项链接到生成。

变更集（或已在变更集中修复）

VersionControl

变更集

用于将工作项链接到变更集。

提交（或已在提交中修复）

Git

提交

用于将工作项链接到提交。

在生成中找到

管道/生成

生成

用于将工作项链接到生成。

在生成中集成

生成

生成管道

用于将工作项链接到生成。

在发布环境中集成

发布

发布管道

用于将发布链接到工作项。当用户为发布定义启用“将部署状态报告为工作”选项时，系统会创建此类型的链接。

拉取请求

Git

PullRequestId

用于将工作项链接到拉取请求。

结果附件

测试管理

TcmResultAttachment

用于将工作项链接到与测试结果关联的附件。将工作项与测试或 Microsoft 测试管理器的测试结果相关联时，将显示这些链接。

源代码文件<

VersionControl

LatestItemVersion

用于将工作项链接到 Team Foundation 版本控制 (TFVC) 下的文件。

情节提要

要求

情节提要

用于将工作项链接到 PowerPoint 文件或其他包含网络上的情节提要信息的文件。

标记

Git

标记

用于将工作项链接到为 git 提交或 git 存储库定义的标记。有关详细信息，请参阅从 Git 命令提示符处理工作。

测试结果

测试管理

TcmResult

用于将工作项链接到测试结果。将工作项与测试或 Microsoft 测试管理器的测试结果相关联时，将显示这些链接。

已进行版本控制的项

VersionControl

LatestItemVersion

用于将工作项链接到 TFVC 存储库中定义的文件或变更集。源代码文件是项目链接类型 API 中此链接类型的名称。

Wiki

用于将工作项链接到 Wiki 页。支持用于 TFS 2018.2 及更高版本。

GitHub 链接类型

GitHub 链接类型是系统定义的类型，支持将工作项链接到 GitHub 对象，如下图所示。

GitHub 链接类型的概念图像。

重要

只能链接到其存储库已连接到 Azure Boards 的 GitHub 项目。

下表描述了从工作项添加链接类型时可以选择的 GitHub 链接类型。

链接名称

项目类型

使用情况

GitHub 提交

GitHub 存储库提交

用于将工作项链接到 GitHub 提交。

GitHub 问题

GitHub 存储库问题

用于将工作项链接到 GitHub 问题。

GitHub 拉取请求

GitHub 存储库拉取请求

用于将工作项链接到 GitHub 拉取请求。

远程工作链接类型

远程工作链接类型是系统定义的链接类型，支持将不同组织中定义的工作项进行链接，只要它们由同一个 Microsoft Entra ID 进行管理即可，如将组织连接到 Microsoft Entra ID 中所述。

工作项的远程链接计数对应于使用远程工作链接类型定义的所有链接的总和。

名称

引用名称

使用情况

使用来源-生产目的
（依赖项拓扑）使用自拓扑的概念图像。生成对象拓扑的概念图像。

System.LinkTypes.Remote.Dependency-Forward
System.LinkTypes.Remote.Dependency-Reverse
拓扑类型：依赖项
链接类别：由系统定义

使用此定向链接，可以在不同的组织中定义且具有依赖项的工作项之间创建链接，前提是这些工作项由同一个 Microsoft Entra ID 管理。通常用于跟踪对需求发出的更改请求。

远程相关
远程相关拓扑的概念图像。

System.LinkTypes.Remote.Related
拓扑类型：网络
链接类别：由系统定义

使用此定向链接，可以在不同的组织中定义的工作项之间创建链接，前提是这些工作项由同一个 Microsoft Entra ID 管理。

自定义链接类型

你可以创建自定义链接类型；导出和导入链接类型的定义；以及删除、激活、停用和重新激活链接类型。请参阅以下文章：

列出链接类型

若要获取链接类型的列表，可以使用任何受支持的命令行工具。

az boards work-item relation list-type

可以使用 az boards work-item relation list-type 命令或工作项关系类型 - 列表 REST API 命令列出组织支持的链接类型。若要开始，请参阅 Azure DevOps CLI 入门。

az boards work-item relation list-type [--org]

可选参数

org：Azure DevOps 组织 URL。可以使用配置默认组织 az devops configure -d organization=ORG_URL。如果未配置为默认或使用选取 git config，则为必需。示例：--org https://dev.azure.com/MyOrganizationName/。

示例

以下命令以表的格式列出了为 fabrikam 组织定义的工作项链接类型。

az boards work-item relation list-type --org fabrikam --output table
Name                  ReferenceName                                                Enabled    Usage
--------------------  -----------------------------------------------------------  ---------  ------------
Produces For          System.LinkTypes.Remote.Dependency-Forward                   True       workItemLink
Consumes From         System.LinkTypes.Remote.Dependency-Reverse                   True       workItemLink
Duplicate             System.LinkTypes.Duplicate-Forward                           True       workItemLink
Duplicate Of          System.LinkTypes.Duplicate-Reverse                           True       workItemLink
Referenced By         Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Forward  True       workItemLink
References            Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Reverse  True       workItemLink
Tested By             Microsoft.VSTS.Common.TestedBy-Forward                       True       workItemLink
Tests                 Microsoft.VSTS.Common.TestedBy-Reverse                       True       workItemLink
Test Case             Microsoft.VSTS.TestCase.SharedStepReferencedBy-Forward       True       workItemLink
Shared Steps          Microsoft.VSTS.TestCase.SharedStepReferencedBy-Reverse       True       workItemLink
Successor             System.LinkTypes.Dependency-Forward                          True       workItemLink
Predecessor           System.LinkTypes.Dependency-Reverse                          True       workItemLink
Child                 System.LinkTypes.Hierarchy-Forward                           True       workItemLink
Parent                System.LinkTypes.Hierarchy-Reverse                           True       workItemLink
Related               System.LinkTypes.Related                                     True       workItemLink
Remote Related        System.LinkTypes.Remote.Related                              True       workItemLink
Attached File         AttachedFile                                                 True       resourceLink
Hyperlink             Hyperlink                                                    True       resourceLink
Artifact Link         ArtifactLink                                                 True       resourceLink

默认的 json 格式提供了有关为链接类型定义的属性的更多信息。例如，链接类型“生产目的”和“使用来源”的信息按如下方式列出。

  {
    "attributes": {
      "acyclic": true,
      "directional": true,
      "editable": false,
      "enabled": true,
      "isForward": true,
      "oppositeEndReferenceName": "System.LinkTypes.Remote.Dependency-Reverse",
      "remote": true,
      "singleTarget": true,
      "topology": "dependency",
      "usage": "workItemLink"
    },
    "name": "Produces For",
    "referenceName": "System.LinkTypes.Remote.Dependency-Forward",
    "url": "https://dev.azure.com/mseng/_apis/wit/workItemRelationTypes/System.LinkTypes.Remote.Dependency-Forward"
  },
  {
    "attributes": {
      "acyclic": true,
      "directional": true,
      "editable": false,
      "enabled": true,
      "isForward": false,
      "oppositeEndReferenceName": "System.LinkTypes.Remote.Dependency-Forward",
      "remote": true,
      "singleTarget": true,
      "topology": "dependency",
      "usage": "workItemLink"
    },
    "name": "Consumes From",
    "referenceName": "System.LinkTypes.Remote.Dependency-Reverse",
    "url": "https://dev.azure.com/mseng/_apis/wit/workItemRelationTypes/System.LinkTypes.Remote.Dependency-Reverse"
  },

`witadmin listlinktypes`

可以使用 witadmin listlinktypes 命令行工具或工作项关系类型 - 列表 REST API 命令列出项目集合支持的链接类型。

下面列出了 fabrikam-sever 默认集合的链接类型：

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin listlinktypes /collection:http://fabrikam-server/DefaultCollection

Reference Name: Microsoft.VSTS.TestCase.SharedParameterReferencedBy
Names: Referenced By, References
Topology: Dependency
Is Active: True

Reference Name: Microsoft.VSTS.Common.TestedBy
Names: Tested By, Tests
Topology: Dependency
Is Active: True

Reference Name: Microsoft.VSTS.TestCase.SharedStepReferencedBy
Names: Test Case, Shared Steps
Topology: Dependency
Is Active: True

Reference Name: System.LinkTypes.Duplicate
Names: Duplicate, Duplicate Of
Topology: Tree
Is Active: True

Reference Name: System.LinkTypes.Dependency
Names: Successor, Predecessor
Topology: Dependency
Is Active: True

Reference Name: System.LinkTypes.Hierarchy
Names: Child, Parent
Topology: Tree
Is Active: True

Reference Name: System.LinkTypes.Related
Name: Related
Topology: Network
Is Active: True

链接类型属性

下表说明了 Azure Boards CLI 或 REST API 返回的每个链接类型属性。

Attribute

说明

名称，name

指定分配给链接类型的友好名称。定向链接是成对定义的，因此包括正向和反向名称。

引用名称，referenceName

指定分配给链接类型或链接类型对的名称。

acyclic

指示链接类型是允许 (true) 还是限制 (false) 循环关系。例如，树类型链接限制循环关系。有关详细信息，请参阅 LinkTypes 元素参考。

directional

指示链接类型是定向的 (true) 还是非定向的 (false)。定向链接类型是成对定义的，其中包括正向和反向组件。有关详细信息，请参阅 LinkTypes 元素参考。

editable

指示链接类型是可编辑的 (true) 还是不可编辑的 (false)。只能使用 witadmin 管理链接类型命令行工具为本地部署添加和编辑自定义链接类型。系统链接类型始终具有 editable=false。

处于活动状态，enabled

指示链接类型处于活动状态 (true) 还是不处于活动状态 (false)。只能使用 witadmin 管理链接类型命令行工具为本地部署使用自定义链接类型。

isForward

指示链接类型在链接类型对中指定 (true) 还是不指定 (False) 正向链接。

oppositeEndReferenceName

指定链接类型的引用名称，它在链接类型对的相反方向定义链接。

remote

指示链接类型支持 (true) 还是不支持 (False) 链接到远程工作项。具有 remote=false 的链接类型要求目标工作项与源工作项位于同一组织或集合中。

singleTarget

指示链接类型是允许多个目标 (false) 还是限制为单个目标 (true)。

topology

指定拓扑类型 - 依赖项, 网络, and 树。有关说明，请参阅链接类型拓扑和限制。

usage

指定使用类型 - resourceLink 或 workItemLink。 The workItemLinkvalue indicates a link type that links two work items. TheresourceLink` 值指示用于将工作项链接到资源的链接类型，例如 URL 或附件。

url

以 json 格式列出链接类型的属性。

链接类型参考指南

工作链接类型

超链接

外部链接类型

GitHub 链接类型

远程工作链接类型

自定义链接类型

列出链接类型

az boards work-item relation list-type

可选参数

示例

`witadmin listlinktypes`

链接类型属性

反馈

反馈

其他资源

链接类型参考指南

工作链接类型

超链接

外部链接类型

GitHub 链接类型

远程工作链接类型

自定义链接类型

列出链接类型

az boards work-item relation list-type

可选参数

示例

witadmin listlinktypes

链接类型属性

相关文章

反馈

反馈

其他资源

`witadmin listlinktypes`