Introducing StyleCop on Legacy Projects

  • Article

A number of people have asked for tips on rolling out StyleCop on a large, pre-existing codebase. This can prove challenging, since the tool will typically generate thousands of violations the first time it is run on existing code. For a large solution, this can make adoption of the tool a bit daunting.

On the other hand, it is relatively easy to comply with StyleCop when writing new code, especially for developers who are already familiar with the tool.

In this article I’ll describe a technique for doing a slow, staged rollout of StyleCop over your existing codebase. This technique has been used successfully by multiple teams within Microsoft, allowing them to adopt the tool in a controlled manner without generating a lot of noise up front. The general idea is to enable the tool for all of your solutions, but disable the tool from analyzing all pre-existing C# files. This provides the following advantages:

  • One day one, StyleCop will not generate any violations against your code, and will have zero measurable impact on your team.
  • Each time a new C# file is added to any project in your solutions, StyleCop will begin analyzing the code in that file. This will ensure that code in new files will be compliant from the start.
  • Over time, pre-existing files can be slowly cleaned up and introduced to StyleCop one by one.

This technique will allow your developers to slowly get used to the tool over time, without having to be confronted with thousands of StyleCop violations on day one.  

The following steps explain how to introduce StyleCop over time, as described above. At this time, this technique is only possible when running StyleCop through MSBuild integration, meaning that StyleCop runs automatically whenever a build is performed.

1. The first step is to enable StyleCop MSBuild integration for each of your existing projects, as described here.

2. After StyleCop MSBuild integration has been set up, perform a build and verify that you can see StyleCop violations in the build output.

3. The next step is to exclude all pre-existing C# files from StyleCop. To do this, each csprojfile must be edited to add an ExcludeFromStyleCop property for each C# file. Within the csproj files, edit each Compile tag as shown in the example below:

<Compile Include="File.cs"/>

Change this to:

<Compile Include="File.cs">
<ExcludeFromStyleCop>true</ExcludeFromStyleCop>
</Compile>

To make this easy, we have provided a sample tool which can do this for you. To use the tool, download the source code here, and build it in VS. This will produce an EXE called ExcludeStyleCop.exe.

Disclaimers: Keep in mind that this tool is provided as sample source code only, and will edit your project files! It is recommended that you make a copy of your source code before proceeding. This tool is only provided as a sample, and should be used at your own risk!

Running the tool with no command-line arguments will cause the tool to recursively find each C# project under the current directory, and add an exclusion tag for every C# file in every project. It is also possible to pass the path to a single csproj file on the command line, in which case the tool will only add exclusion tags for the files in that project.

4. Finally, perform a clean build and verify that there are no StyleCop violations in the build output. All C# files should be excluded now!

Whenever a new C# file is introduced to any of these projects, StyleCop will automatically begin to enforce the style of the code in that file each time the project is compiled. As more and more new files are introduced over time, developers will gain familiarity with the StyleCop rules.

As time allows, developers can clean up pre-existing files by removing the ExcludeFromStyleCop tag for a file, compiling, and cleaning up the StyleCop violations in that file.