Using Work Item Query Language


As mentioned earlier, work items have their own query language, called the Work Item Query Language (WIQL). This language is a SQL-like construct that, when used in conjunction with the work item tracking object model, can be used to build powerful queries that retrieve detailed information from the work item tracking system.

This section will give you a brief primer on the Work Item Query Language. For all the details, you should check out the documentation provided in the Visual Studio SDK. For this brief primer, you will learn about the different aspects of a WIQL query, and then see a short application that uses a WIQL query.

Every WIQL query consists of a SELECT statement, containing the fields to retrieve, and a WHERE statement to help determine what information to retrieve. So a sample query to retrieve all the work item ids assigned to Developer1 might look like this:

 System.ID from workitems where System.AssignedTo = ‘Developer1' 

You always must specify the fields you are interested in. When specifying fields, you can use either the friendly name or the reference name. In the above example, we have used the reference name. Best practices dictate that you use reference names at all times, as these will never change, while friendly names may change at some point in the future. You can select any field type in a query, except for plain text fields. And all your standard operators, such as =, >, and <, work in the WHERE clause section.

You've already learned about some of the macros you can use, such as @today, @me, and @project. Here is a quick hit list of some behaviors and operators for certain field types:

  • String literals, such as Developer1, must be quoted using either single or double quotes.

  • The under operator is used to check whether an area or iteration path value is within a subtree of a specific node: WHERE [System.AreaPath] under ‘\Chp11WIT\Area1\Subarea1'.

  • The in operator checks to see if a value is a member of a specified collection: WHERE System .AssignedTo in (‘developer1', developer2', ‘developer3').

  • The ever operator tells you if a field has ever been given a certain value. For example, to find all work items ever assigned to Developer1: WHERE System.AssignedTo ever ‘Developer1'.

You can also use the standard SQL order by statement, and asc and desc statements, to sort the results of your WIQL query.

Finally, the information returned by your query depends on the security permissions of the user running the query. If you try to pull all the work items every assigned to Developer1, but do not have access to all the Team Projects, you will receive information only from those team projects you have the authority to access. There is no warning of any kind that occurs. The moral is to make sure you have access and privileges on all the team projects you are planning to query information from.

Okay, given all the previous information, let's write a quick little console application that will return the System.ID and System.Title for every work item that the logged in user has ever been assigned to. We'll then display this information to the screen. Create a new console application called MyWorkItems, then open the Program.cs file.

As shown in Chapter 9, add references to Microsoft.TeamFoundation.dll, Microsoft .TeamFoundation.WorkItemTracking.dll, and Microsoft.TeamFoundation.WorkItemTracking .Client dll. Then add the following using statements to the Program.cs file:

 using Microsoft.TeamFoundation; using Microsoft.TeamFoundation.Client; using Microsoft.TeamFoundation.Server; using Microsoft.TeamFoundation.WorkItemTracking; using Microsoft.TeamFoundation.WorkItemTracking.Client; 

The following code listing goes in the Main() function of the Program.cs file:

 TeamFoundationServer tfs = TeamFoundationServerFactory.GetServer("mstfs"); WorkItemStore wis = (WorkItemStore)tfs.GetService(typeof(WorkItemStore)); WorkItemCollection wic = wis.Query("SELECT System.ID, System.Title FROM workitems WHERE System.AssignedTo = @Me"); foreach (WorkItem wi in wic) { Console.WriteLine("ID = "+ wi.Id.ToString()); Console.WriteLine("Title = "+ wi.Title.ToString()); } 

This code creates an instance of the Team Foundation Server Object, and then creates an instance of the work item store associated with the Team Foundation Server Object. Remember, there is only one work item store for each Team Foundation Server.

Next, you run a work item query against the work item store. This query selects the System.ID and System.Title for all work items that have been assigned to the user running the application. Notice how the @me macro was used, to make this query generic. When you run this query against the work item store, it will return all the work items that match the query, and put them in a work item collection.

Finally, you loop through the collection, and for each work item in the collection, you write out the ID and the title. Figure 11-12 shows you a sample output of this application.

image from book
Figure 11-12



Professional Team Foundation Server
Professional Team Foundation Server
ISBN: 0471919306
EAN: 2147483647
Year: 2004
Pages: 168

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net