Handling builds via Team Foundation Server 2017 REST API

By Mirek on (tags: build, HttpClient, REST, tfs, categories: infrastructure, web)

In this post I am going to show you how to utilize the new TFS 2017 REST API. In particular you will see how easy is to list, queue and manage builds for your team project.

The plan is to

  1. Authorize to TFS 2017 on premise and connect to its web rest api.
  2. Get a list of team projects
  3. For particular team project get a list of build definitions
  4. Queue particular build definition
  5. Check the status of the build

For that I’m going to write a simple web application, handle all of those tasks in the controller actions and display result on simple page.

The REST API of Visual Studio Team Services and Team Foundation Server is widely documented here.

1. Connecting to the TFS REST API

The apis support OAuth authentication and this is the recommended way to go, but you can also use a user password authentication. More on that here and here.

Let’s start by creating a HttpClient

We start with the base address, which will be

Of course instead of my.tfs.com you should place a valid TFS server name. The PAT variable holds the personal access token which has to be included in a base 64 encoded form in the request headers. Remember do not hardcode the personal access token and keep it in a safe location. To obtain an access token for your TFS account follow these instructions.

2. Retreiving a list of team projects

According to this we first prepare a proper url to get a list of all team projects from the collection

Then for the sake of simplicity we say we only want to retrieve the project name and id, so create a simple model for representing this

Although the response objects returned by the TFS contains much more properties, we can deserialize only those which we are interested in. That’s all thanks to the json format.

The TFSResponse is a simple class that wraps the api response

I will intentionally skip the view part of the project to keep the post lean.

3. List build definitions

Build definitions api is documented here. First we start with a model class for the build definition.

You can of course extend it according to your needs, but to trigger a build nothing more that a build definition id is required.

The url that returns a build definitions for particular project looks like this

One comment here. The type query parameter tells the TFS to return only definitions of the new build type. The other value that can be passed here is xaml, which causes to return the old deprecated xaml build definitions. If nothing is specified all definitions are returned. As you probably noticed this is a string pattern. The {0} parameter must be replaced by the project name or id.

Having that we can retrieve the list of build definitions for the project

4. Triggering a build

According to the description to trigger a build we need to do a POST call to the api and pass a json object with build definition details. We have here a full set of options, so we can run a build as we would do it from the web portal of the TFS.

The action method looks like this

First we build the body of the message, which has to be a json string. I’ve decided to build an anonymous object buildContent and serialize it to json. Here we can add also a parameters property with a collection of key value pairs, such as “system.debug”:”true” or any other acceptable by the build definition on trigger.

Then we pass that json object as a body to the request and call the api. The response is quite huge, as you can see in the documentation, but lets extract only two of its properties.

The Id is the identifier of the build, the Status is a string which says: notStarted, inProggress, completed and so on.

5. Get the status of the build

To retrieve the status of the build we use following url

where {0} is again a placeholder for team project name and {1} must be filled with the build id.

Calling the api here is straight forward


That’s it. As you can see working with TFS REST API is quite easy. It allows you to fully integrate with the TFS and use all of its benefits outside the web portal or Visual Studio.

Whole project for this post can be found in the attachment below.