Finding Bugs, Tasks, and Other Work Items by Using the Work Item Query Language and the Client Object Model for Team Foundation

You can find bugs, tasks, other types of work items, and links between work items by using one of the WorkItemStore.Query methods or a Query object. These queries use the work item query language (wiql), which resembles T-SQL.

TfsTeamProjectCollection tpc = new TfsTeamProjectCollection(
      new Uri("https://server:8080/tfs/DefaultCollection"));
WorkItemStore workItemStore = (WorkItemStore)tpc.GetService(typeof(WorkItemStore)); 
WorkItemCollection queryResults = workItemStore.Query("
   Select [State], [Title] 
   From WorkItems
   Where [Work Item Type] = 'User Story'
   Order By [State] Asc, [Changed Date] Desc");

In this topic

• Query Language

• Syntax of the Where Clause

  • Comparison Operators

  • Variables

  • Literal Values

• Query Methods and the Query Object

• Asynchronous Queries

• Paging of Field Values

Required Permissions

A query will return only those work items for which you have the View work items or View work items in this node permission. Typically, these permissions are granted to members of the Readers and Contributors groups for each team project. For more information, see Team Foundation Server Permissions.

Query Language

The work item query language has five parts.

Select [State], [Title] 
From WorkItems
Where [Work Item Type] = 'User Story'
Order By [State] Asc, [Changed Date] Desc
AsOf '6/15/2010'

Select [State], [Title]	Identifies each Field whose value will be set in every WorkItem that is returned by the query. You can specify either the display name or the reference name of the field. You must use square brackets ([]) if the name contains blanks or periods. Caution You can use a WorkItem that was returned by a query to get the value of a Field, even if the query did not return the value. If you do this, another round trip to the server will occur. For more information, see Performance Considerations.
From WorkItems	Indicates whether you want the query to find work items or links between work items. From WorkItems Use for work items. From WorkItemLinks Use for links between work items. For more information, see Queries for Links between Work Items.
Where [Work Item Type] = 'User Story'	Specifies the filter criteria for the query. For more information, see Syntax of the Where Clause later in this topic.
Order By [State] Asc, [Changed Date] Desc	(Optional) Specifies how to sort the WorkItemCollection that the query returns.
AsOf '6/15/2010'	(Optional) Specifies a historical query by indicating a date or point in time at which the filter is to be applied. For example, this query returns all user stories that existed on June 15, 2010.

Syntax of the Where Clause

The Where clause specifies the filter criteria of a query for work items. The query returns only work items that satisfy these conditions. The following example query returns user stories that are active and that are assigned to you.

Where [Work Item Type] = 'User Story'
AND [State] = ‘Active’
AND [Assigned to] = @Me

You can control the order in which logical operators are evaluated if you use parentheses to group search criteria. For example, to return work items that are either assigned to you or that you closed, change the query filter to match the following example:

Where [Work Item Type] = 'User Story'
AND [State] = ‘Active’
AND ( [Assigned to] = @Me
OR [Closed by] = @Me )

The following table describes the syntax of the Where clause:

Comparison Operators

You can use the operators in the following table to specify how a field must relate to the corresponding value:

Variables

You can use variables in your queries to pass user input or calculated values. To create a query that includes variables, create placeholders in the query string by using @variable. Then pass the name and the value of each variable to the query method by using an implementation of IDictionary, as the following example shows

// Define a query that uses a variable for the type of work item. 
string queryString = "Select [State], [Title] From WorkItems Where [Work Item Type] = @Type";

// Set up a dictionary to pass "User Story" as the value of the type variable.
Dictionary<string, string> variables = new Dictionary<string, string>();
variables.Add("Type", "User Story");

// Create and run the query.
Query query = new Query(workItemStore, queryString, variables); 
WorkItemCollection results = query.RunQuery();

You can also use @Me or @Today in your query without providing values for those variables. When these variables appear in the query but have no associated value passed in the IDictionary implementation, the variables are evaluated as the following table describes:

Literal Values

When you specify a value for each field, the value must match the data type of that field. All fields in Team Foundation have one of the data types that are listed in the following table:

Queries for Links Between Work Items

You can also use queries to find links between work items. A condition in the Where clause may apply to the links or to any work item that is the source or the target of a link. The following table summarizes the differences between these types of queries and queries only for work items:

The following query returns the links between user stories and their active child nodes.

SELECT [System.Id]
FROM WorkItemLinks
WHERE ([Source].[System.WorkItemType] = 'User Story')
  And ([System.Links.LinkType] = 'Child')
  And ([Target].[System.State] = 'Active')
mode(MustContain)

Query Methods and the Query Object

You can query for work items by using the WorkItemStore.Query method. You can also identify the number of work items that satisfy a query without returning all work items by using the WorkItemStore.QueryCount method.

You can create a Query object to define and run queries.

string queryString = "Select [Title] From WorkItems Where [Work Item Type] = 'User Story'"
Query query = new Query(workItemStore, queryString); 
int numWorkItems = query.RunCountQuery();
Console.WriteLine("The project collection has " + numWorkItems.ToString() + " user stories.");

Asynchronous Queries

You can run queries asynchronously by using the Query.BeginQuery method. The following sample runs a query asynchronously and cancels the query after a very short time-out period.

// Run the query asynchronously, and time out after 0.05 seconds. 
ICancelableAsyncResult callback = query.BeginQuery();
callback.AsyncWaitHandle.WaitOne(50, false); 
if (!callback.IsCompleted) 
{
   callback.Cancel();
   Console.WriteLine("The query timed out");
}
else
{
   WorkItemCollection nextResults = query.EndQuery(callback); 
   Console.WriteLine("The project collection has " + nextResults.Count.ToString() + " work items."); 
}

Paging of Field Values

The WorkItemCollection that a query returns contains values for the following fields:

• ID

• Rev (Revision)

• AreaID

• IterationID

• WorkItemType

The values of fields that you specify in the SELECT clause are returned in pages.

You can minimize round trips to the server by selecting all fields that your code will use. The following code makes one round trip for the query and one round trip to return a page of titles every time that a new page is accessed.

WorkItemCollection results = WorkItemStore.Query(
   "SELECT Title FROM Workitems WHERE (ID < 1000)"); 
foreach (WorkItem item in results) 
{
   Console.WriteLine(item.Fields["Title"].Value);
}

If your code accesses a field that you did not specify in the SELECT clause, that field is added to the set of paged fields. Another round trip is performed to refresh that page to include the values of that field.

See Also

Concepts

Extending Work Item Tracking by Using the Client Object Model for Team Foundation