Part I: Creating Custom Rules for Microsoft Source Analyzer

Copyright 2008-2009, Paul Jackson, all rights reserved

Last week (May 23, 2008), Microsoft released their Source Analyzer for Visual Studio 2008 (also known as StyleCop):

http://code.msdn.microsoft.com/sourceanalysis

http://blogs.msdn.com/sourceanalysis/

Since manual code reviews for style and formatting are a huge time waster, I jumped all over this for use in my shop. Unfortunately, my coworkers can't just accept doing things the Microsoft way; they have to be a bit different, so I started investigating what was involved in creating custom rules.

Part I of this tutorial will create a basic custom rule that loads in StyleCop and add a rule violation message. It will add the rule violation for every source file, every time. In Part II, I'll explain what each piece does and then in Part III, we'll change it to actually do something useful.

The first step is to download and install the Source Analyzer from: http://code.msdn.microsoft.com/sourceanalysis/Release/ProjectReleases.aspx

The default install will go to "C:\Program Files\Microsoft Source Analysis Tool for C#" and add context-menu options to the Solution Explorer in Visual Studio 2008:

Source Analyzer uses Reflection to examine every DLL in its install directory to find custom rules, so all we'll need to do is create a class library with the right classes and attributes and Source Analyzer will automatically load our new rules.

Create a new ClassLibrary project, then add references to the Microsoft.SourceAnalysis and Microsoft.SourceAnalysis.CSharp assemblies:

Then add a new class and an XML file with the same name. Set the Properties of the XML file to be an Embedded Resource and not copy to the output directory:

The XML file should contain the following:

<?xml version="1.0" encoding="utf-8" ?>
<SourceAnalyzer Name="Custom Rules">
  <Description>
    Custom rules added to analyzer.
  </Description>
  <Rules>
    <RuleGroup Name="Custom Rules Group">
      <Rule Name="MyCustomRule" CheckId="CR0001">
        <Context>This is a custom rule.</Context>
        <Description>This is a custom rule description.</Description>
      </Rule>
    </RuleGroup>
  </Rules>
</SourceAnalyzer>

And the class should look like this:

namespace SourceAnalyzerSample
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using Microsoft.SourceAnalysis;
    using Microsoft.SourceAnalysis.CSharp;
    using System.Windows.Forms;

    [SourceAnalyzer(typeof(CsParser))]
    public class SampleAddInRules : SourceAnalyzer
    {
        public override void AnalyzeDocument(CodeDocument document)
        {
            Param.RequireNotNull(document, "document");
            CsDocument document2 = (CsDocument)document;
            if ((document2.RootElement != null) && !document2.RootElement.Generated)
            {
                AddViolation(document2.RootElement, "MyCustomRule", new object[0]);
            }
        }
    }
}

(download the source code)

Build the project and copy its DLL to the Source Analysis install directory. Now, when you run Source Analysis on a project, you should get a warning about the custom rule for every file in the project:

In Part II, I'll explain the elements of the XML file and the code; then, in Part III, I'll demonstrate a useful example.

One of the differences between the standards where I work and Microsoft's is that we require private fields to start with an underscore ("_"), while the Microsoft rules provided by StyleCop require they start with a lower-case letter and contain no underscores. So I'll be turning off the two Microsoft rules (SA1306 and SA1309) and creating a custom rule to enforce our standards.