Tuesday, 15 July 2008

Creating a custom dictionary for code analysis in VS2008

There seems to be a few posts out there asking where to put a custom dictionary to be used by FxCop (code analysis). In Visual Studio 2008, you can add a dictionary xml file to the solution and then tell the solution to use this as the dictionary for FxCop. Here's how.

Create your dictionary file
Add a new XML file to your project or solution and call it what you want. It doesn't need to be called CustomDictionary.xml.
The dictionary file must follow the correct schema, but unfortunately, there does not appear to be an .xsd schema file available (that I can find). As a starting point, copy the XML from the CustomDictionary.xml that comes with FxCop which is in the default FxCop install directory which on my machine is C:\Program Files\Microsoft Visual Studio 9.0\Team Tools\Static Analysis Tools\FxCop\CustomDictionary.xml. You can then edit this file to include your own words. However, the schema is pretty simple:

Making FxCop use your dictionary
In the properties for the XML file you've created (right-click, properties), change the Build Action to 'CodeAnalysisDictionary'.
Recompile your project and FxCop should no longer complain about those words. If you examine the build output window, Visual Studio makes a call to FxCop.exe with a whole load of parameters. Setting the build action property of the xml file to CodeAnalysisDictionary, makes VS include the switch /dictionary:"" to the FxCop command.
You can also just amened the CustomDictionaryl.xml file in the FxCop default installation directory but this obviously only takes effect on that machine. I like being able to check this dictionary file into source control so that other team members can benefit from it and this also includes the build server.

Reusing the dictionary across assemblies
Another common situation is that you have more than one assembly and you want to share the same dictionary across them. One way of doing this is to add your dictionary file to the solution rather than a specific project. Then, add an existing item to your project, browse to the dictionary file in your solution, and select add as link. This add the dictionary file to your project and makes the link act like a shortcut to the dictionary file in your solution. This means you only physically create one dictionary file which is then easily shared across all your assemblies. Remember, you must still set the build action property on the link file in order for it to be recognised as a code analysis dictionary.
Note: You don't actually need to add the dictionary.xml file to the solution, but it obviously must be checked into your source control system and it should be referenced relatively, not absolutely.

The reason
In most projects I've seen, the code analysis rule CA1704 - Identifiers should be spelled correctly is all too easily ignored by adding a rule to the global suppression file. Personally, I don't like this because I think the global suppression file should not be used as a custom dictionary, especially when there is an alternative. The custom dictionary method is much more portable across projects and it preserves the separation of spelling against genuine code analysis errors.


Redmist said...

"In the properties for the XML file you've created (right-click, properties), change the Build Action to 'CodeAnalysisDictionary'."

I don't have this option is VS2008 Professional. Is it only in Team System?

Param said...

Hey Duncan,

Thanks :)

Dave Jellison said...

Nice post, easy to understand, shows best approach and is complete with solution-wide usage.

robert nadar said...

Thanks for the post.
Really very helpful. Came across this article while searching something else, however better i landed here.