Instant StyleCop Code Analysis How-to

In order to follow this recipe, you will need to have at least one of the following Visual Studio programs installed:

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.

Merging StyleCop settings

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.

MSBuild /version

For this recipe, you will need to have:

Whereas the auto clean up feature of Resharper helps to quickly fix a lot of violations, it won't fix all of them, and you will have to check the remaining violations manually or with the help of the fixing feature of Resharper.

If you want to know what the autofixing capabilities of the Resharper add-in are, you can refer to the following link:

http://stylecop.codeplex.com/wikipage?title=ReSharper%20Fixes&referringTitle=Documentation

You can manage the behavior of the Resharper addin in the Resharper | Option… menu. You have two menus that address StyleCop. The first is the Code Inspection | Inspection Severity menu, which allows you to change the way each StyleCop violation is displayed in Resharper.

The second one allows you to manage how StyleCop is running under Resharper, as shown in the following screenshot:

The most important part in this screen is the Analysis Performance as it allows you to control the resources allocated to the StyleCop analysis.

Though Resharper is certainly the most complete tool to autofix your violations and has the advantage of being directly supported by the StyleCop team, it's not the only program that is able to automatically correct violations. Other tools exist, and can help with StyleCop violation fixing.

For this recipe, you will need to have:

The first element we added imports the StyleCop task in the project. That's all that is really required to enable StyleCop analysis via MSBuild. The element is located just under the project root node. It can be placed anywhere as long as it's a direct child of the root node. As you can see, the path used to locate the StyleCop.Targets file is dependant of the version you installed on your computer.

In the second part, I showed you how to modify the behavior of StyleCop by adding properties in the project.

There are 10 properties that can be modified that way; I will present the three most important to me:

Here is some other information that might come in handy in certain scenarios.

<Compile Include="File.cs"/>

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

For this recipe, you need to have the following elements:

StyleCopCmd comes with a lot of options out of the box.

In the previous example, I made you give a solution file. However, StyleCop allows four kinds of entry point:

The ipf parameter allows you to remove some of the files from StyleCop scan by providing a regular expression matching their filename.

Finally, the -of option permits you to specify the name of the output file. This is used with –tf, which is used to transform the output with the help of an XSLT file. It can give you any kind of human readable report.

To get help, launch StyleCopCmd with the -? option; this will display the available options as shown in the following screenshot:

I will let you explore the remaining possibilities.

StyleCopCmd is not the only tool available to do StyleCop analysis from the command line. As we will see later, the API of StyleCop is quite easy to understand and though they don't give a command line directly, lots of projects have been made to support this functionality.

For this recipe, you will need to have:

I will assume you have already used NAnt, and I will concentrate on describing the two methods to achieve integration of StyleCop task in to your NAnt script.

In the previous sample, I tried to give you the full NAnt command. In the StyleCopCmd element we can configure six attributes:

The elements solutionFiles, projectFiles, directories, and files are used to specify the different kinds of element to analyze.

The explained method is not the only one usable to launch StyleCopCmd task. Another way to do it is to rely to the exec element of the NAnt framework. It allows you to use the command line executable of StyleCopCmd (or your own if you made it). The tool can be found at the following site:

http://nant.sourceforge.net/release/0.92/help/tasks/exec.html

For this recipe, you will need to have:

In the first part of the How to do it… section, we presented a build script. Let's explain what it does:

First, as we don't use the premade MSBuild integration, we have to declare in which assembly the StyleCop task is defined and how we will call it. This is achieved through the use of the UsingTask element.

Then we try to retrieve the previous count of violations and set the maximum number of violations that are acceptable at this stage of our project. This is the role of the ReadLinesFromFile element, which reads the content of a file. As we added a condition to ascertain the existence of the violationsCount.txt file, it will only be executed if the file exists. We redirect the output to the property StyleCopMaxViolationCount.

After that we have configured the Jenkins job to follow our project with StyleCop. We have configured some strict rules to ensure nobody will add new violations over time, and with the violation plugin and the way we addressed StyleCop, we are able to follow the technical debt of the project regarding StyleCop violations in the Violations page.

A summary of each file is also present and if we click on one of them, we will be able to follow the violations of the file.

For this recipe, you will need to have:

The template is now available in the My templates section when you create a new file.

In this recipe, we see a way to include your own licensing section in headers. If your needs are not so specific that they include a particular license, you can have a look at this site http://vstemplates.codeplex.com/, which provides some basic templates for visual studio compatible with StyleCop.

In the following paragraph we will see two others topics meant to help you manage the headers of your code files.

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>Add LGPL License</Title>
      <Author>Franck LEVEQUE</Author>
      <Description>Add LGPL License to a file</Description>
      <Shortcut>copyright</Shortcut>
    </Header>
    <Snippet>
      <Declarations>
        <Literal Editable="true">
          <ID>Description</ID>
          <ToolTip>Insert here your project description </ToolTip>
          <Default>Project description</Default>
        </Literal>
        <Literal Editable="true">
          <ID>ClassName</ID>
          <Default>ClassNamePlaceHolder</Default>
        </Literal>
        <Literal Editable="true">
          <ID>Company</ID>
          <Default>Company</Default>
        </Literal>
        <Literal Editable="true">
          <ID>year</ID>
          <Default>Year</Default>
        </Literal>
      </Declarations>
      <Code Language="csharp" Kind="" Delimiter="$"><![CDATA[// <summary>
// $Description$
// </summary>
// <copyright file="$ClassName$.cs" company="$Company$">
// Copyright (C) $year$ $Company$
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA  
// </copyright>]]></Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

Company configuration

StyleCop can enforce a specific company name and a copyright text in the copyright section. This might be useful if you want to be sure all the files of your project have the same copyright information. To do so, you need to go in the StyleCop settings in the Company Information tab.

The Company Name field corresponds to the company attribute of your copyright tag, whereas the Copyright field refers to the content of the copyright tag.

For this recipe, you will need to have:

In the early days of StyleCop, lots of the rules chosen by Microsoft were criticized. One of them was the fact that the developer couldn't add an underscore at the beginning of their private instance fields. In this recipe, we will take this rule as an example and try to implement it at the beginning of non public instance fields.

The main entry point is the AnalyzeDocument function; this is where the document will be analyzed to see if it contains any broken rules. We have two options. Either we use the visitor pattern provided by StyleCop, and in this case we have to define code walkers for the type of construction we want to check (there are four walkers available: CodeWalkerElementVisitor, CodeWalkerStatementVisitor, CodeWalkerExpressionVisitor, and CodeWalkerQueryClauseVisitor), or you can directly access the token list and check them directly. The second approach is a little trickier as upper constructions are made of one or more tokens. To use it in our example, we just have to replace the call to the visitor function by a LINQ request selecting the tokens in violation of your rule. For our sample, it will look as follows:

if (csDocument.RootElement != null && (analyseGeneratedFiles.Value || !csDocument.RootElement.Generated))
{
   Array.ForEach(
       (from token in csDocument.Tokens
        let element = token.FindParentElement()
        where token.CsTokenClass == CsTokenClass.Token &&
        token.CsTokenType == CsTokenType.Other &&
        element.ElementType == ElementType.Field &&
        element.ActualAccess != AccessModifierType.Public &&
        element.ActualAccess != AccessModifierType.Internal &&
        !token.Text.StartsWith("_")
        select element).ToArray(),
        a => this.AddViolation(
        a, 
        "NonPublicFieldsMustBeginByUnderscore", 
        new object[0]));                
}

As you can see, both ways of enforcing our rule look quite similar as we need the parent element of tokens to check easily if the token is a field and if it respects the rule. To exclude tokens of the element construct I had to add further restrictions based on the token class and token type.

When you report your violations you have to be careful of the name of the violation as any reference to an unknown rule in the XML file will just discard the violation.

In this recipe, we have seen how to implement a rule. However, you have to keep in mind that the analyzer is designed to allow you to create a set of rules, not just one. We have also seen that the central method of the analyzer is the AnalyzeDocument function; this is where you have to analyze the rule violations and report them. We also quickly see how to set some properties and use them.

However, custom tasks is a huge topic. In addition, you can customize the StyleCop setting, unit test your rules, and much more.

Customize your StyleCop settings dialog

Defining your properties in the XML file of the analyzer doesn't display them in the StyleCop settings UI. Only BooleanProperty can be shown directly using the DisplaySettings element as shown in the following screenshot:

All other properties require a custom UI. This is achieved by providing UserControl implementing Stylecop.IPropertyControlPage.

A really great tutorial is provided in the Adding a Custom StyleCop Settings Page section of the StyleCop SDK.

For this recipe, you will need to have:

Let's go to the part related to the StyleCop analysis itself; for this I will heavily rely on the code provided with this recipe:

To execute the analysis, we have to define a Configuration object, this is used to allow StyleCop to analyze preprocessor regions (for example, if you want to analyze regions marked by a #if DEBUG, you should add the DEBUG string in this object).

After that, we configure our project itself; it's the common unit under which we analyze a subset of files. It takes an ID, a base path, and a configuration.

Then we add each source file related to the project, in our case it is a temporary file made of the content of the file currently being edited.

Finally, we start the console process. The callbacks we set up at the beginning will transmit the violations and the process message to the host.

The add-in is plugged to two events of the MonoDevelop apps:

Following is the sequence diagram of the add-in:

You should have a look at the full source code to understand how the add-in really works.

The current add-in is just the beginning. It currently contains some drawbacks (first launch of StyleCop) and can be improved in many ways. Here some of them: