Fetch work items with queries programmatically
Azure DevOps Services
A common scenario in Azure DevOps Services is to fetch work items using queries. This article details how to implement that scenario programmatically using our REST APIs or .NET client libraries.
Prerequisites
You must have the following items:
- An organization in Azure DevOps Services. If you don't have one, you can create one for free
- A Personal Access Token, find out how to create one
- A C# development environment, you can use Visual Studio
Create a C# project in Visual Studio
For information about C# programming within Visual Studio, see the Visual Studio C# programming documentation.
C# code content
The following tasks occur in the following code sample:
- Authenticate
- Create credentials using your PAT
- Generate the client
- Get the work items
- Create the query you want to use
- Get the results for that query
- Get each of the work items by ID
C# code snippet
// nuget:Microsoft.TeamFoundationServer.Client
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.Common;
public class QueryExecutor
{
private readonly Uri uri;
private readonly string personalAccessToken;
/// <summary>
/// Initializes a new instance of the <see cref="QueryExecutor" /> class.
/// </summary>
/// <param name="orgName">
/// An organization in Azure DevOps Services. If you don't have one, you can create one for free:
/// <see href="https://go.microsoft.com/fwlink/?LinkId=307137" />.
/// </param>
/// <param name="personalAccessToken">
/// A Personal Access Token, find out how to create one:
/// <see href="/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops" />.
/// </param>
public QueryExecutor(string orgName, string personalAccessToken)
{
this.uri = new Uri("https://dev.azure.com/" + orgName);
this.personalAccessToken = personalAccessToken;
}
/// <summary>
/// Execute a WIQL (Work Item Query Language) query to return a list of open bugs.
/// </summary>
/// <param name="project">The name of your project within your organization.</param>
/// <returns>A list of <see cref="WorkItem"/> objects representing all the open bugs.</returns>
public async Task<IList<WorkItem>> QueryOpenBugs(string project)
{
var credentials = new VssBasicCredential(string.Empty, this.personalAccessToken);
// create a wiql object and build our query
var wiql = new Wiql()
{
// NOTE: Even if other columns are specified, only the ID & URL are available in the WorkItemReference
Query = "Select [Id] " +
"From WorkItems " +
"Where [Work Item Type] = 'Bug' " +
"And [System.TeamProject] = '" + project + "' " +
"And [System.State] <> 'Closed' " +
"Order By [State] Asc, [Changed Date] Desc",
};
// create instance of work item tracking http client
using (var httpClient = new WorkItemTrackingHttpClient(this.uri, credentials))
{
// execute the query to get the list of work items in the results
var result = await httpClient.QueryByWiqlAsync(wiql).ConfigureAwait(false);
var ids = result.WorkItems.Select(item => item.Id).ToArray();
// some error handling
if (ids.Length == 0)
{
return Array.Empty<WorkItem>();
}
// build a list of the fields we want to see
var fields = new[] { "System.Id", "System.Title", "System.State" };
// get work items for the ids found in query
return await httpClient.GetWorkItemsAsync(ids, fields, result.AsOf).ConfigureAwait(false);
}
}
/// <summary>
/// Execute a WIQL (Work Item Query Language) query to print a list of open bugs.
/// </summary>
/// <param name="project">The name of your project within your organization.</param>
/// <returns>An async task.</returns>
public async Task PrintOpenBugsAsync(string project)
{
var workItems = await this.QueryOpenBugs(project).ConfigureAwait(false);
Console.WriteLine("Query Results: {0} items found", workItems.Count);
// loop though work items and write to console
foreach (var workItem in workItems)
{
Console.WriteLine(
"{0}\t{1}\t{2}",
workItem.Id,
workItem.Fields["System.Title"],
workItem.Fields["System.State"]);
}
}
}