Link and attachment queries

VSTS | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

You can link work items to track related work and dependencies and attach files to share information with your team. You can then list work items based on their link type, link count, or attachment file count.

You can filter for work items by the link type, link count, or attachment count.

Filter for

Include these query clauses

Items with attachments

Attached File Count >= 1

Items with 2 or more hyperlinks

Hyperlink Count >= 2

Items containing external links

External Link Count >=1

Items that contain between 3 and 7 Related links

   Related Link Count >=3


   Related Link Count <=7

List hierarchical items in a tree view

Add a query and select Tree of work items to begin your query. You should see something similar to the following:

Query editor, new tree of work items query


You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. You can view the hierarchy through the Test Plans page of the Test hub.

From there, you can add additional query clauses or change the Filter options for linked work items.

Filter for Include these query clauses
View only child items of work item 645
Add to Filters for top level work items: ID = 645
Tasks or bugs
Add to Filters for linked work items: Work Item Type In Task,Bug
Items assigned to my team (Web) Add to both top and bottom filters: Assigned to In Group [Fabrikam Fiber]\Web
Parent items of tasks assigned to me:
Change Filter options to Match linked work items first
Add to Filters for linked work items:
Assigned To = @Me

List items based on linked dependents

The following example shows a dependent linked query that returns items with dependencies on work managed by other teams and other team projects. Use this query to see all dependent work items that link to active Product Backlog Items or Bugs that have not been removed, closed, or completed. Only those dependent work items that are under a product area other than the Phone Save\Phone Customers are returned.

Work Items and Dependent Links Query

Why this works:

  • Removing the Team Project = @Project clause enables all dependent linked work items that match the filter criteria to be listed, no matter which team project they belong to in the collection.

  • Grouping each of two clauses returns all Product Backlog Items on the backlog or in progress, and the second grouped clause returns all Bugs on the backlog or in progress.

  • Grouping the two clauses with the OR operator at the start of the second clause returns work items that match either of the two filter criteria.

  • Choosing the Only return items that have the specified links returns only top-level work items that have dependencies.

  • Choosing Return links of any type returns all linked work items that match the filter criteria for linked work items, in this case, returning all work items that are not under the Phone Saver\Phone Customers area path, and aren't completed or removed.

The following image shows the query results that are returned.

Direct links query results

The following table describes fields associated with links and attachments. Most of these fields do not appear on the work item forms but are tracked for all work item types.

Field name


Work item type

Attachment File Count

The number of files attached to the work item and stored in the work item tracking database..

Reference Name=System.AttachedFileCount, Data type=Integer

note icon
For VSTS, you can add up to 100 attachments to a work item. Attempts to add more result in an error message upon saving the work item.


External Link Count

The number of links from the work item to artifacts that are not work items. such as pull requests, commits, changesets, or other link types.

Reference Name=System.ExternalLinkCount, Data type=Integer


Hyperlink Count

The number of hyperlinks that are defined for the work item.

Reference Name=System.HyperLinkCount, Data type=Integer


Link Comment

Contains comments from the team member who created the link. You can configure this field to appear as a column in a list of links on a work item form. (Not supported in query editor.)

Reference Name=System.Links.Comment, Data type=PlainText


Related Link Count

The number of links defined for a work item with the Related link type.

Reference Name=System.RelatedLinkCount, Data type=Integer


Link Description

Contains the work item type, ID, and title of the work item that is the target of the link. You can configure this field to appear as a column in a list of links on a work item form. (Not supported in query editor.)

Reference Name=System.Links.Description, Data type=PlainText


You can view related work items and object within a work item form by installing the Work item visualization extension available from the Visual Studio Marketplace.

To add link types (TFS only), see Manage link types [witadmin].

All tabs that support creating links between work items are implemented by using the LinksControl element on the work item form. This element controls filtering and restricting the types of work items to which you can link, the types of links that you can create, and whether you can link to work items in another team project. To customize the link controls and restrictions, you modify the definition of the LinksControlOptions for a work item type, see LinksControlOptions XML elements.