連結類型的參考指南

  • 發行項

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

您可以使用不同的連結類型來管理工作專案與其他成品之間的各種關聯性，例如組建、認可、提取要求等等。 在本文中，我們會描述下列連結類型。

特定欄位會維護前四個連結類型的連結計數，例如相關連結計數、超連結計數、外部連結計數和遠端連結計數。

  • 工作連結類型：連結工作專案，包括選取測試案例管理工作專案
  • 超連結：將工作項目連線至任何URL或網路共用
  • 外部連結類型：將工作專案連接到外部物件，例如程式代碼對象、組建或Wiki頁面
  • GitHub 連結類型：將工作項目連線至 GitHub 存放庫認可或提取要求。

特定欄位會維護前三個連結類型的連結計數，例如 相關連結計數、 超連結計數和 外部連結計數。

鏈接類型會根據其拓撲受到特定限制。 使用下表中提供的指引，根據您想要建立的查詢和報表類型，選擇要使用的連結類型。 若要深入瞭解不同的拓撲，請參閱 鏈接類型拓撲和限制。

工作連結類型為系統定義、進程定義或使用者定義（自定義）。 下表所列的連結是系統定義的。

每個工作連結類型都會定義建構工作專案之間的連結標籤、拓撲類型和限制。 例如，父子連結類型會定義兩個標籤：Parent 和 Child。 連結類型也支援階層式或樹狀結構拓撲，並防止在工作項目之間建立循環參考。

工作項目連結類型的概念影像。

工作專案的 [相關連結計數 ] 對應至以工作連結類型定義之所有連結的總和。

下表描述您可以使用 WorkItemLinksFilter XML 元素來設定連結控制元件範圍的工作專案連結類型。

名稱

參考名稱

使用方式

影響受影響 （僅限 CMMI） 影響連結類型的概念影像。受連結類型影響的概念影像。

Microsoft.VSTS.Common.Affects-Forward
Microsoft.VSTS.Common.Affects-Reverse
拓撲類型：相依性
鏈接類別：進程定義

使用此方向連結來建立任何一組工作專案之間的連結，但不是會建立封閉迴圈的專案。 通常用來追蹤對需求所做的變更要求。

限制和建議：

  • 您可以使用 Affects，將變更要求連結至只有一個需求。 您可以使用 [受影響的人] 將需求連結至所需的多個子變更要求。
  • 只使用影響受影響的連結來連結相同專案中的工作專案。 如果您打算使用 Excel 來修改或更新工作專案數據，建議您執行此動作。

Child-Parent
子連結類型的概念影像。
父連結類型的概念影像。

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Hierarchy-Reverse
拓撲類型：樹狀結構
鏈接類別：系統定義

使用此方向連結可建立單一父系與一個或多個子項目之間的一對多關聯性。 使用 來組織階層內的工作專案。 您可以使用對應函式，或使用短期衝刺待辦專案或Taskboard，在待辦專案和工作之間快速建立此階層。

一般用法包括：

  • 維護工作摘要關聯性。 父子連結會針對摘要工作和其次級工作建立。
  • 將工作連結至 PBIs、用戶劇本或需求。 支援待辦專案概觀、劇本概觀和需求概觀報告。

限制和建議：

  • 使用 Excel 大量編輯工作項目和父子連結。 請參閱 使用 Excel 大量新增或修改工作專案。
  • 工作專案只能有一個 Parent。 父工作專案可以有許多子系。
  • 只使用父子連結來連結相同專案中的工作專案。 如果您打算使用 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、使用者劇本、需求和產品待辦專案。 用來追蹤測試用戶劇本（Agile）、產品待辦專案 （Scrum） 或需求 （CMMI） 的測試案例。 也可以連結到其他工作項目類型，例如 Bug、問題或工作。 針對內部部署 Azure DevOps，有數個 SQL 報告相依於這些連結。 請參閱 檢閱小組活動以支援有用的報告。

測試案例共用步驟
鏈接類型測試的概念影像。測試連結類型的概念影像。

Microsoft.VSTS.TestCase。
SharedStepReferencedBy
拓撲類型：相依性
鏈接類別：進程定義

使用連結測試案例與共用步驟。 在測試案例 之間共用步驟，以避免必須建立相同步驟序列的多個專案。

超連結可以將工作項目連結至任何URL。 [超連結計數] 會追蹤工作專案的超連結數目。

超連結的概念影像。

連結名稱

支援的工具

成品類型

使用方式

超連結

工作項目追蹤

超連結

用來將工作項目連結至 URL。 工作專案超連結是成品連結類型 API 中此連結類型的名稱。

外部連結類型是系統定義的連結類型，可支援將工作專案連結至儲存在 Azure DevOps 內的其他物件，如下圖所示。 工作專案的 [外部連結計數 ] 對應至以外部連結類型定義的所有連結總和。

外部連結類型的概念影像。

注意

您只能使用外部連結類型來連結至 Azure DevOps 物件。 若要將工作項目連結至 Azure DevOps 外部的其他物件，請使用 超連結。

下表描述當您從工作專案或測試案例新增連結類型時，可以選擇的外部連結類型。

下表描述從工作項目或測試案例新增連結類型時，您可以選擇的外部連結類型。 此外，您也可以使用 ExternalLinksFilter XML 元素，指定其中一個連結類型來設定連結控制件的範圍。

連結名稱

支援的工具

成品類型

使用方式

分行

Git

分行

用來將工作項目連結至分支。

管線/組建

組建

組建

用來將工作專案連結至組建。

Changeset （或在 Changeset 中修正）

VersionControl

Changeset

用來將工作專案連結至變更集。

認可 （或在認可中修正）

Git

提交

用來將工作專案連結至認可。

在組建中找到

管線/組建

組建

用來將工作專案連結至組建。

整合在組建中

組建

組建管線

用來將工作專案連結至組建。

整合在發行環境中

版本

發行管線

用來將發行連結至工作專案。 當使用者啟用 發行定義的 [報表部署狀態為 Work ] 選項時，系統會建立此類型的連結。

提取要求

Git

PullRequestId

用來將工作項目連結至提取要求。

結果附件

測試管理

TcmResultAttachment

用來將工作項目連結至與測試結果相關聯的附件。 當您將工作專案與 Test 或 Microsoft Test Manager 的測試結果產生關聯時，就會顯示這些連結。

原始碼檔案<

VersionControl

LatestItemVersion

用來將工作項目連結至 Team Foundation 版本控制 （TFVC） 底下的檔案。

分鏡

需求

分鏡

用來將工作項目連結至PowerPoint檔案或其他檔案，其中包含網路上的故事上線資訊。

標籤

Git

標籤

用來將工作專案連結至針對 Git 認可或 Git 存放庫定義的標記。 如需詳細資訊，請參閱 從 Git 命令提示字元工作。

測試結果

測試管理

TcmResult

用來將工作專案連結至測試結果。 當您將工作專案與 Test 或 Microsoft Test Manager 的測試結果產生關聯時，就會顯示這些連結。

已建立版本的專案

VersionControl

LatestItemVersion

用來將工作項目連結至 TFVC 存放庫中定義的檔案或變更集。 原始碼檔是成品連結類型 API 中此連結類型的名稱。

Wiki

Wiki

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]

選擇性參數

  • 組織：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 格式提供連結類型所定義之屬性的其他資訊。 例如，鏈接類型 產生 For and Consumes From 的資訊會如下所示。

  {
    "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

您可以使用命令列工具或工作專案關聯類型 - 清單 REST API 命令，列出專案集合witadmin listlinktypes支援的連結類型。

我們在這裡列出 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。 workItemLink resourceLinkvalue indicates a link type that links two work items. The的值表示連結類型，用來將工作專案連結至資源，例如 URL 或附件。

url

以 json 格式列出連結類型的屬性。