I may have joined the wrong side : FxCop

A statistics collection tool for FxCop backlogs

calinoiu — Fri, 15 Feb 2008 20:21:00 GMT

For the past week or so, I've been performing last-minute documentation tasks at the day job in preparation for the impending maternity leave. If you've been reading this blog because of my FxCop posts, then you might be interested in my latest post on the FinRad blog, which covers the statistics collection tool that we developed internally to help us track our FxCop backlog cleanup efforts. A copy of the tool is also available on CodePlex if you would like to try it out for yourself.

Some FxCop rules for VB

calinoiu — Sun, 03 Jun 2007 13:34:00 GMT

We've got a rather large VB code base at FinRad, at least some of which we would like to migrate to C# in the nearish future. Because of this, we have created several custom rules that are intended to detect issues in VB code that would cause problems when migrating the code to C#. However, while attempting to assign categories for those custom rules, we quickly realized that each of them had merits besides portability of the code base, and that we wanted our assemblies to abide by these rules regardless of whether or not they might eventually be ported to C#.

I hadn't been planning on writing a post about these rules for some time to come, but then I saw the announcement last week that Microsoft is using VB to build the Silverlight javascript compiler and VBx, which seems to have boosted the topic's prority on my internal TODO list enough that I can't quite seem to ignore it...

Rule #1: Interfaces should not contain nested types (Design)

By definition, interfaces should not contain any implementation, and a nested type would certainly qualify as implementation. Unfortunately, the VB compiler generates no warnings or errors when any type whatsoever is nested within an interface. For example, the following interface will compile just fine (and FxCop won't flag it as an "empty" interface either):

Public Interface ISomething

	Enum Animal
		Cat
		Dog
		Fish
	End Enum

	Class SomeClass
		Public Sub DoSomething()
			Console.WriteLine("something")
		End Sub
	End Class

End Interface

To make matters worse, the VB compiler will also generate a type within an interface under certain conditions. Consider, for example, the following interface:

Public Interface ISomethingElse

	Event SomethingDone(ByVal sender As Object, ByVal e As EventArgs)

End Interface

When an event is declared using the above syntax, the VB compiler will generate a delegate for the event signature within the same parent type. The resulting compiled assembly actually ends up containing the following interface definition, which includes a nested type:

Public Interface ISomethingElse
    
    Delegate Sub SomethingDoneEventHandler(ByVal sender As Object, ByVal e As EventArgs)
    
    Event SomethingDone As SomethingDoneEventHandler

End Interface

Rule #2: Properties should not have arguments (Design)

In order to be easily invokable from C#, a property should never have more than one argument, and only indexers (i.e.: properties named "Item" in VB) should have even one argument. If either of these conventions are ignored, C# code is going to have to use syntax like get_SomeProperty(a, b, c) to use your properties, which is considerably less readable than some of the alternatives. Do you really want to be forcing your API's callers to be writing ugly code?

Rule #3: Member names should not match type names (Naming)

C# will generate compiler error CS0542 if you try to create a member with the same name as its parent type, but VB won't complain about this at all. The use of a member with the same name as the type to signify a constructor in C# presumably explains this difference in compiler behaviour. However, there's an API useability problem here as well since this significance of a member (usually a property) with the same name as its parent class is rarely immediately obvious. For example, imagine a class named "Label" with a property named "Label". What exactly does "Label.Label" represent? In such a case, either the class or the member probably ought to be renamed to convey more information about its role.

Rule #4: Review call scope forcing (Usage)

VB allows for forcing the scope of invocation of a virtual member to the current class via the MyClass keyword. Both VB and C# allow for forcing the scope of invocation of a virtual member to the base class (via MyBase and base, respectively). Since call scope forcing isn't really a VB-specific capability, this isn't really a VB-specific rule. However, eliminating MyClass use was what provoked its development at FinRad, so I'm including it here anyway.

In case you're wondering why call scope forcing should be reviewed, consider why a member would be declared as virtual in the first place: it's meant to be overrideable. If a subclass has overridden a virtual method, why should a base class be deliberately avoiding invoking that override? Obviously, there are cases where this behaviour is desirable, which is why this is a "review" rule rather than a "do not" rule, but there are also plenty of cases where scope forcing is likely to be used inappropriately, particularly when developers aren't aware of the consequences.

If you want to implement this rule, there are a few things to watch out for:

Within the implementation of an overriding, overloading, or hiding member, it is quite common to invoke the base class implementation explicitly. In order to avoid undesirable noise in the rule analysis results, these cases should not be flagged as problems by the rule.
Because of VB interface member implementation renaming, the name of an overload will not necessarily be the same as the name of the member it is overloading.
The C# compiler will force a non-virtual call when invoking a non-virtual base class member even if your code uses this rather than base to scope the call. The VB compiler will retain the virtual call.
FxCop 1.35 and Visual Studio 2005 Static Analysis both have problems detecting whether a property is overriding and/or hiding, although the exact behaviour differs between the two engines, as well as between .NET 1.1. and 2.0 assemblies for FxCop 1.35. For more details on this issue (which appears to have been resolved in Orcas), see this bug report.

FxCop backlog tools: FxCop

calinoiu — Sat, 02 Jun 2007 13:07:00 GMT

If you're considering tackling an FxCop backlog, you're going to need a few tools. Obviously, the most important of these is FxCop itself, but that still leaves you with a potential choice to make between stand-alone FxCop and Visual Studio Static Analysis. If your target code base is built against .NET 1.1 or if you're not willing/able to shell out for Team Edition for Software Developers or Team Suite, the decision is pretty trivial. However, what if all your developers already have Visual Studio 2005 editions that include static analysis? You've paid for it, so your first instinct will probably be to use it. Unfortunately, it's probably not the best tool for this particular job.

While VStudio Static Analysis is great for dealing with a small volume of problems that should be addressed immediately, it kind of sucks the big wazoo with respect to handling the much larger volume of violations that one needs to deal with while tackling a backlog. This is partly a UI issue, and it shouldn't come as much as a surprise given that the backlog scenario probably wasn't exactly a major priority during the development of the VStudio integration piece. However, there are also some issues that go beyond the limited capabilities of the Visual Studio Error List window, and it's important to be aware of these as you make your tooling decisions.

In order to help understand why the stand-alone tool will likely be a better choice, let's take a closer look at some of the tasks in the backlog winnowing process...

Fix this

You've decided to activate a given rule. Your code base has 400 existing violations of the rule, and you want your team to start fixing those right away. However, you certainly don't want to have to specifically assign each and every fix to a given developer. How do you create a "pool" of violations from which developers can draw?

If you're using Static Analysis and you also happen to be using Team Foundation Server, you might want create work items for the violations, then let developers assign the work items to themselves before starting to work on the fixes. However, from the VStudio Error List, you're going to able to generate work items in only one of two ways:

Select all the violations, then generate a single work item, or
Generate a work item for each violation individually.

Generating the individual work items would be ridiculously time consuming and tedious, so a single work item would usually be the only practical choice. However, in order to ensure that the more than one developer isn't working on any given violation at the same time, there's still going to have to be some manual work in terms of copying and editing work items before a developer will even start fixing a violation. Unfortunately, this procedural overhead doesn't really have much added value besides preventing overlapping work, and the additional effort may end up accounting for a very large proportion of the time spent on any given fix. Wouldn't you rather use that time for fixing other violations instead? (Of course, you could create a tool that automatically creates individual work items for you based on an FxCop output report, but that's again time that might be better spent doing other things.)

Another problem with adding backlog work items to TFS from VStudio Static Analysis results is that they're going to end up in the same TFS project as all your "real" work items for the same code base. Assuming your Static Analysis backlog is non-trivial, these backlog work items will start to swamp out your other feature and bug fix work items pretty quickly. Sure, you can isolate them in a category of their own, but sooner or later someone is going to include those beasties in a report where they shouldn't belong, and your stats are going to be skewed halway to heck.

OK, so if those are problems with using Static Analysis for violation reservation, what can the cheapskate's standalone edition do better? For starters, we can mark all the violations for fixing in one step without requiring later splitting. After activating a new rule and executing an analysis, simply select all the newly active violations of the rule and exclude them with a "TODO" note. If you're feeling fancy, you can even add a priority level (e.g.: "TODO 1" or "TODO 2"). After excluding the pre-existing violations, simply check the FxCop project into source control, and all the developers on your team can instantly access the items.

Under the "TODO" exclusion scheme, it's equally easy for any given developer to grab himself a chunk of new backlog work. He simply selects a bunch of violations from those that still have "TODO" notes, adds a new note (in one step) to claim all of them, then checks the modified FxCop project back into source control. What's this new note that gets added for the claiming? At FinRad, we simply add our initials to the note. For example, I claim violations by adding the note "TODO - NC" to an unclaimed TODO exclusion. If you've got a bigger team, you might need to identify developers by somewhat longer strings than their initials, but the underlying technique should still work.

Using stand-alone FxCop and TODO exclusions, I can both create and reserve violation "work items" in seconds, so I can spend more time on actually fixing violations rather than on managing the workload itself.

Don't break that

Identifying the current workload is only part of managing the violation backlog. Another important part is ensuring that the backlog violations that have not yet been fixed don't break your builds (assuming, of course, that you're using automated builds and that you've set FxCop rule violations to break those builds). If you're using VStudio Static Analysis, you've got two basic options for doing this:

Set the rule to not break the build until after all the backlog violations are fixed or
Use SuppressMessageAttribute to exclude the pre-existing violations.

If you don't allow violations of the newly activated rule to break the build, you won't start detecting new violations of the rule until after you've cleaned up the entire backlog, and that's not pretty. On the other hand, if you add a SuppressMessageAttribute to any given pre-existing violation, that violation will no longer show up in the Error List, so it's going to start being difficult for your team members to find and fix the problem.

Another problem with the SuppressMessageAttribute exclusions approach is that VStudio Static Analysis doesn't let you know when you don't need a suppression anymore.¹ This means that if you fix the original violation but forget to remove the attribute, you could later create another violation of the same rule in the same code element, and you'll never notice it because the old placeholder exclusion will hide the new problem. That's a nasty enough problem even when you have a small number of "real" exclusions, but it's asking for big trouble when you consider the very large number of suppressions that you would need to create for your backlog violations.

This is another problem for which a much cleaner, simpler solution is possible when using the FxCop stand-alone UI. In fact, we've already covered the approach above. Since we create a "TODO" exclusion for every violation in the immediate backlog, we can keep the rule activated and build-breaking while still readily identifying the backlog violations. The stand-alone UI also allows us to detect exclusions that are no longer needed, so we can remove the unecessary exclusions in batches even if individual developers forget to remove them when fixing a violation.

On a bit of a side note, if you happen to be running a backlog cleanup of a .NET 2.0 application, you will probably want to store only your TODO exclusions in the FxCop project file. If you happen to resolve a violation by creating a "real" exclusion, that exclusion should probably be created with SuppressMessageAttribute rather than in the FxCop project file. After all, one of these days, you'll actually finish tackling the backlog, and you may want to switch over to using VStudio Static Analysis for finding and addressing the piddly few rule violations you'll be generating in your day-to-day work.

Sorting, filtering, and other fancy-pants advanced techniques

So let's say you're a developer who is ready to give an hour or so to fixing some of the backlog problems. How to you select which ones to work on? If you simply grab a random assortment, you'll probably end up working on violations of a variety of different rules that are widely separated with respect to location in the source code. You'll very likely end up wasting time on context switching that could have been put to much better use actually fixing violations.

As a more concrete example, let's say you decide that you have time to fix about 30 violations of the Performance.RemoveUnusedLocals rule. Trivial as these might seem, chances are that you'll probably find that somewhere between 10% and 20% of the violations actually require some decisions and maybe even a bit of code spelunking. This is why you won't try tackling 3 or 4 violations per minute, but it also has another consequence. If you're going to be encountering "weird" violations, wouldn't it be nice if they're mostly of the same style? One way of trying to increase the probably of this would be to draw the violations from a smallish area of the code base, where you'll at least stand a reasonable chance of encountering mostly code authored by a single developer.

While selecting violations using the above pattern is certainly possible from the VStudio Error List, it's not terribly convenient, and it's certainly not something that most of your developers are likely to enjoy doing several times a week. Developer patience with the selection process is likely to fray even faster if you're using TFS to store the backlog work items. To make things worse, you'll again be wasting time that could be better spent on actually fixing violations.

On the other hand, making the same issue selection in the stand-alone FxCop UI is trivial. First, I select the Performance.RemoveUnusedLocals rule in the rule treeview to hide violations of any other rule. Then I sort the "Excluded In Project" list by the item column. Since I can see availability of items in the "Last Note" column, all I have to do is select a bunch of violations that are clustered close together by item path in order to increase the chances of similar types of weirdness in the problems that I'm going to address.²

But I don't like the extra step involved in running FxCop...

Let's step back a moment and look at the usual reason for preferring VStudio Static Analysis: it runs seemlessly as part of the build process. Even ignoring the backlog problem, there's another nasty gotcha here: duration of a static analysis run. It takes over 3 minutes to analyze the assemblies in the product on which I work day-to-day. Given this, I'm certainly not going to run an analysis as part of my usual debug builds, whether it's via the integrated Static Analysis tool or by launching FxCop via a post-build event. If I really want the analysis to be associated with a build, I'm going to have to create an alternate build configuration at the very least.

This means that, even if I'm targeting the integrated tool, I'm still going to be launching analyses via a conscious, at least partially manual step. With one little extra step (clicking the "Analyze" button within the FxCop UI), I can run the analysis in the richer, otherwise more convenient stand-alone UI instead. To make this rapid launch possible, I simply add my FxCop project file to my solution as a solution item, then configure Visual Studio to open FxCop files using FxCop.exe. Once this initial setup is done, all I need to do to run my FxCop analysis is open the FxCop project from within Visual Studio then click the "Analyze" button once the FxCop UI has opened (to watch a 700K demo video, click here). That's amply convenient for me, although I guess your mileage may vary (but only if you're a complete nut <gdr>).

But that Static Analysis thingy cost me 5000$ (per seat) !!!

If you've bought one of the Team System editions that includes static analysis, I very much hope that you're taking full advantage of it for your new development work. I also hope that static analysis isn't the only "extra" feature that you're using, or perhaps you did spend rather a lot for one feature. ;) Either way, the fact that you happen to have the integrated static analysis tool available to you shouldn't be an important factor in making a decision regarding which FxCop tool to use for your backlog cleanup project.

On the other hand, the integrated tool ships with some rules that are not available in the free version of FxCop, and you might be swayed toward using that tool in order to take advantage of the additional rules, particularly given that FxCop 1.35 and Visual Studio 2005 Static Analysis cannot consume each other's rules. However, what you may not know is that FxCop 1.35 also shipped with some rules that aren't present in the integrated static analysis rule set³. The following table lists the rule set differences:

Category	FxCop 1.35	Visual Studio 2005
Design	ExceptionsShouldBePublic
Maintainability		AvoidExcessiveComplexity AvoidExcessiveInheritance VariableNamesShouldNotMatchFieldNames
Naming	CompoundWordsShouldBeCasedCorrectly FlagsEnumsShouldHavePluralNames IdentifiersShouldBeSpelledCorrectly OnlyFlagsEnumsShouldHavePluralNames ResourceStringCompoundWordsShouldBeCasedCorrectly ResourceStringsShouldBeSpelledCorrectly
Performance	RemoveEmptyFinalizers
Reliability		DisposeObjectsBeforeLosingScope DoNotLockOnObjectsWithWeakIdentity DoNotTreatFibersAsThreads RemoveCallsToGCKeepAlive UseSafeHandleToEncapsulateNativeResources
Security	CatchNonClsCompliantExceptionsInGeneralHandlers SecurityTransparentAssembliesShouldNotContainSecurityCriticalCode SecurityTransparentCodeShouldNotAssert SecurityTransparentCodeShouldNotReferenceNonpublicSecurityCriticalCode
Usage	AttributeStringLiteralsShouldParseCorrectly LiteralsShouldBeSpelledCorrectly TestForNaNCorrectly

If you're seeking to maximize your rule coverage, jumping on static analysis because it supposedly contains more rules isn't exactly looking like an optimal approach... If you want to cover the combined rule set offered by the two tools, I'd recommend using FxCop 1.35 for your backlog cleanup until you've exhausted all of its rules. Once that's done, you would potentially be faced with a decision of switching over to the integrated tool for the remaining rules or coding custom rules for FxCop 1.35 that check for the same problems as the additional rules shipped with Visual Studio.

Then again, is that really a decision you're likely to end up facing? Assuming you start a backlog cleanup now, when do you think you're likely to be almost done? Unless your backlog is trivial, chances are excellent that both Orcas and FxCop vNext will have shipped by the time you're even half way done. Personally, I'm hoping that Orcas static analysis and FxCop vNext will be able to consume each other's rules, thereby making it possible to use the richer UI when addressing a backlog of the Visual Studio rules, as well as easing some of the pain around custom rule authoring. There's no technical reason why they shouldn't be able to consume the same rules, but that doesn't mean that a difference couldn't be introduced explicitly in order to prevent using the expensive rules from the free tool. I'm keeping my fingers crossed that this won't happen, although I won't start counting any chickens until Orcas and FxCop vNext have both RTMed...

¹If you wish VStudio Static Analysis and/or FxCopCmd.exe would let you know when you've got unecessary suppressions, vote here.

²If FxCop wouldn't "lose" the rule selection when switching between the rules and targets treeviews, it would be possible to make an even more convenient selection by "climbing" the target treeview from the target associated with any given violations. Unfortunately, the rule selection is lost when switching to the other treeview tab in FxCop 1.35. I'm keeping my fingers crossed that this won't be the case in the vNext UI, but there seems little point in creating a bug report until I've actually tried the beastie. I'm also hoping that the vNext UI will allowing filtering by column values within the violation lists, which would also make working with large backlog lists more convenient, but I won't be holding my breath for that change.

³In case you're not already aware of this, the Visual Studio rule set is supposed to be a superset of the stand-alone FxCop rule set. FxCop 1.35 only contains rules that aren't present in Visual Studio 2005 because of time constraints during the preparation of Visual Studio 2005. (Sorry, but the best reference I seem to be able to find regarding this at the moment is a post on the FxCop forum.) The extra FxCop 1.35 rules are present in Orcas, with the exception of Usage.LiteralsShouldBeSpelledCorrectly, which is a control flow rule.

FxCop backlog themes: Disposition and finalization

calinoiu — Wed, 16 May 2007 19:44:00 GMT

I skipped ahead a while back with my post on the exceptions theme, and it's time to get back on track with stuff that would usually precede that rather involved topic during an FxCop backlog cleanup project.

The good news with the disposition and finalization topic is that its scope is quite a bit narrower than the exceptions topic. The bad news is that you'll probably see almost as many preconceptions regarding how it works, particularly if you have quite a few developers who are accustomed to deterministic finalization. As with the exceptions topic, it's probably a pretty good idea to start the topic from scratch, making the assumption that most of the developers on your team will get at least something from coverage of even the fundamentals of the subject matter.

Resources

This time around, Chris Brumme's post on finalization is absolutely required reading, at least for the topic trainer. If you don't understand at least 90% of that article, you probably don't know enough about finalization to be teaching the topic.

You'll also need some resources that are more on the "how to" side of things. The MSDN articles Implementing Finalize and Dispose to Clean Up Unmanaged Resources and Implementing a Dispose Method to provide a reasonable starting point around guidelines for finalization and disposition. By the time you complete your training on finalization and disposition, all the developers on your team should be able to read and understand these articles.

Some gotchas

By and large, the documentation available is pretty clear, and the recommended practices are relatively unambiguous. However, we did run into a few picky detail issues while tackling the disposition and finalization theme at FinRad:

In a disposable class that contains a collection of disposable items, how does one deal with exceptions that might be thrown during the disposition of any individual item?
The issue here is that one wants to continue disposing of any remaining items even if an exception is thrown while disposing of any given item. However, one still wants to throw an exception out of the parent class Dispose method. The question here is exactly what should one end up throwing? One answer is to store any exceptions into some custom exception that contains an exception collection, then throw the resulting beastie at the end of the process. Unfortunately, there are several problems with this approach, not least of which is that the original Dispose method caller isn't likely to be want to iterate over the exception collection trying to decide what to do about each and every one of the member exceptions.

What we ended up deciding to do instead was to treat disposition of each individual collection item as if it we were disposing a field on the parent class. In other words, we wanted to expose the same exception scenario that would be seen if we were able to code the parent Dispose method like this:
```
try
{
	this._someDisposableField.Dispose();
}
finally
{
	try
	{
		this._someOtherDisposableField.Dispose();
	}
	finally
	{
		try
		{
			this._collectionOfDisposables[0].Dispose();
		}
		finally
		{
			try
			{
				this._collectionOfDisposables[1].Dispose();
			}
			finally
			{
				...
			}
		}
	}
}
```
If one were able to do this, the only exception the caller of the parent class Dispose method would see is the last exception thrown in any of the individual try blocks. This is quite easy to simulate even while disposing in a loop. e.g.:
```
try
{
	this._someDisposableField.Dispose();
}
finally
{
	try
	{
		this._someOtherDisposableField.Dispose();
	}
	finally
	{
		try
		{
			Exception lastException = null;
			foreach (IDisposable item in this._collectionOfDisposables)
			{
				try
				{
					item.Dispose();
				}
				catch (Exception ex)
				{
					lastException = ex;
				}
			}

			if (lastException != null) throw lastException;
		}
		finally
		{
			GC.SuppressFinalize(this);
		}
	}
}
```
Is this ideal? Obviously not, but I happen to believe that it presents less problems than any of the alternatives. If you think you have a better approach, I'd love to hear about it.
What exactly is an unmanaged resource?
The basic rules for implementing disposition and finalization are the following:
- If a class has a disposable field, it should disposed from the Dispose method of the parent class.
- If a class has a field that represents an unmanaged resource, this should be released from both the Dispose method and the finalizer of the parent class.
The first rule is pretty unambiguous, but what exactly qualifies as an "unmanaged resource" that should be released both on disposition and finalization of the parent class? Most of the articles on disposition and finalization make some airy-fairy mention of things like database connections and file handles, but does that mean a SqlConnection should be disposed in the parent class finalizer? The simple answer is "no". The barely more complicated answer is pretty much the only things you should be cleaning up during finalization are IntPtr fields. If you've gone beyond IntPtr to start using SafeHandle in .NET 2.0, you don't even need worry about those since the unmanaged handle is already wrapped in a disposable, finalizable managed object.
There's no framework design guideline with respect to interface inheritance from IDisposable, but there probably ought to be.
Interfaces that are likely to be implemented by types that will need to be disposable should themselves be disposable. This is because you don't want to end up having to write code that looks like this:
```
IShouldBeDisposableButIsNot thingy = Factory.CreateThingammy();
try
{
	//...
}
finally
{
	IDisposable disposableThingy = thingy as IDisposable;
	if (disposableThingy != null) disposableThingy.Dispose();
}
```
Instead, you want to be able to simply write code like this:
```
using (IShouldBeDisposableAndIs thingy = Factory.CreateThingammy())
{
	//...
}
```

The built-in rules

Here are the built-in rules that you'll want to start activating during the disposition and finalization theme:

Category	Rule	In FxCop 1.35?	In VStudio 2005?
Design	ImplementIDisposableCorrectly	x	x
	TypesThatOwnDisposableFieldsShouldBeDisposable	x	x
	TypesThatOwnNativeResourcesShouldBeDisposable	x	x
Performance	DisposeMethodsShouldCallSuppressFinalize	x	x
Performance	RemoveEmptyFinalizers	x
Reliability	DisposeObjectsBeforeLosingScope		x
Usage	DisposableFieldsShouldBeDisposed	x	x
	DisposableTypesShouldDeclareFinalizer	x	x
	DisposeMethodsShouldCallBaseClassDispose	x	x
	DoNotDisposeObjectsMultipleTimes	x	x
	FinalizersShouldBeProtected	x	x
	FinalizersShouldCallBaseClassFinalizer	x	x

Some custom rule ideas

We haven't created any custom rules yet around finalization and disposition at FinRad, but there are at least a couple that I would like to implement eventually:

IDisposable.Dispose should be called from within a finally block (and the only other code in the finally block should be a cast to IDisposable)
An interface with at least one disposable implementation should itself be disposable

That last one is bound to be interesting to try to author, but I've got loads of time to figure out how to implement it since there are quite a few more important rules to tackle first...

FxCop is case-sensitive. VB is annoying.

calinoiu — Tue, 08 May 2007 03:30:00 GMT

With profound apologies to VB lovers, there are a few features of the VB compiler that occasionally make me want to start drinking at a very early hour of the day. Perhaps the most troublesome of these is its failure to start screaming bloody murder upon detection of namespaces that differ only by case, even while compiling an assembly that is marked as CLS-compliant. VB 2005 is at least kind enough to conserve the casing from the source code. However, VB 2003 seems to more or less randomly pick one case version and apply it throughout an assembly, and that leads to all sorts of fun and games.

If you've developed mixed VB and C# solutions, chances are pretty good that this isn't exactly news to you since C# tends to get mighty unhappy the resulting changes in namespace casing. However, you might be blissfully unaware that FxCop is also case-sensitive, and that has its own special set of consequences...

At FinRad, we're still supporting applications that run against .NET 1.1 (and will be for at least a couple more years), and a very large part of that code base is written in VB 2003. Given that this is .NET 1.1 code, we're using the stand-alone version of FxCop for static analysis, and exclusions are stored in the FxCop project file, not as SuppressMessageAttribute annotations in the source code.

Given that this also happens to be the same code base covered by the bulk of our backlog cleanup efforts, the FxCop project files contain an unusually large number of exclusions. (I'll write about the reasons for this soon. For now, just trust me: lots more violation exclusions than you might normally expect.) Every now and then, we would end up with a situation where a sizeable chunk of our exclusions would suspiciously disappear, and all the violations they covered would auto-magically become active again. Needless to say, this was terribly annoying, but we chalked it up to gremlins, manually re-created the exclusions, and forged bravely ahead.

A few weeks ago, we hit a really weird problem where an automated build running on an integration server was detecting active FxCop rule violations that couldn't be duplicated on any developer machines. Several of us tried clean check outs, rebuilding, etc., but without any success at reproducing the problems seen in the automated build. In retrospect, it seems painfully obvious, but the namespace casing problem (which also tended to raise its ugly head in a Visual Studio vs. automated build disjunction with respect to C# callers) didn't occur to me until I was stuck in traffic that evening. It was the first thing I checked the next morning and, sure enough, the exclusions were registered under the "Something" namespace, but the classes compiled in the automated build now fell under the "SomeThing" namespace.

Some lessons learned:

FxCop is case-sensitive.
The gremlins actually lived in the VB compiler. (Luckily, they've been evicted, but the nasty smells are lingering.)
Giving an "aha!" smack to one's forehead while stuck in traffic will earn some very concerned looks from drivers of neighbouring vehicles.

FxCop backlog themes: Exceptions

calinoiu — Sat, 05 May 2007 16:31:00 GMT

Since I started monitoring traffic on this blog a little more closely about a week ago, I had the unexpected surprise that the posts on HTML encoding and server vs. client cultures were getting a lot more hits than I expected. I had been planning on starting a series of "how to" posts on those topics this weekend, but that was before David Kean from the FxCop team was kind enough to direct a bunch of folks my way with a post about my recent FxCop posts. Since it would seem that I've now got quite a few new subscribers who are interested in FxCop, I figured I might as well continue on that theme for a while...

Jumping the gun

I've got exception stuff on the brain this morning, so that's what I'm going to write about. However, if you have decided to tackle an FxCop backlog, exceptions are probably not the first major theme you should cover. Then again, even assuming that my recent posts have inspired you to immediately start a backlog winnowing project, you should still be at least a month away from covering any major theme. I'm going to try to write about the much easier disposition and finalization topic within the next couple of weeks. Heck, it might even happen tomorrow morning if I don't get coerced into some sort of housework. In the meantime, just keep in mind that the sequence in which I end up covering the topics here isn't necessarily the sequence in which you'll want to cover them in your backlog process.

Starting from scratch

Unless your team already has very specific guidelines in place around the generation and handling of exceptions (along with training and code reviews to reinforce those guidelines), it's pretty safe to assume that there is a very wide variety of exception treatment in your code base. In addition, the developers on your team likely have similarly disparate understandings of when and how exceptions ought to be generated and handled. Instead of jumping right into covering the existing FxCop rules around exceptions, it would probably be a much better idea to start with some training around the basics of exceptions. Chances are excellent that individual developers will be carrying quite a bit of baggage based on their experiences with exception treatment in other languages or platforms, and you will most likely need to devote quite a bit of time to dispelling inappropriate preconceptions.

Here are a few resources that you may wish to consult during your exception training:

The .NET Framework Design Guidelines for Exceptions
Some parts are a bit outdated, and the formatting doesn't necessarily make for easy reading, but this is probably still the best place to start.
The .NET Framework Developer's Guide to Handling and Throwing Exceptions
Some parts are very basic, but the Best Practices for Handling Exceptions section is good complement to the design guidelines.
Krzysztof Cwalina's posts on exceptions
Most of the information contained in these posts ought to be in the official design guidelines documentation on MSDN. Unfortunately, since the latter content doesn't seem to get updated all the often, you'll need to read Krzysztof's posts as well.
The FxCop team FAQs on which exception types to throw and why you should catch System.Exception
By a stroke of luck, the "what to throw" FAQ came out just as we were wrapping up the exceptions topic at FinRad, which saved me the trouble of writing a very similar set of guidelines for internal consumption.
Rico Mariani's posts on the costs of exceptions
This content is helpful if you're trying to understand the cost of exception handling, but watch out for a bit of performance-oriented bias. If you're concerned about the usability of your APIs, you'll probably end up wanting to throw exceptions a little more often than Rico might like. ;)
Chris Brumme's post on the exception model
Interesting as it is, this isn't likely to be required reading for most folks on your team. However, it is something you might want to read if you're going to be the one giving the training on the exception topic.

If you're concerned about globalization and localization issues, you might also want to have a look at my post on client vs. server cultures. The disparity between application user and administrator languages can present challenges when emitting localized exception messages for any application, and it's something you may wish to consider as you develop your internal exception generation guidelines, even if you don't happen to be writing web applications.

The built-in rules

As part of the exceptions theme, you'll want to start activating the FxCop rules that touch on exception generation and handling. The following table lists the rules available in FxCop 1.35 and Visual Studio 2005 static analysis:

Category	Rule
Design	DoNotCatchGeneralExceptionTypes
Design	ExceptionsShouldBePublic¹
Security	CatchNonClsCompliantExceptionsInGeneralHandlers¹
Security	WrapVulnerableFinallyClausesInOuterTry
Usage	DoNotRaiseExceptionsInFilterBlocks
	DoNotRaiseReservedExceptionTypes
	InstantiateArgumentExceptionsCorrectly
	RethrowToPreserveStackDetails

I suppose that it could be argued that Usage.DoNotIgnoreMethodResults might also be worth including while activating exception rules. If your team is resistant to the idea of throwing exceptions instead of using failure return codes, then a bit of time cleaning up violations of this rule might be just the thing to convince them. Otherwise, it's probably safe to activate this rule whenever it otherwise seems reasonable during your backlog process. If you're following the guidelines, you'll probably want to fix most violations of this rule by modifying the invoked method to throw exceptions rather than return a status code, which is a breaking change for public methods, and scheduling breaking changes can be a wee bit tricky.

Custom rules

If you've read the design guidelines concerning exceptions, it should be pretty obvious that the above eight rules don't exactly cover all the potential problems for which you might want to screen. Here are a few custom rules for exceptions that we're either already using at FinRad or will be introducing once we get a little further along in the backlog cleanup:

Do not throw System.NotImplementedException
Pretty obvious, although you'll occasionally need to create temporary exclusions, particularly for when someone checks in a class skeleton to be fleshed out by somebody else. Also, as a bit of side note, when you introduce this guideline, you might want to stress that the exception signifies that the code is not implemented yet, not that it's not implemented here. For "not implemented here", you should be using System.NotSupportedException instead.
Methods that throw System.NotSupportedException should not include other instructions
Simple as it might seem, this rule is a bit tricky to author since the VB compiler has the nasty habit of adding extra instructions (e.g.: return statements) to methods. Also, one needs to keep in mind that a custom message might be provided for the exception, and that message might be retrieved via a method call.
Throw System.ComponentModel.InvalidEnumArgumentException for an invalid enum argument value
Not really relevant to the rule itself, but it's really annoying that this particular exception lives in the System.ComponentModel namespace rather than System.
An argument exception should be thrown directly from the method whose argument is being validated
I had hoped that the parameter name verification on Usage.InstantiateArgumentExceptionsCorrectly would cover this issue but, after looking at the rule logic via Reflector, I've decided that a custom rule is going to be need for this one. I'm planning on activating it at the same time as Design.ValidateArgumentsOfPublicMethods (which will definitely be happening before we move to Orcas <gdr>).
Use recommended exception logging methods
In order to make logged exceptions more noticeable, we decided to create a new helper method that is capable of writing exception details to both a central repository and whatever target location was previously used. The decentralized logging problem was the consequence of an application architecture that you may not share, so this might not be particularly relevant for your team. However, if you do have similarly decentralized logging, you may want to consider a similar approach. If you do decide to add a special exception logging method, then you'll probably also want to add a custom rule to verify that it's being used.
Review use of System.Diagnostics.Debug methods
Some folks have a tendency to use Debug.Assert or Debug.Fail where they really ought to be throwing exceptions.
Review catch without throw
Last but definitely not least, this is our "do not eat exceptions" rule. Unfortunately, fixing an undesirable violation of this rule can be very time-consuming, but discovering places where an application is hiding exceptions has tremendous impact on reliability, and the short-term cost is well worth the long-term benefit.

Personally, I'd love to see at least the more generally useful rules from the above list make it into the rule set shipped by Microsoft. I seem to remember seeing something from the code analysis team that promised some new rules around exceptions for Orcas, but I can't find it anymore, and I haven't seen any new exception rules either. It's a pity, because I was really hoping to get rid of my custom rules, particularly the less than ideal verification for other instructions in methods that throw System.NotSupportedException...

¹This rule is not available in Visual Studio 2005, but it is shipped with both FxCop 1.35 and Orcas beta 1.

FxCop backlogs: Some rules for rule activation

calinoiu — Sun, 29 Apr 2007 14:38:00 GMT

If you've decided to try to tackle an FxCop violation backlog, one of the first issues you're going to face is deciding which rules to activate when. Here are some general guidelines...

Starting out

When you first begin the backlog clean-up process, you're going to need to introduce the FxCop tool to your team (assuming, of course, that you're not already using FxCop for new projects). In order to focus on mastering the tool and the cleanup process before diving into "difficult" rules, you'll want to pick a few rules to activate that meet the following criteria:

The rule itself should be easy to understand with minimal background explanation.
Violations of the rule should be easy to fix.
Your code should contain very few violations of the rule.

My favourite introductory rule is DoNotConcatenateStringsInsideLoops. Unfortunately, it's slated to disappear in Orcas, so you might want to get a start on that backlog cleanup soon if you want to use it. ;) For finding other candidate "early" rules, the best approach would generally be to count your violations per rule, then look for any rules with a violation count of between approximately 5 and 20 that also meet the "easy to understand" and "easy to fix" criteria.

If it ain't broke, it don't need fixin'...

Another thing you'll want to do fairly early in the process is activate rules for which you have no existing violations. Even though this lock down might seem very important with respect to preventing additional backlog problems, it should probably wait until you're a few weeks into the cleanup process, and the team is starting to get reasonably comfortable with the whole thing. Don't worry too much about this delay causing new rule breaking -- if you've gone this long without breaking those rules, chances are pretty slim that you'll break them in the next three weeks or so. ;)

Simple as it may seem, there are still a few things to consider as you select "no violation" rules to activate:

Some of these rules will have no violations because your team has been actively avoiding some problem. Take this opportunity to highlight that they've been doing the right thing and confirm what that "right thing" is since newer team members may not be aware of it.
Some of the rules will have no violations because your project doesn't touch on the area covered by the rule. For example, if you don't interact with native APIs, there are several rules around p/invoke calls that you won't have broken. Given that your team is unlikely to start breaking these "irrelevant" rules, you can safely activate them without too much explanation. However, you should at least mention that you are activating the rule, give a quick description of its significance, and explain why it's not likely to be violated in the target code base. This approach will ensure that the team is aware of the rule should it eventually become more relevant due to changes in the project scope.
Some rules (but not very many) will have no violations almost by chance alone and will require more in-depth explanation than you may wish to allot this early in your process. You might want to consider delaying activating such rules until you have a more appropriate opportunity to provide more in-depth training on the rule.

Mix and match

As you start activating rules, you'll soon realize that some rule violations are a lot quicker and easier to fix than others. For example, fixing a violation of RethrowToPreserveStackDetails usually takes seconds, while there are a few rules for which a fix may take hours. It's important that your immediate fix backlog contain a mix of problems, both with respect to difficulty and fix duration. The quick and easy fixes will provide small tasks that any developer will be able to perform, and they're nice little "fillers" for those five minute blocks when you're waiting on something like a pre-commit test run for another task. They'll also help keep the momentum going when you've got a backlog of "big" problems to address. If you only have big problems in the backlog at any given time, the overall fix rate will be slow, and that's just plain depressing for everyone.

Some fixes will require considerable knowledge of a particular area of your product, and one approach to handling these would be have developers fix such problems in their own areas of responsibility. However, you may also want to view such fixes as an opportunity for a bit of cross-training. Either way, you should make sure that your immediate backlog doesn't only contain violations against a limited subset of your product. Any given developer on your team should be able to draw problems from the backlog pool at any given time.

Slow down, you crazy child

Now and then, your immediate fix backlog is going to grow just a bit too big. This usually happens because you've activated a rule with a large number of violations and/or for which violations are expensive to fix. In order to prevent the backlog from growing even more, you're going to have to stop activating new rules for a while. There are basically two things you can do to avoid losing momentum because of this hiatus. The first is pretty trivial, and simply involves having developers fix violations during the time that would normally be allotted to introducing new rules. If you're concerned that the fix rate has dropped off because developers have fallen out of the habit of working on the backlog, then having everyone work on fixing problems at the same time like this can be one way of "rebooting" the process. However, if developers are already spending the time they ought to be on the backlog, a fix session like this isn't necessarily a very effective use of anyone's time.

The other "delaying tactic" is to treat the increased between-rule activation delay as an opportunity to provide more in-depth training, particularly for rules where a lot of background information may be required. It can help quite a bit to divide such rules into themes, with background training on any given theme spanning several weeks. A few obvious themes are:

finalization and disposition,
exceptions, and
code access security.

Custom rules

As you tackle your backlog, you'll probably start to identify some less than desirable usage patterns that aren't covered by existing rules. While it can be quite tempting to immediately activate a new custom rule based on such a discovery, don't forget that you have plenty of built-in rules that aren't yet active either. Your custom rule should go into the same backlog "pot" as the built-in rules, and it should be activated when most appropriate to your backlog process, which may or may not be when you first discover the problem that the rule covers.

How far, how fast?

Obviously, the rate at which you will be able to activate rules will depend quite a bit on the size of the backlog and rate at which your team will be able to fix violations. However, you should also expect the activation rate to drop off over time as you start to activate rules that are difficult to fix and rules with large numbers of violations. Given that you may also start adding custom rules, the proportion of rules activated may drop even though you're not inactivating any rules. Nothing exactly surprising in any of that, but it does mean that you shouldn't use the rate of rule activation as an important indicator of your backlog clearing progress.

Control flow engine, 200?-2007, RIP

calinoiu — Sat, 28 Apr 2007 12:38:00 GMT

Surprise! (not the good kind)

If you use FxCop or Visual Studio Static Analysis and haven't yet started playing with Orcas, you may be in for a bit of an unpleasant surprise. While the code analysis team is doing all sorts of interesting things for Orcas, one somewhat less desirable change you probably haven't heard about yet is removal of the control flow engine and, consequently, the following rules which depend upon it:

Category	Rule
Design	ValidateArgumentsOfPublicMethods
Globalization	DoNotPassLiteralsAsLocalizedParameters
Performance	AvoidUnnecessaryStringCreation
	DoNotCallPropertiesThatCloneValuesInLoops
	DoNotConcatenateStringsInsideLoops
Reliability	DisposeObjectsBeforeLosingScope
Security	ReviewSqlQueriesForSecurityVulnerabilities
Usage	AttributeStringLiteralsShouldParseCorrectly
	DisposeMethodsShouldCallBaseClassDispose
	DoNotDisposeObjectsMultipleTimes
	LiteralsShouldBeSpelledCorrectly
	ProvideCorrectArgumentsToFormattingMethods

The reasons given for removing the engine are basically that it's slow, buggy, and difficult to maintain. Well, we've all had to deal with that sort of problem before, but most of us haven't have the luxury of removing the nasty, old implementation without providing a replacement. I can certainly understand that the code analysis team might be under pressure to rapidly address performance problems introduced by an engine that slows any use of their product by a factor of 2 or more, but this strikes me as a case of throwing the baby out with the bath water.

The one piece of good news is that there seem to be plans to eventually replace the engine. However, we supposedly won't be seeing the new implementation until at least the post-Orcas release of Visual Studio, which very likely means waiting two years or more. A couple of things to consider:

How big a backlog of violations against the missing control flow rules do you think your team will likely create in two years?
Given that the code analysis team apparently considers it acceptable to remove this feature set without providing an immediate replacement, how confident are you in their ability to keep development of the replacement at a high enough priority level that it will actually ship in the post-Orcas release of Visual Studio?

On again, off again...

Let's assume for the moment that the performance hit caused by the control flow engine really does prevent some folks from using FxCop. Even if it doesn't, performance improvements are probably pretty high on many folks' wish lists for FxCop, and it would seem likely that the code analysis team has to put up with a lot of complaining on that front. In addition, there are known bugs in the control flow engine and rules, and those problems may cause both some minor inconvenience as well as false confidence that rules are being applied where they're not. Are these really sufficient justifications for eliminating the control flow engine entirely in Orcas?

Rather than removing the engine, I would much rather see it become an optional, disabled-by-default component. This scenario would remove the potential performance obstacle for new users while still allowing existing customers to at least keep up the same level of screening that was previously applied. If there is concern on the part of the code analysis team that users aren't aware of the buggy, partial screening against control flow rules, the feature that allows enabling of the control flow engine could include whatever warnings they deem necessary.

Given that Orcas is already in beta, it seems likely that re-introducing the control flow engine might be too big a change to support. If so, another possibility might be to make it available only in the stand-alone FxCop product. Obviously, this would be a little less convenient for users of Visual Studio Code Analysis. However, it would at least allow such users to make their own performance/convenience/quality trade-off decisions rather than having a potentially unsuitable decision imposed upon them by the complete absence of the engine.

I've already submitted a suggestion regarding re-introduction of the control flow engine as an optional component on the Microsoft Connect site. If you're concerned about the removal of the engine, perhaps it's time to consider voicing your opinion there as well...

FxCop and the big, bad backlog

calinoiu — Sun, 22 Apr 2007 13:19:00 GMT

A few months ago, I gave a presentation on using FxCop at the Montreal Visual Studio Users Group. The material was divided into two main topics: (a) the mechanics of using FxCop and (b) integrating FxCop use into a development process. During the first part of the talk, some members of the peanut gallery kept piping up with questions about what one can do to handle the huge number of FxCop rule violations that an existing code base will have when one first runs FxCop against it. Lucky for me, most of the second part of the talk covered exactly that problem, and I managed to finish the evening without having any rotten produce lobbed in my direction. However, their questions did confirm my suspicion that dealing with the backlog problem is a topic of potential interest to folks, so it's one I might as well spend a bit of time writing about...

No backlog? No problem.

Before tackling the hard part of the backlog problem, let's look at the easy part. If you're starting a new project, the easiest way to handle the backlog issue is to never develop a backlog in the first place. The way to do this is to start running FxCop with all rules activated from the moment you first set up your project(s) and to fix problems (or flag true exclusions) before each and every check-in.

This may seem like a lot of work and, to be honest, it will almost certainly add noticeable overhead at the very beginning, but the additional effort required will probably taper off more quickly than you might expect. Within a week or two, most individual developers should be over the learning curve "hump" with respect to the FxCop tool itself. What might surprise you is that it probably won't take much longer for most developers to become familiar with the rules that touch their own work and to stop introducing new violations of those rules. This will, of course, vary depending on the spectrum of tasks that any given developer performs, but most developers in anything but the very smallest shops are likely working on fairly similar tasks from one week to the next.

Another issue on the "no backlog" side of things is that you might need to occasionally create temporary exclusions (e.g.: when you've added the first class to a namespace, but the others that would eventually prevent Design.AvoidNamespacesWithFewTypes from firing don't yet exist), and allowing these to accumulate could also create a backlog problem. The way to prevent this is to avoid them where possible and clean them up as soon as possible when their creation can't be avoided. I would recommend creating a project work item for removing any given temporary exclusion immediately before adding the exclusion itself. A final check that they have all been removed should be part of a pre-release checklist, and the release in question should be the earliest you can isolate (e.g.: internal release to QA).

And now for the hard stuff...

If, like many folks with a medium-to-large existing code base, you've run FxCop and been overwhelmed at the thousands or tens of thousands of violations that it spits out, what can you possibly do? The most common reaction seems to be essentially giving up on the idea of using FxCop for that product. That's unfortunate, partly because the existing problems will go unaddressed until they manifest as user-noticeable bugs, but also because the product will continue to accumulate new problems as development progresses.

Another path is to disregard the existing backlog and follow the "no backlog" approach described above for new development. Since the FxCop team has produced a tool to help facilitate this approach, I presume that it is a relatively common choice. Unfortunately, while it does avoid the problem of accumulating new violations, it doesn't address the existing backlog particularly well.

So... Can one do something to both prevent new problems and clean up the old problems? At FinRad, we started a process in late September to do just that. One of the things that was immediately obvious was that "hiding" the existing backlog wasn't likely to be terribly helpful if our goal was to eventually clean it all up. Part of the problem is that folks would probably become rapidly inured to the large volume of existing exclusions. Another, potentially more important issue, is that a big backlog is just plain too depressing.

Rather than activating all rules at the beginning and excluding all existing rule violations (even temporarily), we decided to adopt a process whereby rules are activated one-by-one. Once a rule is activated, its existing violations are added to the immediate backlog and nobody is allowed to introduce new violations. In addition, we decided to provide training on the newly activated rules rather than expecting individual developers to do all the rule reason and fix approaches research on their own. The basic outline of this process is:

Every week, a new set of rules to activate is selected.
We have a one hour training session on the new rules. This training includes:
- any background information that is required to understand the rules,
- the specific problems that the rules are meant to address,
- recommended approaches to fixing rule violations, and
- reasons for which it is acceptable to create exclusions for violations.
In addition, progress statistics are presented at each training session so that everyone is aware of where we stand with respect to the existing backlog.
Immediately after the training session, the new rules are activated, and existing violations are added to the backlog by creating "TODO" exclusions.
As of the activation of a rule, no new violations are accepted.
Each developer is supposed to spend two hours per week fixing rule violations from the backlog.

In practice, this exact process isn't followed to the letter every week. Besides the obvious impossibility of grabbing three hours of each developer's time every single week, there are also all sorts of picky details around which rules can/should be activated when, and what one should do to keep the momentum going when the size of the backlog jumps because of the activation of a single rule. There's also the question of what sort of hit we're taking with respect to new violations against the rules that haven't yet been activated. However, I think I'll keep all of that as meat for further blog posts for now...

No rules in your FxCop rule assembly?

calinoiu — Sat, 21 Apr 2007 12:39:00 GMT

Since I posted an FxCop rule sample over at bordecal.mvps.org, it's rapidly become the most popular content on the site. Not something I expected but, given that I have trouble coming up with blogging topics and there seems to be some interest in FxCop, I figured I might as well spend a lovely Saturday morning writing about it... (Actually, I'm pretty much just killing time while waiting for a tire change, so please feel free to keep that "get a life" comment to yourself. <g>)

There's all sorts of stuff I could (and will try to) write about FxCop use, but one thing that jumped out at me this week was quite a few searches for "no FxCop rules could be found" landing on my rule sample page, so I guess I'll start with that...

There are several reasons why FxCop might have trouble finding rules in a custom rule assembly:

There are no rule classes.
If you haven't added any rule classes to your assembly, it shouldn't be too much of a problem to figure out why FxCop can't find them. ;)

Another problem might be that your rule classes don't implement the necessary rule interfaces. If you've done the usual thing and created your rules as subclasses of Microsoft.FxCop.Sdk.Introspection.BaseIntrospectionRule, then you've got the interface problem covered. However, if you're rolling your own rules from scratch, you're probably going to have to do quite a bit more work... (Which I've never done, so I have no idea what's the minimum required. My first guess would be IRule, but that seems rather useless since there are no problem collections exposed until one gets to IControlFlowRule or IIntrospectionRule.)
You've forgotten to add an embedded rules resource file.
This is probably the most common problem for beginners. If you're not sure what the rule resource file should contain, grab yourself a copy of Reflector, and take a look at the Microsoft.FxCop.Rules.Design.DesignRules.xml embedded resource in the DesignRules.dll file that ships with FxCop or Visual Studio Static Analysis.

Also, remember that this file must be set to be an embedded resource. If the file doesn't end up in your compiled assembly, FxCop won't be able to find it.
You've incorrectly identified the embedded rules resource file in which the data for your rule class can be found.
Once you've created your embedded rules resource file, this may be the next problem you hit. If you're inheriting from BaseIntrospectionRule, you must pass the full resource file name (minus the .xml extension) when invoking the protected BaseIntrospectionRule constructor. Since all the custom rules in a given assembly will typically use the same rules resource file, one would usually create a base class from which they would all inherit. The rule base class might look something like this:
```
namespace Bordecal.FxCop.Rules
{
	internal abstract class IntrospectionRule : BaseIntrospectionRule
	{
		protected IntrospectionRule(string name)
			: base(name, "Bordecal.FxCop.Rules.Rules", typeof(IntrospectionRule).Assembly)
		{
		}
	}
}
```
This avoids requiring all rules to provide the resource file name, but it doesn't help with figuring out what the file name ought to be in the first place.

The bad news is that inferring the resource file name can be a bit tricky. It will depend on your project's default namespace, as well as on where the rule file resides within your project's directory hierarchy. The good news is that you don't need to infer the name at all. Instead, simply open your rule assembly in Reflector, and copy the full name of your resource file (remember to omit the .xml extension):