Using StyleCop on Legacy Projects
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:
- On 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.
- The first step is to enable StyleCop MSBuild integration for each of your existing projects, as described here
Setting Up StyleCop MSBuild Integration
- After StyleCop MSBuild integration has been set up, perform a build and verify that you can see StyleCop violations in the build output.
- The next step is to exclude all pre-existing C# files from StyleCop. To do this, each csproj file 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:
Change this to:
- 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.
(Originally from the Microsoft StyleCop blog at