How to: Using Microsoft’s FxCop tool with VB.Net

Sadly, it just seems to be the case lately that those of us attempting to use VB.Net to write professional applications, in a professional manner, using up-to-date tools, and best practices, are swimming upstream against the current.

Whether trying out the latest tool from Microsoft (I’m looking at you, StyleCop), the latest Test-Driven/agile development approach, or even paging through most .Net-based development magazines, the support for VB.Net just isn’t there in most cases. I don’t want to add fuel to the endless, pointless debates over which .Net language is “better” — personally, I believe you use whichever language best fits the project, and if there is no difference, you use whichever dialect you find more natural – so I am going to note that both languages produce pretty much the same I.L. code, and move on.

A final note: this post applies specifically to the standalone program FxCop, not the built-in Code Analysis tools that come with versions of Visual Studio above “Professional”.

 

So, here is the latest in a series of posts on “How to use product/method/tool x with VB.Net.”

 


Download it if you ain’t got it

You can download FxCop v1.36, which is the latest version as of this writing, here. Make sure you close down any open Visual Studio instances before starting the installer. Go through the installation, which is about as standard as they come. You can find details on using FxCop in general at this location; I’m not going to repeat them here, as this is intended to be a VB.Net-specific post.

Setting it up for real-life use; what they don’t tell you

First, a quick mention of Options you will want to set: every time you start a new FxCop Project, go to the Project menu and click on Options. On the Spelling & Analysis tab, you will definitely want to check the “Suppress analysis results against generated code”. Ostensibly, this will prevent FxCop from checking Microsoft’s own generated code, such as the scaffolding code for data access, Window Forms, ASP.Net, etc. Even though this code has become less visible to the programmer over the last few versions of Visual Studio, you don’t want FxCop spitting out hundreds of warnings about code you can do nothing to change. In my experience, this option doesn’t always work, but it’s worth setting nonetheless.

Using FxCop – and how to shut it up

Next, once you actually start using FxCop, you will likely be overwhelmed by the hundreds of messages even a smallish app generates. This is normal; even Microsoft’s own code fails to measure up occasionally. So the first thing you will likely want to know is how to turn off certain warnings. It’s easy enough to right-click any warning in the Active window and then left-click Exclude; this will suppress all warnings of a given rule for the entire project. However, this is rarely the approach you want to take long term; the idea is to look at each instance of a given warning and choose, on a case-by-case basis, which individual instances to take heed of and make the recommended fix, and which to leave. Look at each warning and decide whether the rationale for the rule applies in that case. Microsoft’s analysis engine isn’t perfect, and occasionally it flags something incorrectly; some warnings are only guidelines, which may not agree with your company’s, or your personal, coding style; and sometimes there are bigger-picture reasons why a warning needs to be ignored.  Use Exclude only temporarily, to quiet the noise while you work on reducing other warnings; then, turn off Exclude and go through all warnings one at a time.

Eventually, you will have an individual warning you need to suppress permanently.

Suppressing an individual warning

There are several steps you’ll need to take to enable suppression of individual warnings in a workable way:

  1. The CODE_ANALYSIS constant: go to the Properties page for the Project (Project menu –> Properties). On the Compile tab, click on “Advanced Compile Options”. In the textbox under “Custom Constants”, type in CODE_ANALYSIS and click OK.
  2. Import the CodeAnalysis namespace: to make your life easier, open the file with the code that caused the warning, and add this namespace import at the top: Imports System.Diagnostics.CodeAnalysis

Next, go back to FxCop and right-click the warning you want to suppress. Choose Copy As:, then Suppress Message from the pop-up menu. This will copy the correct suppression message to your Clipboard, but we’re not done yet; unfortunately, FxCop will copy the message in C#, not VB.Net. Grrr.

Go back to the code file that caused the warning, and go to the problem code. In most cases, you will be pasting the suppression message at the start of a function, sub-routine, or class; occasionally, you’ll paste it right before an individual line of code, such as a call to the Messagebox.Show() method. In any event, the suppression method needs to be on the same line as the class/sub/function/code line it refers to. To keep the code readable, the usual approach is to paste the suppression message on the line above the code it goes with, then use VB.Net’s line continuation character, the underscore (_), to signal to the compiler that both items are on the same line.

However, if you go ahead and do this, you’ll wind up with this ugliness: 

suppressMessageError

Obviously, the closing bracket is not truly missing; it’s right there. The actual problem is that FxCop only speaks C# when it generates suppression methods. SuppressMessage is an attribute, and C# attributes are surrounded with square brackets [attributeHere] , like you see above.

 

The fix is also obvious, and easy, as well: simply remove the square brackets and replace them with “angle brackets”, a.k.a. less-than/ greater-than signs: <attributeHere>. Once we do that, we see the following:

suppressMessageError2

Wait—what’s that? Another error? What’s going on here?

What’s going on is quite simple—it’s another C#-ism that needs conversion to VB. That MessageId bit is C#’s version of a Named Parameter.

VB also allows named parameters, using this special named parameter operator: := . So, again, the fix is easy; simply add the named parameter operator, like so:

suppressMessage

And no errors.

However, there is one final thing you should do when suppressing an FxCop warning message.

 

“Justifying” your suppression message

Whenever you suppress an FxCop warning message, there is one additional item you should add: the Justification parameter, which should be a named parameter. The thinking is that you should have a good reason for permanently suppressing an FxCop warning message; and you should document that reason. The Justification parameter allows you to do exactly that, and documents to anyone reading through your code why you chose to suppress the warning. This is how you use it:

suppressMessageJustification

There are a couple of points to note here.

First, the location of the Justification parameter: after the Category parameter (“Microsoft.Naming”) and the CheckID parameter, which starts with the rule identifier, “CA1709”; but before the MessageID parameter. In point of fact, because we used the named parameter operator, we could have placed it after the MessageID; but it’s best to place it in the expected order, which you will see in Intellisense when entering the code. 

Second, that we used another line continuation character to place the Justification on its own line. This adds to readability, as the Justification is usually the longest parameter, and generally the most important one to someone reading your code after the fact.

 

So, there you have it; another C# tool, made usable from VB.Net! FxCop is an important tool, which will help you find bugs as well as clean up your coding style; and you can choose which messages are important, and which to ignore, either on a message-by-message basis, or project-wide. Hopefully this article will encourage you to use it more.


Currently listening to: Elvis Costello – Spike – Any King’s Shilling
Advertisements
  1. Leave a comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: