Looking through the Error List shown in Figure 8-3, you should see item CA1810, with a description of "Initialize all static fields in 'PayCalculator' when those fields are declared and remove the explicit static constructor."

Right-click on this warning and choose Show Error Help. This will display the documentation for the rule that triggered this warning, including suggestions for resolving the issue. You are currently assigning the value of 100 to MaximumHours inside the static constructor of PayCalculator. The rule's Help text states that your code may perform more efficiently if you make that assignment when the variable is defined.

To address this issue, double-click on this warning and you'll be brought to the static constructor of the PayCalculator class. Change the code to assign the value in the declaration as follows:

public static int MaximumHours = 100;

Next, delete the static PayCalculator constructor entirely. Build the project and look at the Error List window. The specific warning should no longer be in the list.

There is another easy problem to correct. Many of the code analysis rules relate to standard naming conventions. Find the warning "Remove the underscores from type name 'PayCalculator.Pay_Level'" and double-click. The rule helps to enforce the naming convention that underscores should not be used in type names. Use the built-in refactoring support to rename it. Right-click on the Pay_Level enumeration and choose Refactor

Mark the PayCaclulator class definition static as follows:

public static class PayCalculator

Rules can also help ensure that you're using the Framework correctly. You can see from the following warning that the rule has detected that you might not be creating the ArgumentOutOfRangeException correctly; "Method 'PayCalculator.ComputePayment(int, PayCalculator.Pay_Level)' passes 'Employee works too much' as the 'paramName' argument to a 'ArgumentOutOfRangeException' constructor. Replace this argument with one of the method's parameter names. Note that the provided parameter name should have the exact casing as declared on the method." To fix this, change the line that throws the exception to the following:

if (hours > MaximumHours)
    {

     throw new ArgumentOutOfRangeException("hours", "Employee works too much");
    }

One of the remaining warnings, "Mark 'SampleLibrary.dll' with CLSCompliantAttribute(true) because it exposes externally visible types," is a fairly common suggestion. Consider addressing this when creating a reusable library assembly that might be consumed by code of more than one .NET language. Common Language Specification (CLS) compliance specifies that your assembly must meet the common structure and syntax supported by all .NET languages as defined in the CLS. Keep in mind that there may be times when CLS compliance is not possible, such as when exposing unsigned types.

To address this warning, open AssemblyInfo.cs and add the following line:

[assembly: System.CLSCompliant(true)]

The assembly: notation is used because the attribute applies to the entire assembly, and not to a specific class or member. Other assembly-level attributes can be found in the AssemblyInfo.cs file.

Now, build the project. The violations you corrected should no longer generate messages in the Error List. The remaining five warnings will be addressed shortly.

Visual Studio 2010 ships with many rules, and not all of them are appropriate for every project. There is a chance that some rules will trigger warnings that simply don't apply to certain parts of your project. To prevent these irrelevant messages from recurring, right-click on the rule violation and choose Suppress Message(s).

When you suppress a message, Visual Studio automatically adds an attribute to your code to indicate that a rule should not apply. The SuppressMessage attribute can be applied to a code construct, such as a field, method, or class, and to an entire assembly.

Let's continue with the SampleLibrary example and use message suppression to clean up more of the code analysis violation messages.

The warnings for CA1709 states, "Correct the casing of 'BONUS' in member name PayCalculator.BONUS." Assume that your organization has different naming conventions for constants, and you know that this rule will not apply to this BONUS constant. Right-click on the message and choose Suppress Message

[System.Diagnostics.CodeAnalysis.SuppressMessage(
    "Microsoft.Naming",
    "CA1709: IdentifiersShouldBeCasedCorrectly",    MessageId = "BONUS")]

The next time Code Analysis is run, the engine will recognize this attribute. Moreover, even when the CA1709 rule is violated at this point, no message will be created. Messages for any other violations of this rule elsewhere in the code will still be reported as normal.

Two more messages don't apply to the project. "Consider making 'PaymentCalculator.MaximumHours' non-public or a constant" reminds you that external users of the class could change its value. This is the behavior you want, so right-click on the message and choose Suppress Message

As you can see, suppressing messages can quickly add a number of attributes to your code. If you find that you always suppress a given message, it is probably better to exclude the rule altogether; then your code will not require the additional SuppressMessage attributes. However, as noted previously, use caution when doing this, because you could unintentionally be missing valid violations that should be addressed.

The warning "Sign 'SampleLibrary.dll' with a strong name key" applies to the overall assembly. If you know that you'll never use this assembly in the Global Assembly Cache (GAC), and will have no other need for strong names, you can suppress this message. Right-click the warning and select Suppress Message

[assembly: System.Diagnostics.CodeAnalysis.SuppressMessage(
    "Microsoft.Design",
    "CA2210:AssembliesShouldHaveValidStrongNames")]

There is one warning left: "CA 1034: Microsoft.Design: Do not nest type 'PayCalculator.Pay_level'. Alternatively, change its accessibility so that it is not externally visible." Suppress this warning message, build the project, and you should now see an empty Error List. This indicates all enabled Code Analysis rules have either been passed or suppressed.

As mentioned earlier, most of the included code analysis rules inherit (typically indirectly) from a base class called BaseIntrospectionRule. While each custom rule could inherit directly from this class, it's easier to create a common base class that inherits from BaseIntrospectionRule. This is because the constructor to BaseIntrospectionRule requires three arguments. The first argument is the name of the rule, and the second is the name of the XML file containing rule data. The final argument is a reference to the rule assembly type.

If you created a rule assembly with multiple rules, each rule would have to supply those three arguments each time. However, with a new base class, you can abstract away the last two arguments and keep your rule code streamlined.

Create a new file called BaseStaticAnalysisRule.cs and add the following code:

using System;
using Microsoft.FxCop.Sdk;

namespace CustomCodeAnalysisRules
{
    public abstract class BaseStaticAnalysisRule : BaseIntrospectionRule
    {
        protected BaseStaticAnalysisRule(string name) :
            base(name,
                 "CustomCodeAnalysisRules.Rules",
                 typeof(BaseStaticAnalysisRule).Assembly) { }
    }
}

Because the values of the second and third parameter to the BaseIntrospectionRule constructor will be the same for all rules in your assembly, you use this simple class as a wrapper in which those values can be set. The second argument, CustomCodeAnalysisRules.Rules, needs further explanation and is described in detail later in this chapter in the section "Creating Rules.xml."

Now that you have a base class to use for all of your custom rules, you can create a rule. A rule has two main components:

Before you can create the rule's implementation, you must have an approach for evaluating and inspecting a target assembly. While there are many ways you could write code to do this, Microsoft has made the job much easier by including the Microsoft.Cci assembly with Visual Studio 2010. Let's take a look at what this assembly is and how to use it.

The Microsoft.Cci assembly (or Common Compiler Infrastructure) originated from Microsoft Research and contains classes that provide features for language-based tools, such as compilers. This assembly is especially helpful for code analysis because it offers many classes that map directly to common programming constructs (such as classes, fields, members, and methods). You'll use these classes to inspect target assemblies to identify the places where your rule applies.

Table 8-4 lists the major classes offered by Microsoft.Cci, organized by programming concept.

The members of the Microsoft.Cci namespace are organized in a hierarchical structure, with related classes organized under a parent type.

For example, the Member class is the parent for the types of things you'd expect to have as class members, Method, Property, Field, Event, and others. If you have a Method instance, you can use its members to obtain references to the items it contains. For example, the Instructions property returns an InstructionList that you can use to loop through the operations of the method. Similarly, the Method class also has a Parameters field, returning a ParameterList instance that can be used to inspect each parameter of the method.

As mentioned earlier, one of the abstractions the base class makes is the implementation of the IIntrospectionRule interface. This interface provides the opportunity to specify the conditions under which you want your rule to be invoked. IIntrospectionRule contains the following members:

ProblemCollection Check(Member member);
ProblemCollection Check(Module module);
ProblemCollection Check(Parameter parameter);
ProblemCollection Check(Resource resource);
ProblemCollection Check(TypeNode type);
ProblemCollection Check(string namespaceName, TypeNodeList types);

These overloads of the Check method provide the capability to indicate that your rule should be called when a specific kind of programming construct is currently the focus of the code analysis engine. You do not need to implement all of the Check methods in your custom rules, only the ones that expose the constructs you need.

In this chapter's example, you are looking for constants in an assembly, so you must observe the various members of each class, looking for those that are constants and exposed publicly. Therefore, you must use the Check(Member member) overload. This method will be called each time the analysis engine finds any type member, be it a constant, method, field, property, or other member type.

You now have a base class for your rule, and an understanding of the Microsoft.Cci namespace and IIntrospectionRule methods that will help you write the implementation. Create a new class file, AvoidExposingPublicConstants.cs.

First, add using statements for the namespaces you'll use:

using System;
using Microsoft.FxCop;
using Microsoft.FxCop.Sdk;

Now, create the class, inheriting from the BaseStaticAnalysisRule you created earlier:

namespace CustomCodeAnalysisRules
{
    public class AvoidExposingPublicConstants : BaseStaticAnalysisRule
    {
        public AvoidExposingPublicConstants() :
                base("AvoidExposingPublicConstants") {}

        public override ProblemCollection Check(Member member)
        {
            Field f = member as Field;
            if (f == null)
            {
                // Not a field
                return null;
            }

if (member.DeclaringType is Microsoft.FxCop.Sdk.EnumNode)
            {
                // Inside an enumeration
                return null;
            }

            if (member.IsVisibleOutsideAssembly && f.IsLiteral)
            {
                // Is publicly visible and is a constant
                Problems.Add(new Problem(GetResolution(member.Name.Name)));
            }

            return Problems;
        }

        public override TargetVisibilities TargetVisibility
        {
            get { return TargetVisibilities.ExternallyVisible; }
        }
    }
}

The constructor must only supply the name of the rule to the base class constructor, which will forward the name of your XML data store and the assembly type reference automatically to the BaseIntrospectionRule.

As determined earlier, you must implement the Check(Member member) overload from the IIntrospectionRule and search each member for constants. The first thing you do is attempt to convert the Member to a Field instance. If this fails, you know the member was not a field, and you can move on to the next member. If it is a Field, you check the Member to determine whether it was declared inside of an enumeration. You're not interested in enumerations, so you return null in this case.

Finally, you verify that the member is publicly visible with the IsVisibleOutsideAssembly property, and that it is a constant (or literal) value with the IsLiteral property. If these expressions are true, you have a publicly visible constant, and your rule has been violated.

When a rule has been violated, you must create a new Problem instance and add it to your rule's ProblemsCollection collection, provided by the BaseIntrospectionRule class. The argument to a Problem constructor is a Resolution instance. The BaseIntrospectionRule class offers a GetResolution helper method that loads the resource data from the embedded XML data for the current rule. Arguments to GetResolution are automatically inserted into any placeholders such as {0} and {1} in the rule's resolution text, in the same manner as String.Format.

The new Problem is added to the ProblemsCollection collection, and the ProblemsCollection collection is returned, indicating to the Code Analysis tool that a new violation has been added.

The final item in the rule implementation is the TargetVisibility property. This property is used by the Code Analysis tool to determine when items should be fed into the rule's Check method(s). The TargetVisibilities enumeration has values such as All, ExternallyVisible, NotExternallyVisible, AnonymousMethods, None, Obsolete, and Overridable that can be combined to indicate when the rule should be tested. In this case, you only care about publicly visible members, so you return TargetVisibilities.ExternallyVisible.

With the implementation written, you must now create an XML node that describes the rule and provides text to help the user understand and address rule violations. The outer Rules node specifies the name of the group of rules — for example, Performance Rules. It contains one or more Rule nodes, each describing a single rule.

Add a new XML file to the project. Name the file Rules.xml and enter the following:

<?xml version="1.0" encoding="utf-8" ?>
<Rules FriendlyName="Custom Code Analysis Rules">
  <Rule TypeName="AvoidExposingPublicConstants" Category="Wrox.Custom"
   CheckId="CS0001">
    <Name>Avoid exposing public constants</Name>
    <Description>The values of public constants are compiled into any referencing
assemblies.  Should that value change, it is not sufficient to recompile
    the source
assembly because that value will also be stored in those referencing assemblies.
Avoid public constants for this reason.</Description>
    <Resolution>Change public constant '{0}' to a readonly variable, or mark it as
     private or internal.</Resolution>
    <MessageLevel Certainty="99">Warning</MessageLevel>
    <FixCategories>NonBreaking</FixCategories>
    <url>/Custom/AvoidExposingPublicConstants.html</url>
    <Email>[email protected]</Email>
    <Owner>Contact Person's Name</Owner>
  </Rule>
</Rules>

The Rule node has a TypeName attribute (which should match the name of the rule class), a Category (which is used when displaying violations), and a CheckId (which uniquely identifies that rule — for example, in SuppressMessage attributes). Name is a short, but friendly, version of the rule name. Description contains the full description of what the rule is detecting.

Resolution is the full text shown to users to help them correct the violation. It may contain placeholders, such as {0}, which will automatically be replaced with values from the implementation code, as discussed earlier in this chapter. This is extremely useful to help users quickly identify where problems exist.

Resolution also supports an optional Name attribute that enables you to specify multiple resolutions for the same rule, which can be selected at analysis time by your rule. To do so, instead of using the GetResolution method, use GetNamedResolution, supplying the name you wish to match.

MessageLevel provides a Certainty that the rule is applicable, with values from 0 to 99. A 99 indicates there is little doubt the rule has been violated and should be addressed. A lower value means violations of the rule are difficult to detect with great certainty. Use this value to indicate to the user how likely it is that a specific member or assembly has violated the rule.

The element value of the MessageLevel can be any of the Microsoft.VisualStudio.CodeAnalysis.Extensibility enumeration values, including Information, Warning, CriticalWarning, Error, or CriticalError. Use these to indicate the relative severity of violating a rule. You can see this and the MessageLevel value in practice when you open the XML report from a Code Analysis run, as shown in Figure 8-4.

FixCategories indicates whether the changes needed to correct a rule violation should generally be considered breaking or nonbreaking. Values come from the Microsoft.VisualStudio.CodeAnalysis.Extensibility enumeration and can be Breaking, NonBreaking, or DependsOnFix (which ties back to the concept of multiple named resolutions).

For example, let's say you have a custom rule that has two named resolutions, each used for different rule-violation scenarios. One resolution is easy to implement, and you consider it nonbreaking. But the other is complex to correct, requiring a breaking change.

The Url is the path to an optional file that will show full details of the rule to the user, beyond what is given in the IDE. Email is the optional address of a contact person for help on the rule. Owner is the optionally provided name of a contact person for the rule.

You now have a complete rule assembly with embedded XML containing the supporting data for the contained rule(s). The easiest way to get Visual Studio 2010 to use the contained rules is to move the assembly into the Team ToolsStatic Code AnalysisFxCopRules subdirectory of your Visual Studio installation directory. This will cause the IDE to recognize the rule assembly and read the contained rules so that you can select them for inclusion. The rule is added to the Microsoft.AllRules rule set by default.

A useful way to debug new rules is to create a single solution containing both the custom rule project and a sample target project with code that violates the rule. Open the Properties window for the rule assembly project and choose the Build Events tab. Add a post-build event command line to copy the rule assembly from the source project to the Team ToolsStatic Code AnalysisFxCopRules directory.

A problem with this approach is that if you open the Code Analysis properties window in either project, the custom rule assembly will be loaded and locked by the IDE. When this happens, you must close and reopen Visual Studio. However, this approach will generally make your rule debugging process much easier.

You've now seen how to create your own rules and integrate them into the Code Analysis tool of Visual Studio 2010. You will certainly find many uses for additional rules, but before you begin creating them, you should invest some time learning from examples.

The recommended approach for those wishing to implement custom rules is to look at how the rules included with Visual Studio 2010 were written. While you don't have direct access to the source code for these rules, there is a tool that can help. Reflector, written by Lutz Roeder and now maintained by RedGate (www.red-gate.com/products/reflector), uses the power of .NET's reflection services to peer inside any assembly and generate an approximation of the source code. The target assembly can be any assembly, including those from Microsoft.

After obtaining Reflector, find the existing rules files in your Visual Studio 2010 installation directory under Team ToolsStatic Analysis ToolsFxCopRules. Using Reflector, open one of the rule assemblies, such as PerformanceRules.dll. You can then navigate to the Microsoft .Tools.FxCop.Rules.Performance namespace, where you will see all of the rules in the Performance category.

Opening each rule will show you the details you've learned about earlier in this chapter. The rules inherit from base helper classes, just as you saw with AvoidExposingPublicConstants and BaseStaticAnalysisRule. Opening the Resources node for any rule assembly enables you to view the XML data that was embedded in the assembly. Opening members such as the Check methods will show you code that, while not exactly original, will give you enough detail to determine how you might accomplish the same tasks in your own rules.