The Codeplex Community TFS Build Extensions contains a wide variety of activities that can be used with the TFS 2010 or 2012 build process. However, the way to use them is sometime less than obvious. This is not helped by the complexity in using any custom activity within TFS 2010/2012 builds.

In this example we will show how to get started with the StyleCop activity, which should also help shed some light on using other custom assemblies.

Actions to be Done Once

Get the Custom Activity and Supporting Files

1. Download and install StyleCop on you development PC. The custom activity is built against StyleCop 4.7.x.x.
2. Download and unzip the Community TFS Build Extensions to a directory on you development PC. The zip file contains both 2010 and 2012 version of the custom activities.

Get the files onto the build box

The assemblies that contain the custom activity and StyleCop need to put under source control so they are available to the build controller and agent(s).

1. In VS2010 or VS2012 open Source Control Explorer select your Team Project and map the BuildProcessTemplates folder to a location on your local disk.
2. Create a new folder under the BuildProcessTemplates called Custom Assemblies
3. In this  Custom Assemblies new folder copy all the assemblies from the unzipped TFS Build Extensions  Make sure you copy the 2010 or 2012 version of the assemblies as required.
4. Also copy all the StyleCop DLL from C:\Program Files (x86)\StyleCop 4.7 to  Custom Assemblies
5. From within Source Control Explorer add these new files to the new Custom Assemblies folder and check the files into TFS.
6. Open Team Explorer, right-click on Builds and select Manage Build Controllers
7. Select the controller to configure, and then select Properties
8. Set the Version control path to custom assemblies to the location just created under version control containing your added assemblies

Get the custom activities into Visual Studio

Next we need to get the activity into Visual Studio so we can add it to build process

1. Open Visual Studio 2010 or Visual Studio 2012 (use the version that match the version of TFS you are using)
2. Create new Class Library project, this new project is only going to be used as a container for the editing of the build process template. IMPORTANT - this project must target .NET 4.0 if on TFS 2010 and .NET 4.5 if in TFS 2012. 
3. Delete the Class1.cs file
4. In Solution Explorer right click and select Properties., make sure the new project does not build in any configuration.

Now we have a project to work with, we need to get a process template into it, this can be done by branch the process template into the project for adding it as a link. In this example we use a link to one of the standard template in the BuildProcessTemplates folder, for simplicity. Remember we would normally recommend at least copying the process template in the BuildProcessTemplates folder prior to editing it.

1. Make sure BuildProcessTemplates is mapped in you current workspace and get a local copy on your development PC
2. In the new project select Add Existing Item and browse to local folder mapped to the BuildProcessTemplates, select the template your wish to edit. But, don’t just press the Add button, but use the drop down to select Add as link.
3. On the added file set the build action property to none
4. Select Add Reference and add references to all the assemblies from the unzipped TFS Build Extensions
5. Open the newly added process template in VS2010, this can be slow, so wait…..
6. Open the toolbox and you should see all the standard build activities
7. Right click in the toolbox and select Choose Item, select browse and select the file TfsBuildExtensions.Activities.StyleCop.dll.
8. The StyleCop activity should now be in the toolbox

Editing the XAML Process Template

We can now start to edit the process template mapped in the previous step to add our custom activities.

In this example we are Using the DefaultTemplate, find the ‘Compile the Project’ sequence and add the activities as show in a graphic below. We have chosen to add the sequence inside the compile phase of the project so we can pickup the solution file’s location, but you could choose a different location if that better meets you needs. The StyleCop activity does not require to be after the compile stage as it works against the .CS files, not the compiled assemblies.

To add this block of activities:

1. Add a new sequence activity, named it “Run StyleCop”
2. Add the following variable with a scope of the “Run StyleCop” sequence
   • StyleCopFiles – iEmumerable<string>
   • StyleCopSettingsFile – string
   • StyleCopResults – bool
   • StyleCopViolations - int32
3. The choice of the paths to use depend on whether you wish to use the same StyleCop rules for all projects in a solution. In many project the number of StyleCop rules for the production code will be higher than for test code e.g. no XML headers for unit tests.
   
   If you wish to use the same rules for all files in a solution
   1. Make sure the build builds the SLN file
   2. Make sure there is a settings.stylecop file in the same folder as the solution file (else the default will be used)
   3. Add a FindMatchingFile activity, set the result to StyleCopFiles and the MatchPattern to String.Format("{0}\**\*.cs", BuildDirectory). This will recursively find all the .CS files in the project and add them to the collection.
   4. Add an Assign activity, this is set the to property to StyleCopSettingsFile and the value to String.Format("{0}\Settings.StyleCop", localProject.Substring(0, localProject.LastIndexOf("\"))). We use the name of the .SLN file to find the root folder to find the StyleCop solutions settings file.

   If you wish to use different rules for each project in a solution

   1. Make sure the build builds the PROJ files one by one
   2. In each project folder have a settings.stylecop file with the correct rules. TIP: Make sure the rules are set to not merge in values from parent folders as this will usually mean you enable more rules than you expect.
   3. Add a FindMatchingFile activity, set the result to StyleCopFiles and the MatchPattern to String.Format("{0}\**\*.cs", localProject.Substring(0, localProject.LastIndexOf("\"))). This will recursively find all the .CS files in the project and add them to the collection.
   4. Add an Assign activity, this is set the to property to StyleCopSettingsFile and the value to String.Format("{0}\Settings.StyleCop", localProject.Substring(0, localProject.LastIndexOf("\"))). We use the name of the .SLN file to find the root folder to find the StyleCop projects settings file.
4. Add a WriteBuildMessage activity, set the importance to High (so we always see the message) and the Message to String.Format("About to run Stylecop with {0}", StyleCopSettingsFile)
5. Add a StyleCop activity with the following properties (these are a minimum to get it working, to see what the other options do we would suggest you look at the unit tests in the Codeplex activities source.)
   • SettingsFile = StyleCopSettingsFile
   • SourceFiles = StyleCopFiles.ToArray()
   • Succeeded = StyleCopResults
   • TreatViolationsErrorASWarnings = True - setting this is down to how you want violations to appear in the log
   • ViolationCount = StyleCopViolations
6. Add another WriteBuildMessage activity, again set the importance to High and the Message to String.Format("StyleCop Successed:{0} with {1} violations", StyleCopResults, StyleCopViolations)
7. Save the edited process template and check it into TFS

Running the Build

If you have not done so already create a build using this process template. It is worth remembering here that you do not need to do any previous steps on a development PC as long as you DO NOT wish to edit the process template on that PC. You can create a new build that uses your template with custom activity on any PC.

So create a new build using the edited template. Run the build and if it is all OK you should see a build log similar to the graphic below

Notice that the FXCop (code analysis) results appear within the main build summary (green), but the StyleCop violations (red) appear in the Other Errors and Warnings section. Unfortunate this cannot be altered. You cannot add extra bits to the main build summary. However, you could choose to fail the build if there are StyleCop violations