FxCop and Code Analysis: Writing Your Own Custom Rules

Jason Kresowaty

Version 1.5 (8/20/2008)


Table of Contents

Introduction
The Possibilities
Obtaining FxCop
Using FxCop: A Short Tutorial
Assembly Structure
Introspection Code Model
Introspector
Identifiers
Working With Assemblies, Modules, and Types
Structural Types
Access Modifiers
Rule Metadata XML
Rule Initialization
Check and Visit
Problems and Resolutions
Debugging FxCop Rules
Callers and Callees
Checking Documentation Comments
About the Examples
Example: Class Field Name Prefixes
Example: Spell Checking String Resources
Example: Generic List<T> Instead of ArrayList
Example: Specify Justification for SuppressMessage Attributes
Example: ArgumentException Parameter Names
Example: Check that Members are Documented
Resources

Introduction

Microsoft is taking the .NET development world by storm with its FxCop tool. The tool is designed to check .NET code for violations of a wide range of programming rules and conventions. The rules included with FxCop draw heavily upon Microsoft's Framework Design Guidelines as described in Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Krzysztof Cwalina and Brad Abrams (ISBN 0321246756).

The kinds of rules checked by FxCop include:

  • Design

  • Globalization

  • Interoperability

  • Mobility

  • Naming

  • Performance

  • Portability

  • Security

  • Usage

Unlike traditional code analysis tools (such as lint for C), FxCop does not analyze source code. Instead, it analyzes the binary Common Intermediate Language (CIL) generated by .NET compilers and persisted in .NET assemblies (EXE and DLL files). Analysis is enabled by the rich metadata that is a part of CIL. By analyzing assemblies directly, FxCop avoids being tied to any particular .NET programming language: it will work without modification against C#, VB.NET, and potentially other .NET languages.

FxCop is a mature tool. The first version of FxCop was released to the public shortly after the release of the .NET Framework 1.0 itself in 2002. In Summer 2007, FxCop was awarded the Chairman's Award for Engineering Excellence by Microsoft chairman Bill Gates. This award reflected the substantial improvement FxCop has made to development and testing practices of managed code at Microsoft. A version of FxCop is integrated with Visual Studio as a part of the Visual Studio Team System code analysis features. Another version is available as a free download.

The best part about FxCop is that you are not limited to just the rule libraries provided by Microsoft. You can easily define your own rules. What makes this possible is the "FxCop SDK," two DLLs which host the rule API. As with most APIs, you might expect detailed and comprehensive documentation. However, this is an area in which the SDK is lacking. While it has encouraged developers to write custom rules and has provided some sample code, Microsoft has not yet provided public documentation for the FxCop SDK. One ramification is that the API is subject to change without notice. Indeed, there have been significant changes in the API from version 1.35 to the latest version 1.36.

This document provides only a cursory look at the basics of using FxCop. Instead of diving deeply into features that are well-documented elsewhere, our focus is on development of custom rules, a task that many developers are—or should be—interested in doing.

Visual Studio Team System: The Code Analysis features of Visual Studio Team System 2008 Development Edition provide the same API for custom rules as FxCop 1.36. Therefore, most of what is described in this document applies to Visual Studio Team System as well. Note that the Team System includes additional rules out of the box that are not included with the free FxCop.

[Caution]Caution

This document is based on research and experimentation. The FxCop APIs are not yet documented by Microsoft. As a result, expect some changes in future releases of FxCop. Furthermore, some parts of this document are likely to be incomplete or even incorrect. This document is a tutorial; to improve readability, this document sometimes presents assumptions as if they were verified facts.