Setting Up StyleCop For VS2012 Agile Team

StyleCop 

StyleCop is a visual studio add-in that allows us to apply coding guidelines to our projects, if we want our code to look a certain way then StyleCop can help us to enforce these guidelines through warning or errors.  



StyleCop can be downloaded from the following location: http://stylecop.codeplex.com/  

In order for us to utilise StyleCop, we have two options; install the StyleCop executable, or, for more collaborative development situations, set up StyleCop against the project and allow each member of the team to link to the target values.  


Install Style Cop 

StyleCop should initially be installed on a single development machine, once the application has been installed then the user can open the project they wish to apply some coding guidelines to. 
 If we right click on our project the context menu should now contain an option to for StyleCop Settings. 


Context menu with StyleCop settings

If we click this we get the StyleCop settings form, this allows us to define what our guidelines are for this project. 


StyleCop Settings Form

The image above shows the StyleCop settings with maintainability, Layout and Naming rules all checked for inclusion. 

Once we’ve chosen our settings for this project we can apply them to all of the projects in the solution by locating the settings.stylecop file in the root folder of the project we applied the settings to. Copy this file into the root folder of the solution. 

Inside the solution we need to open the StyleCop settings for each project and ensure that the setting Merge with settings file found in parent folders is selected. 

This will enforce any StyleCop settings higher up in the folder structure. 

StyleCop Settings Files Tab

Attempt to build the application and you should receive warnings for any code that breaks your selected guidelines.

StyleCop rules being violated (errors flag set to true)
This gives us an overview of how set up StyleCop on a single machine, but what if we want to set up StyleCop in a team environment?  

There’s at least two requirements that we might need to satisfy, the first is setting up style cop on each developers machine, the second is setting up StyleCop on an integrated build machine.

Setting up StyleCop on multiple machines 

StyleCop team integration doesn’t require each user to install the StyleCop client; in fact, we can set StyleCop up with a few easy steps using files from the original install. 

Firstly, we need to locate the StyleCop targets file, this can be found in the location: {Program Files}\MSBuild\StyleCop\v4.x 

Copy and paste the file StyleCop.Targets into the root folder of the solution we want to apply the guidelines to.  

Next, create a folder called StyleCop in the root folder of the solution, then, Locate the folder {Program Files}/StyleCop 4.x, copy and paste all files from this folder to the new StyleCop folder you created in the solution root folder. 


Adding files to the solution 

In visual studio add the StyleCop.Targets file by right clicking on the solution, selecting Add and then Existing Item. 

In visual studio add the settings.stylecop file we created in the install StyleCop section of this walkthrough by right clicking on the solution, selecting Add and then Existing Item. 

The previous actions should create a folder called Solution Items by default. 

Right click on the folder Solution Items, select Add, and select New Solution Folder. 

Give the folder the name StyleCop. 

Right click on the StyleCop folder and select Add and then Existing Item. 

Navigate to the StyleCop folder you created in the root folder of the solution and add all of the files in this folder to the solution folder in visual studio. 

When you’ve added both of these files and the folder your solution should look something like this: 

Solution Items

Editing StyleCop.Targets 

 Open the StyleCop.Targets file; locate the UsingTask element at the top of the file and replace it with the following element:


<UsingTask AssemblyFile="$(SolutionDir)\StyleCop\StyleCop.dll" TaskName="StyleCopTask"/>

 
StyleCop Targets UsingTask


Editing the project files 
Open the solution folder in windows explorer and select the first project that we want to add StyleCop settings to and find the .csproj file, ensure the file is checked out and then right click and open the file in a text editor.  

Inside the text editor we need to add an import statement to the project file  
<Import Project="$(StyleCopTargets)" /> 

You can add this in under other import files in the project or directly underneath the following import file that should already exist: 
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" /> 

Repeat this for each project in the solution that you want the guidelines applied to. 
Check in the solution. 

Creating The Environment Variable 

We need to now link the StyleCop on each developers machine, go to each machine and get latest on the project that was just edited then follow the next steps on each user machine: 

Create an environment variable that allows the other development machines to see where the StyleCop.Targets file is located. 

To create an environment variable in the start menu type run, select enter, and then enter the command sysdm.cpl in the run menu, press enter and then select the button Environment Variables.
  
Add Environmental Variable



In the System Variables section, select Add and create an environment variable called StyleCopTargetsin the value field we need add in the location of the StyleCop.Targets file that exists in the solution. 

Select ok to create this variable and then restart the machine 

Once the machine has restarted open the solution and check that the project can be built. If it’s a new solution then try adding in some code that you know breaks the style guidelines, attempt to build and ensure that you receive warnings for any guidelines you’ve broken. 


StyleCop on the Build Server 

If the project team is utilising continuous build integration and you want to set StyleCop up on the build server then you can just repeat the steps above or install the application directly to the server. 

In either case you still need to create the environment variable. 

If you choose to not install the application then you will need to copy  the StyleCop folder, StyleCop.Targets and settings.stylecop files to a location on the server, the environment variable should point to the location of the StyleCop.Targets file on the build server and the UsingTask Should point to the location of the StyleCop.dll file on the build server. 

Make sure you restart the server in order for it to recognise the Environment variables. 


Warnings Vs. errors 

Out of the box, StyleCop sets warnings for any style guidelines that have been violated, we may wish to change this to errors and we can do so by setting a second environment variable.  

The details for the environment variable are outlined below: 

NameStyleCopTreatErrorsAsWarnings 
Value: False 

Again you need to restart to get any environment variable to register on either a server or dev machine.