I recently posted on the evils of Microsoft.VisualBasic.MsgBox and have been looking at ways of preventing future problems to do with it. I decided on using static analysis to warn developers that they are using MsgBox rather than MessageBox.Show, so I thought I would share how I went about it.
Writing custom FxCop rules is reasonably well documented, and there are some excellent resources available for the inexperienced and experienced FxCop developer alike:
Of course the rules available in Team System and later versions of FxCop are written in .NET and therefore are very instructive to reflect using something like Reflector. However the process for writing rules can be summed up as such.
1. Decide if you are targeting FxCop or VS Team System Code analysis. Because they run different versions, you will have to compile your rules against the appropriate dll's. The good news is that development is largely the same from here on in.
2. Create a new class library project in Visual Studio and reference the FxCopSdk.dll and the Microsoft.Cci.dll. You will find these in your FxCop installation directory or in the case of VSTS you will find them in [VSInstallDir]\Team Tools\Static Analysis Tools\FxCop\.
3. Write your rule such that it inherits from Microsoft.FxCop.Sdk.Introspection.BaseIntrospectionRule. You may find it useful to create your own base rule class as I did:
using System;
using Microsoft.FxCop.Sdk.Introspection;
namespace Nervoustych.CodeAnalysis
{
[CLSCompliant(false)]
public abstract class BaseStaticAnalysisRule : BaseIntrospectionRule
{
protected BaseStaticAnalysisRule(string name) :
base(name, "Nervoustych.CodeAnalysis.Rules.Rules",
typeof(BaseStaticAnalysisRule).Assembly)
{
}
//other base class methods here
}
}
Note the string literal parameter in the constructor; it refers to an embedded XML File resource that describes the rule to the FxCop engine. David Kean has a top example of a base rule class on his site.
4. Create the aforementioned XML file and embed it as a resource in your project. The rules document uses a schema called FxCopReport.xsd which is in the Xml directory under the FxCop 1.35 installdir. Here is an example of a Rules.xml file containing one rule.
<?xml version="1.0" encoding="utf-8" ?>
<Rules FriendlyName="Nervoustych Rules">
<Rule TypeName="DoNotUseMsgBox" Category="Nervoustych.Design" CheckId="NT0001">
<Name>Full name of rule</Name>
<Description>Rule description</Description>
<Resolution Name="DoNotUseMsgBox">Resolution Description</Resolution>
<FixCategories>NonBreaking</FixCategories>
<MessageLevel Certainty="99">Warning</MessageLevel>
<Email></Email>
<Url></Url>
<Owner></Owner>
</Rule>
</Rules>
5. Write the rule. In my rule I wanted to warn developers of uses of MsgBox, so I needed to check any method calls for MsgBox:
using System;
using Microsoft.Cci;
using Microsoft.FxCop.Sdk;
using Microsoft.FxCop.Sdk.Introspection;
namespace Nervoustych.CodeAnalysis.Rules
{
class DoNotUseMsgBox : BaseStaticAnalysisRule
{
public DoNotUseMsgBox() : base("DoNotUseMsgBox") { }
public override ProblemCollection Check(Member member)
{
Method lMethod = member as Method;
if (lMethod == null) return base.Check(member);
foreach (Instruction i in lMethod.Instructions)
{
if (IsMethodCall(i)
&& ((Method)i.Value).FullName.Contains("Microsoft.VisualBasic.MsgBox"))
{
Problems.Add(new Problem(GetNamedResolution("DoNotUseMsgBox"),
i.SourceContext));
}
}
return Problems;
}
private static bool IsMethodCall(Instruction instruction)
{
if (instruction == null)
throw new ArgumentNullException("instruction");
switch (instruction.OpCode)
{
case OpCode.Callvirt:
case OpCode.Call:
case OpCode.Calli:
return true;
default:
return false;
}
}
}
}
As you can see the override to the Check method cycles through each instruction in a method and checks its operation code, to confirm if it's a method call to Microsoft.VisualBasic. MsgBox or not. If it is, then a problem is added to the collection using BaseIntrospectionRule.GetNamedResolution. If anyone could let me know a better way to do this so that I don't have to use a string literal, I would be forever grateful.
6. Build your rules project and copy the resultant assembly to either [VSInstallDir]\Team Tools\Static Analysis Tools\FxCop\Rules or [FxCopInstallDir]\Rules depending on your target platform. FxCop will pick up rule assemblies from this directory. At this point you are ready to start using your custom rule against target assembliles using either the FxCop command line, GUI or VSTS code analysis.
7. Didn't quite work? If you need to debug your rule, then you will probably want to read this.
All in all, it's not really that hard, the worst part is learning your way around the undocumented introspection engine. However reflecting the existing rules really helps, and there is a thriving community of mentors to reach out to if the going gets tough. Happy rule making.