Team Build Customisation - Running StyleCop on a Hosted Build Controller

For companies and individuals who don't or can't use an on premise version of Team Foundation Server, the hosted TFS service http://tfs.visualstudio.com is a great alternative. Once signed up, you can connect to the hosted version from visual studio just as you would connect to an on premise version and it provides the same if not a better experience.

However, when it comes to Team Builds, there is some restrictions on the type of customisation that you can do on your hosted build controller. You can, of course, create your own Build Machine and connect with the tfs.visualstudio.com service, but here we are looking a purely hosted service.

In this post, I will demonstrate how to customise your TFS build template to run StyleCop on all your code files. We will use the StyleCop activity present in TFS Build Extensions.

The first step is to get the two libraries need for customisation

1. StyleCop (http://stylecop.codeplex.com/). The version I am using is 4.7.44.0

2. Community TFS Build Extensions  (http://tfsbuildextensions.codeplex.com/). The version I am using is January 2013 release.

Changes in Build Controller

The first thing you need to do is to make your build controller aware of the location of the custom assemblies. This is the place from where the build controller will load assemblies to load and execute activities while running team build. To do so create a folder in your team project where you would want to keep all the build assemblies. Typically, I keep it separate from the project's main branch and other branches. The next step is to inform build controller of this location. For this

1. Click on the build link in your team explorer window. Then click Actions and select Manage Build Controllers.

2. The following dialog appears. Select "Hosted Build Controller" and click on the properties button.

3. In the Build Controller properties dialog, set the "version control path to custom assemblies" property to the folder in team project that you created earlier

Click Ok and close the properties dialog. At this point, the build controller is configured to load your custom activities. The next step is to customise your build's template.

Custom Build Templates

When you create a team project, a folder called BuildProcessTemplate is created by default containing a number of build templates.

Its best practice to make a copy of the template before modifying it. I copied the file DefaulitTemplate.11.1.xaml and renamed it to CustomTemplate.xaml. This will be our custom build template. If you double click this file, you will see the team build workflow. 

The next step is to add the custom StyleCop Activity to this workflow. To do so you will need to do the following

1. Create a Workflow activity project in Visual Studio. This will create a project with all the assemblies required to create a workflow already added in the reference.

2. Add reference to the libraries StyleCop.dll, TfsBuildExtensions.Activities.dll and TfsBuildExntesions.StyleCop.dll

3. Add a link to the CustomTemplate.xaml to the project. Do to so, right click on the project, click Add and then Existing Item, browse to the file CustomTemplate.xaml, click on the arrow with Add button and select Add as Link. 

4.  The fourth and final step of setting up your environment to be able to modify custom template is to add the activities of TFS Build Extensions to the toolbox. To do so, first double click on your CustomTemplate.xaml file to load it up. In the Toolbox window, right click on the area below activities and select the option Add Tab. Name the new tab "TFS Build Extensions". Right click on the tab name and select choose items. Browse to the assemblies "TfsBuildExtensions.Activities.dll" and "TfsBuildExtensions.Activities.Stylecop.dll". The activities are loaded up on Toolbox and you are ready to add the StyleCop activity.

5.  Where do you want to run style cop in your build process is a matter for you decide. I typically want to do it first thing before anything gets compiled. So, I do it as part of "Initialize Variables" sequence in the workflow. I dragged a sequence activity at the end of it and named it "Run StyleCop" as shown.

 6. My Run StyleCop Activity looks like following

As you can see, in the sequence after using the usual write build messages, I use the activity FindMatchingFiles looking for all c# files. The activity properties are set as follows

Note that I am looking for all .cs files and storing the result in a variable called "SourceFilesToStylecop", which takes the type IEnumerable. "Execute StyleCop" is the "Community TFS Build Extension activity" and it's properties are set as following

This completes our changes to the CustomTemplate.xaml file. Save it and check it in.

Adding required assemblies to TFS

At this stage, our custom build template is all ready to be used. But before running it, we need to make sure that the custom assemblies and any related files are added to the TFS folder which was set in the  "Version control path to custom assemblies" option for our build controller. In this case, the assemblies we would want to load are the TFS build extension assemblies, StyleCop assemblies and it's dictionary and settings file. My custom assemblies folder look as follows.

Now, we are all ready to use our custom build template.

Using Custom Template in Build Definition

Open your build definition, click on process, expand Build Process Template and click on New button.

In the New Process Template dialog, select the option "Select an existing XAML file" and browse to the CustomTemplate.xaml file checked-in earlier. Click OK

Now your custom build is ready to be used. Run a sample build and you would see StyleCop being executed in your build doing static code analysis.