StyleCop integrates with Visual Studio, and provides a fully customizable, and reasonably-sized rule set for analyzing. Unlike its predecessor FxCop, StyleCop analyzes the actual source code instead of the compiled assembly object code, so a more thorough analysis can be obtained. StyleCop was originally developed by Microsoft. In 2010, Microsoft decided to make it open source and eventually stopped support for it. The open source community has since picked up its development. StyleCop integration now comes in a few different flavors, although it seems development is halting on all of them except the StyleCop.Analyzers project. This is the distribution my development team uses, the StyleCop.Analyzers project developed by Sam Harwell.
What's great about StyleCop.Analyzers, is it is built right on top of Code Analysis, another tool I encourage my colleagues to use. Code Analysis options used to be rather buried in older versions of Visual Studio. In Visual Studio 2017, it is reasonably easy to get StyleCop and Code Analysis set up for a project. Let's build a new C# project from scratch and take a look at what it can do.
I created a new project called CodingOnCaffeine in a new solution called CodingOnCaffeine. The first thing we need to do is install the StyleCop.Analyzers NuGet package. To do this, right-click the CodingOnCaffeine project in Solution Explorer, then click the Manage NuGet Packages… option in the context menu.
The NuGet Package Manager will be displayed. From here, click the Browse option, and type "StyleCop.Analyzers" in the search box.
Select the StyleCop.Analyzers package from the list, then click the Install button on the right side of the window.
The Visual Studio Output window should display something like the following during the installation process.
Retrieving package 'StyleCop.Analyzers 1.0.2' from 'nuget.org'.
Once the install is completed, you can now go back to Solution Explorer, expand CodingOnCaffeine Project -> References -> Analyzers -> StyleCop Analyzers to see a complete list of rules that are now being enforced on the code base. In this view, you can even customize the severity, or completely turn off individual rules to accommodate your team's style. I wouldn't recommend doing this, however, until you have selected the set of Code Analysis rules you wish to target in the project.
At this point, the autogenerated Class1.cs file that was added to our CodingOnCaffeine project by default lights up with some green squiggly notifications, and our Error List window also populates with numerous StyleCop (SA) warnings.
These will be easy to fix, but we will save that exercise for a little later in this post. There are a couple more things that need to be done to make sure Code Analysis and StyleCop are ran on the project when the solution is built.
Right-click the project again in Solution Explorer. This time click the Properties context menu option. On the project properties view, select the Code Analysis option. You'll want to select the build configurations and platforms you'll run Code Analysis on at build time. I've selected All Configurations (Release and Debug) for the Any CPU platform. Check the Enable Code Analysis on Build checkbox, and select the set of rules you will run for Code Analysis. Although I recommend getting familiar with using the Mirosoft All Rules rule set, for this example I've chosen the Microsoft Managed Recommended Rules rule set.
The next section will cover customizing the rules with a json settings file.
The StyleCop.Analyzers addon provides a convenient way to add a stylecop.json file to the project. Hover over one of the green squiggle notifications in Class1.cs to get a Light Bulb context menu. Expand it and click the Add StyleCop settings file to the project menu option.
The file allows teams to customize StyleCop's settings to accommodate their own specific needs and styles. The documentation for this file can be found on StyleCop's github. For now, we will just keep the default settings, which will enforce having "PlaceholderCompany" as the company name in our file headers.
If we go back to Class1.cs, we can start to fix the warnings listed in the Error List. For the SA1200 Using directive must appear within a namespace declaration warning, let's move all the using statements inside the namespace CodingOnCaffeine. Next, we can add a file header to the file by hovering over the green squiggle notification, expanding the Light Bulb context menu and selecting the Add File Header menu option.
Notice the "PlaceholderCompany" is inserted to the header as the company name. If the header does not contain "PlaceholderCompany" as the company, a StyleCop warning will be generated.
At this point, we should only have one StyleCop warning left for Class1.cs, regarding enabling XML output. This is done through project properties. So once again, right-click the project and click Properties from the context menu. Navigate to the Build page, and for All Configurations make sure the XML documentation file option is checked.
Note that this caused two more StyleCop warnings to appear for Class1.cs in the Error List! Both of these are related to documenting the class with XML comments. Yes, StyleCop will even force documentation! Let's type up a quick summary so StyleCop is satisfied.
/// Defines a class used for testing StyleCop compliance.
Finally, Class1.cs is StyleCop compliant. However it looks like AssemblyInfo.cs has a warning about a missing file header. Let's use the same technique there and insert a header in that file as well. Now let's do a rebuild. Should be squeaky clean with no warnings. Nice!
Because of its fluid integration with Visual Studio and the build process, StyleCop is a great tool for teams to utilize when they are looking for a way to automate code style enforcement. Tools like StyleCop and Code Analysis can be fully customized to accommodate a team's style preferences. I hope this article was helpful in getting your team started on adopting and enforcing code styles through StyleCop.