Tuesday, May 27, 2008

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.

kick it on DotNetKicks.com

12 comments:

ILya said...

Can you tell how can I totally turn off DocumentaionRules (not for each project but for Analysis globally)? Thanks.

Ragoczy said...

Turning rules on/off either globally (for an entire machine) or for a particular directory path (parent directory) is done through the "Settings Files" tab of Source Analysis Settings.

Basically, you have a global settings file that you specify merging with your local project settings.

Paul said...

that's very helpful Paul, thanks.

Dave said...

I followed all your steps. Somehow I just didn't get the Source Analysis Tool to list my Rule. I have no idea what could be wrong.

Thanks god you also posted your code! That one works fine.

Anonymous said...

Thanks for the nice post. I have downloaded stylecop 4.2 and also downloaded PART I code and copied DLL into the to the Source Analysis install directory.

Somehow it is not working for me. Please help me to resolve this.

Ragoczy said...

Dave,

If it's not showing the rule, there's probably a mismatch in the naming between the rule class and the XML resource. Check out Part III for a description of this issue.

Ragoczy said...

Anonymous,

If you'd like to contact me via email, I'll be happy to try and help you.

lacombefr said...

For those who don't see Custom Rules in the settings window : for me, it's visible when double clicking on Settings.StyleCop file in the windows explorer, and not visible in the right click menu in visual studio !

Also, don't foget to put "Embaded Ressource" for the xml

lacombefr said...

But the problem is that I can't make it work too..

xkip said...

Looks like I'v understand the source of problem.

There are 2 deployment of StyleCop:

c:\Program Files\MSBuild\Microsoft\StyleCop\v4.3\

AND

c:\Program Files\Microsoft StyleCop 4.3.3.0\

Looks like VS use the 2-nd one. After I'v added dll to second path and restart VS, all works fine

MAJ11 said...

This is an easy to understand, amazing example.
I've tried the exact steps that were mentioned, but it doesn't seem to be working (And i also tried the solution mentioned in Part III). The source code works fine.
So i was wondering if there's something that's not mentioned...

Robb Schiefer said...

If your custom rule isn't found by the StyleCop settings editor make sure to set the target framework for your custom rule to .NET 3.5. I wasted an hour on this.