In this recipe, we will describe the installation process of StyleCop, learn how to configure the rules to be executed on a project, and how to launch an analysis from Visual Studio.
In order to follow this recipe, you will need to have at least one of the following Visual Studio programs installed:
Visual Studio 2008 Professional
Visual Studio 2010 Professional
Visual Studio 2012 Professional
Download StyleCop from its website (http://stylecop.codeplex.com). At the time of writing, the current version of StyleCop is 4.7 released on January 5, 2012.
Once downloaded, verify your Visual Studio is closed and launch the setup. The procedure is relatively straightforward. The only tricky part is to choose the correct components for your installation according to your use.
The wizard shows an MSBuild integration step during installation as shown in the following screenshot. Here are two pieces of advice on the installation process:
For a developer using only Visual Studio on his computer, staying with only the Visual Studio integration is fine
However, if you need to use another IDE such as SharpDevelop or need StyleCop to be used in your CI, the best approach is to add the MSBuild integration as it might be required
Once the installation process is finished, let's see what has been added to your Visual Studio.
Open a project in your Visual Studio.
Right-click on the project file in the explorer solution panel, and then click on StyleCop Settings... to open the configuration window as shown in the following screenshot:
Once you have finished selecting the rules you need, you can launch your first analysis of code.
In the Explorer solution, right-click on the project file to open the context menu, and then click on Run StyleCop… to launch your analysis. You can perform analysis on different scope by launching StyleCop in different ways:
From the Tools menu, you can perform a scan for the current C# document, or a full scan of your solution
In the Explorer solution, from the context menu, where you can restrict the scope of your analysis to the node you have currently selected
And from the coding panel, where you can analyze the code you're currently modifying.
StyleCop configuration is made on a project basis, not solution. This means you will have to specify for each project what rules and other configuration data you will use.
When opening a Visual Studio solution, you can access the StyleCop configuration from the context menu of each project in the explorer panel. You can also find configurations made this way in the Settings.Stylecop file of the project folder.
You can also use some "master" configuration files if you want to propagate the same settings in multiple projects.
Now let's talk about some useful options that are available in the settings and how to have StyleCop violations displayed in your favorite IDE if it's not Visual Studio.
Each section of rules may contain some additional configuration elements (they will be displayed in the Detailed settings region of the Rules tab.
At the moment you have additional configuration elements for the following lines:
C#: The detailed settings of this section are certainly the most important as they allow you to exclude generated and designer files from further analysis by StyleCop. This is helpful as designer files do not generally follow these rules and generates many issues.
Documentation rules: In this section, you can change the check scope of the documentation. This means you can remove the rule checking for private and internal code and you can exclude fields from it.
Ordering rules: The detailed section lets you exclude the generated code from the checks.
Earlier in this chapter, I explained that StyleCop configuration was set up on a project basis. While this is true for the standard behavior, the Setting Files tab allows you to change the default behavior and specify a setting file to merge with your current project settings as shown in the following screenshot:
Doing so allows you to have a global configuration file and depend on it for rule exclusion. If you modify any settings, they will appear in bold in the Rules tabs to show they have been overwritten.
In order to use StyleCop with Visual Studio Express or SharpDevelop, we have to enable MSBuild integration. For SharpDevelop, that is all that's required. SharpDevelop will then take care of missing lines in your project files.
However, for Visual Studio Express, you need to manually add StyleCop analysis in your project files. See the Automating StyleCop using MSBuild (Simple) recipe to know how to do this.
Once you have set up StyleCop analysis in the projects files of your solution, StyleCop violations will be displayed as warnings or errors at compile time.
Tip
Is there a way to do automate StyleCop integration for all my project files?
Since framework 4.0 it is also possible to include the Stylecop.targets file in C:\Program Files\MSBuild\4.0\Microsoft.CSharp.targets\ImportAfter\.
This will allow the integration of Stylecop.targets by default in all the project builds. If the directory doesn't exist, you will have to create it.
To be sure of version of the framework MSBuild uses, you can run the following command in your visual studio command line:
MSBuild /version