Code Analysis Team Blog : FAQ

FAQ: How do I prevent FxCop 1.36 from firing warnings against generated code?

David M. Kean — Thu, 28 Feb 2008 21:39:29 GMT

I've upgraded from FxCop 1.35 to 1.36 and now FxCop has started to fire warnings against typed DataSets and other generated code. How do I turn this off?

The reason this is occurring is because we changed the way that FxCop analyzed generated code. Whereas previously in 1.35, FxCop would only ignore particular generated code (such as DataSets), FxCop 1.36 will now either ignore no generated code, or all generated code. The former is the default.

To change this behavior and have FxCop skip over generated code:

Using an FxCop project:

Open your FxCop project in FxCop
Choose Project -> Options -> Spelling & Analysis
Check Suppress analysis results against generated code
Click OK

Via the command-line:

Pass the /ignoregeneratedcode switch, for example:

FxCopCmd.exe /file:MyAssembly.dll /out:AnalysisResults.xml /ignoregeneratedcode

For more information on FxCop's behavior over generated code, see Correct usage of the CompilerGeneratedAttribute and the GeneratedCodeAttribute.

FAQ: Which Code Analysis rules shipped in which version?

David M. Kean — Mon, 07 Jan 2008 21:04:00 GMT

In response to a lot of recent requests, we've put together a complete list of rules that shipped in the different versions of Visual Studio Code Analysis and FxCop. Attached is an Excel worksheet providing this information for Visual Studio 2005, Visual Studio 2008, FxCop 1.35 and FxCop 1.36 Beta.

One of things you'll notice as you read through the list is that we removed some rules from the later versions. There are a few reasons for this:

Noise and applicability. We use feedback from customers, SQM data (to see which rules users turn off), and input from internal teams (Windows, Office, CLR, etc) to determine the rules that are noisy without adding any perceivable value. There are also rules that are either no longer applicable or can no longer fire. for example, a rule could have been firing on a limitation of the CLR which has since been fixed in later versions.
Merged rules. Sometimes it makes sense to merge rules that fire on similar things, for example, the analysis in SecureGetObjectDataOverrides was already covered by OverrideLinkDemandsShouldBeIdenticalToBase, so these two rules were merged. Similarly, LongAcronymsShouldBePascalCased, ShortAcronymsShouldBeUppercase and IdentifiersShouldBeCasedCorrectly all fired on the casing of identifiers, and hence were merged in the later.
Analysis engine removed. In Visual Studio 2008 and FxCop 1.36 we removed one of our analysis engines. This engine was removed for a variety of reasons; it increased analysis time (although the engine encompassed less than 5% our analysis, it took up 50% of our time-to-analyze), indeterministic results (results appearing and disappearing between runs), and bugs found within the engine (and hence the rules that depended on it) required huge architectural changes. We instead decided to invest the resources that we would have spent on fixing the old engine, on a new data flow analysis engine based on Phoenix, which we will ship in a future version of Visual Studio.

There are also more differences between Visual Studio Code Analysis and FxCop than just the rules - in a future blog post I will cover these in detail.

FAQ: How do I debug a custom rule?

David M. Kean — Wed, 16 May 2007 18:00:00 GMT

While writing your custom rule, you will likely come across a need to debug it and work out why it's behaving in a particular manner.

Debugging within FxCop

Debugging a custom rule within the FxCop UI is actually quite easy. To do so, simply:

Open the FxCop project that contains your custom rule (making sure the PDB is alongside the assembly)
Open the solution that contains your custom rule and set a breakpoint in the rule your want to debug
Choose Debug -> Attach to Process
Under Available Processes, choose FxCop.exe and click Attach
In FxCop, choose Project -> Analyze

The debugger should break when it hits the breakpoint.

Debugging within Visual Studio or via command-line

However, if you want debug a rule that you've written for Visual Studio Code Analysis, or via the command-line, the procedure is not so obvious:

Open a Visual Studio Command Prompt
If debugging a custom rule written for Visual Studio, run the following:

> cd %VSINSTALLDIR%\Team Tools\Static Analysis Tools\FxCop

Otherwise, if debugging a custom rule written for FxCop, run the following:

> cd %PROGRAMFILES%\Microsoft FxCop 1.35
Run the following command, replacing [TargetAssembly] and [RuleAssembly] with the assembly you want to analyze and the assembly that contains your custom rule respectively.

> devenv /debugexe FxCopCmd.exe /file:[TargetAssembly] /rule:[RuleAssembly] /console

This will open Visual Studio in a state that is ready to debug your custom rule.
Choose File -> Open -> File and browse to and open the source file that contains your custom rule
Set a breakpoint in the rule
Choose Debug -> Start Debugging

The debugger should break when it hits the breakpoint.

The Modules window is your friend

If the breakpoint is not being hit, check to make sure that you actually have symbols for your custom rule loaded:

While debugging, choose Debug -> Windows -> Modules

To do this if you are debugging via /debugexe switch, as soon as the command window opens to start running FxCop, click PAUSE on the keyboard.
Look for your rule assembly and check under the Symbol Status column.
If this column states anything other Symbols Loaded, then right-click on the assembly and choose Load Symbols and browse manually to the PDB.

FAQ: Why is file and line information available for some warnings in FxCop but not for others?

David M. Kean — Sat, 12 May 2007 18:00:00 GMT

It appears that sometimes FxCop displays a link to the source line and file in the Message Details window and sometimes it doesn't. Why this inconsistent behavior?

There are three usual reasons why this occurs:

Source lookup is disabled. To turn source lookup on, choose Project -> Options and check Attempt source file lookup.
The Program Database (PDB) is not present or it is out-of-date. Starting in Visual Studio 2005, this file is now built by default both in Debug and Release. Make sure it was built at the same time and is alongside the assembly under analysis.
There is no source information for the code element that warning was raised against. FxCop and Visual Studio Code Analysis both use the information stored in the Program Database (PDB) file to map members back to a particular source file. Unfortunately, because this file was orginally only designed for use by a debugger, it only contains information about actual executable code. This means that FxCop cannot find non-executable code such as namespaces, types, fields, interface methods and abstract methods.

Note: Visual Studio Code Analysis does not suffer this problem to extent of FxCop - it falls back to the Visual Studio Code Model to find elements that do not exist in the PDB. It still, however, is unable to find namespaces.

FAQ: How do I get the SourceContext for a local?

David M. Kean — Tue, 27 Mar 2007 18:00:00 GMT

I want to fire on the naming of a local, however, whenever I pass the local to the Problem constructor, the source information for the method is always used. How do I get FxCop/Code Analysis to use the source information for the local instead?

Because the declaration of a local is not associated with an executable instruction, a local does not contain any source information within the pdb. However, any usages of the local (such as an assignment) does.

The following example shows when source information is provided and not provided:

    public void Bar()
    {
        int value1;                // Does not have source information
        value1 = 10;               // Has source information
        int value2 = 20;           // Has source information

        Console.WriteLine(value1); // Has source information
        Console.WriteLine(value2); // Has source information
    }

As most locals are assigned at their time of declaration (such as in the case of value2 in the above example), a simple trick is use the source context of the first usage of the local in place of its declaration. This works in most situations.

The following example shows this (using the code from FAQ: How do I access the locals of a method in a custom rules?):

    public override ProblemCollection Check(Member member)
    {
        Method method = member as Method;
        if (method == null)
            return null;

if (method.Instructions.Length == 0)
return null;

        LocalList locals = method.Instructions[0].Value as LocalList;
        if (locals == null)
            return null;

        for (int i = 0; i < locals.Length; i++)
        {
            Local local = locals[i];

            if (someCondition)
            {   // Fire on the local

                Resolution resolution = new Resolution("Fix local {0}", local.Name.Name);

SourceContext sourceContext = FindSourceContext(local, method.Instructions);

                Problem problem = new Problem(resolution, sourceContext);
                Problems.Add(problem);
             }
        }

        return Problems;
    }

    private static SourceContext FindSourceContext(Local local, InstructionList instructions)
    {
        foreach (Instruction instruction in instructions)
        {
            if (instruction.Value == local)
            {   // Found its first usage
                return instruction.SourceContext;
            }
        }

        return new SourceContext();
    }

Note: If the local is only declared and is never assigned to, or its usage is only as the argument for an out parameter, then the source context of the method will be used.

FAQ: How do I run FxCop during a post-build event?

David M. Kean — Sat, 24 Feb 2007 19:00:00 GMT

A little known feature of FxCop (in particular FxCopCmd.exe) is its ability to be integrated into the build process within Visual Studio. Although not a replacement for the Code Analysis functionality available within both Visual Studio Team Edition for Developers and Visual Studio Team Suite, it allows you to display FxCop violations within the Error List alongside normal build errors and warnings.

To set this up is easy:

In Solution Explorer, right-click on your project and choose Properties
For C# projects, in the Project Properties window, select the Build Events tab
For Visual Basic projects, in the Project Properties window, select the Compile tab, and click Build Events
In the Post-build event command-line text box, enter the following (assuming you installed FxCop to the default location):

"%ProgramFiles%\Microsoft FxCop 1.35\FxCopCmd.exe" /file:"$(TargetPath)" /console
In Solution Explorer, right-click on your project and choose Build

Any FxCop violations will now appear as build warnings:

One thing that you might notice is that although source information is populated in the Error List for warnings raised against properties, events and methods, double-clicking the warning does not cause Visual Studio to jump its location. It turns out this is actually a bug in the MSBuild engine failing to assume the default column of 1 for warnings without column information. This is likely to be fixed in Visual Studio Orcas.

The workaround for this is to simply replace %ProgramFiles%\Microsoft FxCop 1.35\Xml\VSConsoleOutput.xsl (again, assuming you installed to the default location), with the version attached to this post.

Thanks to David Gardiner for making us aware of both the bug and workaround.

FAQ: When looking at the names of locals in a custom rule, why do I see strange names such as 'CS$1$0000' and 'VB$1$0000'?

David M. Kean — Fri, 26 Jan 2007 19:00:00 GMT

Previously we showed you how to access the locals or variables of a method. Once you started to run your rule over an assembly, you might start to notice strange locals with names that start with 'CS$' and 'VB$'. These are compiler generated locals that are outside the control of the user.

If you are writing a rule to check the names of locals, you will want to skip over these, To do this, simply pass the local to RuleUtilities.IsCompilerGenerated method and check the result.

Note: This will also skip over locals when source and line information (PDBs) is not alongside the assembly under analysis.

FAQ: What exception should I throw instead of the reserved exceptions that DoNotRaiseReservedExceptionTypes warns against?

David M. Kean — Mon, 22 Jan 2007 19:00:00 GMT

Throwing a general exception type such as System.Exception or System.SystemException in a library or Framework forces consumers to catch all exceptions, including unknown exceptions that they do not know how to handle (see FAQ: Why does FxCop warn against catch(Exception)? for reasons as to why this is bad).

Instead, either throw a more derived type that already exists in the Framework, or create your own type that derives from Exception.

The following list examples of when you should throw specific exceptions:

When validating a parameter (including the value parameter in the set accessor of a property) that:

is a null reference (Nothing in Visual Basic)
    throw System.ArgumentNullException

is outside of the allowable range of values (such as an index for a Collection/List)
    throw System.ArgumentOutOfRangeException (DO NOT throw System.IndexOutOfRangeException)

is outside the allowable values for a enum
    throw System.ComponentModel.InvalidEnumArgumentException

contains a format that not meet the parameter specifications of a method (such as the format string for ToString(String))
    throw System.FormatException

is otherwise invalid (such as an empty string)
    throw System.ArgumentException

When an operation is invalid for an object's current state:
throw System.InvalidOperationException

When an operation is performed on an object that has been disposed:
throw System.ObjectDisposedException

When an operation is not supported (such as in an overridden Stream.Write in a Stream opened for reading):
throw System.NotSupportedException (DO NOT throw System.NotImplementedException)

When a conversion would result in an overflow (such as in a explicit cast operator overload):
throw System.OverflowException

For all other situations, consider creating your own type that derives from Exception and throwing that.

Note: Exceptions that derive from ArgumentException (including ArgumentNullException, ArgumentException, ArgumentOutOfRangeException and InvalidEnumArgumentException), InvalidOperationException (including ObjectDisposedException) and NotSupportedException should only be thrown in situations that are avoidable (such as passing a null argument) and if thrown, would indicate a bug in the calling code. The Path class is not a good example of this, it incorrect throws ArgumentException to indicate that a path is incorrectly formed, however, it does not expose any methods that can help prevent this from occurring.

FAQ: How do I fix a violation of MovePInvokesToNativeMethodsClass?

David M. Kean — Sun, 14 Jan 2007 19:00:00 GMT

MovePInvokesToNativeMethodsClass fires on P/Invokes (ie methods marked with DllImport) that are not members of one of the following classes; NativeMethods, SafeNativeMethods or UnsafeNativeMethods.

For example, the following sample fires this warning.

[C#]

using System;
using System.Runtime.InteropServices;

internal static class Directory
{
    // Violates MovePInvokesToNativeMethodsClass
    [DllImport("kernel32.dll")]
    internal static extern bool RemoveDirectory(string name);
}

[Visual Basic]

Imports System
Imports System.Runtime.InteropServices

Public NotInheritable Class Directory

Private Sub New()
End Sub

    ' Violates MovePInvokesToNativeMethodsClass
    <DllImport("kernal32.dll", CharSet:=CharSet.Auto)> _
    Friend Shared Function RemoveDirectory(ByVal Name As String) As Boolean
    End Function

End Class

In the above example, the RemoveDirectory P/Invoke should be moved to an appropriate class that is designed to only hold P/Invokes.

For most applications, moving P/Invokes to a new class called NativeMethods is typically enough. However, in situations where you are developing reusable libraries for use in other applications then you should also consider defining two other classes called SafeNativeMethods and UnsafeNativeMethods. Both of these classes are similar to the NativeMethods class, however, they are marked with a special attribute called SuppressUnmanagedCodeSecurityAttribute. Applying this attribute causes the runtime to avoid performing a full stack walk to make sure that all callers have the UnmanagedCode permission when calling the p/invoke methods containing within these classes. The runtime will check your library for this permission at startup, however, not the assemblies that reference it. This can greatly improve performance when calling unmanaged code and also allows code with limited permissions to call these methods.

However, using this attribute should not be taken lightly, as implemented incorrectly it can actually have serious security implications.

NativeMethods

As the NativeMethods class should not be marked with SuppressUnmanagedCodeAttribute, P/Invokes placed within in it, will require UnmanagedCode permission. As most applications run from the local machine and run with FullTrust, this is usually not a problem. However, if you developing reusable libraries, you should instead consider defining a SafeNativeMethods or UnsafeNativeMethods class.

The following example shows a method Interaction.Beep that wraps the MessageBeep function from user32.dll, the MessageBeep P/Invoke is placed within the NativeMethods class.

[C#]

using System;
using System.Runtime.InteropServices;
using System.ComponentModel;

public static class Interaction
{
    // Callers require Unmanaged permission
    public static void Beep()
    {
        // No need to demand a permission as callers of Interaction.Beep
        // will require UnmanagedCode permission
        if (!NativeMethods.MessageBeep(-1))
            throw new Win32Exception();
    }
}

internal static class NativeMethods
{
    [DllImport("user32.dll", CharSet = CharSet.Auto)]
    [return: MarshalAs(UnmanagedType.Bool)]
    internal static extern bool MessageBeep(int uType);
}

[Visual Basic]

Imports System
Imports System.Runtime.InteropServices
Imports System.ComponentModel

Public NotInheritable Class Interaction

Private Sub New()
End Sub

' Callers require Unmanaged permission
Public Shared Sub Beep()

        ' No need to demand a permission as callers of Interaction.Beep
        ' will require UnmanagedCode permission
        If Not NativeMethods.MessageBeep(-1) Then
            Throw New Win32Exception()
        End If

    End Sub

End Class

Friend NotInheritable Class NativeMethods

Private Sub New()
End Sub

    <DllImport("user32.dll", CharSet:=CharSet.Auto)> _
    Friend Shared Function MessageBeep(ByVal uType As Integer) As <MarshalAs(UnmanagedType.Bool)> Boolean
    End Function

End Class

In the example above, any assembly that calls NativeMethod.MessageBeep or Interaction.Beep will require UnmanagedCode permission.

SafeNativeMethods

P/Invoke methods that are safe to be exposed to any application and do not have any side effects should be placed in a class called SafeNativeMethods . No permissions need to be demanded and you do not need to pay too much attention to where they are getting called.

The following example shows a property Environment.TickCount that wraps the GetTickCount function from kernel32.dll.

[C#]

using System;
using System.Runtime.InteropServices;
using System.Security;

public static class Environment
{
    // Callers do not require UnmanagedCode permission
    public static int TickCount
    {
        get
        {
            // No need to demand a permission in place of
            // UnmanagedCode as GetTickCount is considered
            // a safe method
            return SafeNativeMethods.GetTickCount();
        }
    }
}

[SuppressUnmanagedCodeSecurityAttribute]
internal static class SafeNativeMethods
{
    [DllImport("kernel32.dll", CharSet = CharSet.Auto, ExactSpelling = true)]
    internal static extern int GetTickCount();
}

[Visual Basic]

Imports System
Imports System.Runtime.InteropServices
Imports System.Security

Public NotInheritable Class Environment

Private Sub New()
End Sub

' Callers do not require Unmanaged permission

    Public Shared ReadOnly Property TickCount() As Integer
        Get
            ' No need to demand a permission in place of
            ' UnmanagedCode as GetTickCount is considered
            ' a safe method
            Return SafeNativeMethods.GetTickCount()
        End Get
    End Property

End Class

<SuppressUnmanagedCodeSecurityAttribute()> _
Friend NotInheritable Class SafeNativeMethods

Private Sub New()
End Sub

    <DllImport("kernel32.dll", CharSet:=CharSet.Auto, ExactSpelling:=True)> _
    Friend Shared Function GetTickCount() As Integer
    End Function

End Class

In the above example, although the assembly that defines Environment.TickCount still requires UnmanagedCode permission, any callers of it do not.

UnsafeNativeMethods

P/Invoke methods that are not safe to be called by anyone and can cause side effects should be placed in a class called UnsafeNativeMethods . These methods should be either stringently checked to make sure that they are not being exposed to the user inadvertently (the rule Review SuppressUnmanagedCodeSecurity usage can help with this) or should have another permission demanded in place of UnmanagedCode when using them.

The following example shows a method Cursor.Hide that wraps the ShowCursor function from user32.dll.

[C#]

using System;
using System.Runtime.InteropServices;
using System.Security;
using System.Security.Permissions;

public static class Cursor
{
    // Callers do not require UnmanagedCode permission, however,
    // they do require UIPermissionWindow.AllWindows
    public static void Hide()
    {
        // Need to demand an appropriate permission
        // in place of UnmanagedCode permission as
        // ShowCursor is not considered a safe method
        new UIPermission(UIPermissionWindow.AllWindows).Demand();
        UnsafeNativeMethods.ShowCursor(false);
    }
}

[SuppressUnmanagedCodeSecurityAttribute]
internal static class UnsafeNativeMethods
{
[DllImport("user32.dll", CharSet = CharSet.Auto, ExactSpelling = true)]
internal static extern int ShowCursor([MarshalAs(UnmanagedType.Bool)]bool bShow);
}

[Visual Basic]

Imports System
Imports System.Runtime.InteropServices
Imports System.Security
Imports System.Security.Permissions

Public NotInheritable Class Cursor

Private Sub New()
End Sub

    ' Callers do not require Unmanaged permission, however,
    ' they do require UIPermission.AllWindows
    Public Shared Sub Hide()

        ' Need to demand an appropriate permission
        ' in place of UnmanagedCode permission as
        ' ShowCursor is not considered a safe method
        Dim permission As New UIPermission(UIPermissionWindow.AllWindows)
        permission.Demand()

        UnsafeNativeMethods.ShowCursor(False)

    End Sub

End Class

<SuppressUnmanagedCodeSecurityAttribute()> _
Friend NotInheritable Class UnsafeNativeMethods

Private Sub New()
End Sub

    <DllImport("user32.dll", CharSet:=CharSet.Auto, ExactSpelling:=True)> _
    Friend Shared Function ShowCursor(<MarshalAs(UnmanagedType.Bool)> ByVal bShow As Boolean) As Integer
    End Function

End Class

In the above example, although the assembly that defines Cursor.Hide still requires UnmanagedCode permission, any callers of it do not. In place of UnmanagedCode however, callers will require UIPermission.AllWindows.

FAQ: What is the GlobalSuppressions.cs/GlobalSuppressions.vb file and why is it needed? Is it possible to change the name of this file? [David Kean]

David M. Kean — Thu, 28 Dec 2006 20:00:00 GMT

I've noticed that Code Analysis sometimes places suppressions in a file called GlobalSuppression.cs (GlobalSuppressions.vb in Visual Basic). Why this is file needed and it is possible to change its name?

What is this file?

When you right-click on a warning and choose Suppress Message(s), Code Analysis checks to see if the warning was raised against an element that exists within source. If it does, such as in the case of a type or a member, then the suppression is applied against the element itself. This is called In-Source Suppression because the suppression is applied in-source alongside the target of the warning.

The following sequence shows this:

The user right-clicks on a warning raised against a property and chooses Suppress Message(s).
The suppression (via use of the SuppressMessageAttribute) is applied against the property.

If the warning was raised against an element that does not live in source, such as namespaces*, assemblies and or any other element without source information (ie compiler generated constructors), then Code Analysis places the suppression, by default, in a file called GlobalSuppression.cs (GlobalSuppression.vb in Visual Basic). This is currently called Module-Level Suppression or Assembly-Level Suppression because the suppression is applied at the assembly-level using the [assembly:] declarator, however, as warnings can be raised and suppressed against both a module and assembly at this level, this is confusing terminology and in future versions of Visual Studio this name will likely change.

*Although technically namespaces do live within source files, they do not have a representation in the Common Intermediate Language (CIL) and therefore you cannot apply attributes against them.

The following sequence shows this:

The user right-clicks on a warning raised against an assembly and chooses Suppress Message(s).
The suppression (via use of the SuppressMessageAttribute) is applied against the assembly in GlobalSuppression.cs.

As you can see from above, GlobalSuppression.cs/GlobalSuppression.vb exists to store suppressions against elements without source information. If this file does not exist within the project, then Code Analysis will automatically create it.

Note: Starting in Orcas, it will become possible to choose whether to apply a suppression against a element containing source information as an in-source or module-level suppression.

How do I change the name of this file?

While not very obvious, it is possible to change the name of the Global Suppression file that Code Analysis stores these Module-Level Suppressions in.

To change the name, do the following:

Open your project in Visual Studio
In Solution Explorer, right-click the project and choose Properties
In the Project Properties window, choose the Code Analysis tab
In the Code Analysis tab, choose the rules you want for your minbar
In Solution Explorer, right-click the project and choose Unload Project, answering Yes to any prompt to save changes
In Solution Explorer, right-click the project and choose Edit

Add the following <CodeAnalysisModuleSuppressionsFile> element to the project, replacing [name] with the new name (without path information) of the Global Suppressions file (for example Suppressions.cs):

<PropertyGroup>
<CodeAnalysisModuleSuppressionsFile>[name]</CodeAnalysisModuleSuppressionsFile>

[...]

</Project>

If you want all your projects to use the same name, see the following: FAQ: How do I share Managed Code Analysis rule settings over multiple projects?

FAQ: How do I share Managed Code Analysis rule settings over multiple projects? [David Kean]

David M. Kean — Thu, 16 Nov 2006 20:51:00 GMT

If your team has a minbar of Managed Code Analysis rules that must be explicitly fixed or suppressed, it is possible to share the Managed Code Analysis rule settings over multiple MSBuild projects (.csproj, .vbproj).

To share the minbar between multiple projects, do the following:

Using Visual Studio, create a new empty project
In Solution Explorer, right-click the project and choose Properties
In the Project Properties window, choose the Code Analysis tab
In the Code Analysis tab, choose the rules you want for your minbar
In Solution Explorer, right-click the project and choose Unload Project, answering Yes to any prompt to save changes
In Solution Explorer, right-click the project and choose Edit
Search for the <CodeAnalysisRules> element and copy the text within it
Create an empty text file called [team].CodeAnalysis.Rules.targets, replacing [team] with the name of your team

In the text file enter the following, replacing [rulesettings] with the text copied above in Step 6:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <PropertyGroup>
      <CodeAnalysisRules>$(CodeAnalysisRules);[rulesettings]</CodeAnalysisRules>
   </PropertyGroup>
</Project>

If you do not want developers to be able to turn on extra rules over and above the minbar, do not add the '$(CodeAnalysisRules);' text.

Using Visual Studio, open your projects
In Solution Explorer, right-click a project and choose Unload Project
In Solution Explorer, right-click the unloaded project and choose Edit
Add the following <Import> element to the project, replacing [path] with the path of the targets file created above. This needs to be the last line (just above the closing </Project> element) to ensure that settings within the project do not override the team settings:

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

[...]

<Import Project="[path]" />
</Project>
Repeat from Step 11 for each project you want to share the rule settings with

Any projects that imported the common rule settings via Step 9, should now reflect these settings in the Code Analysis properties pane. You can also share any MSBuild properties using similar steps.

Please Note: In order to avoid Visual Studio prompting about unsafe imported MSBuild projects, you need to explicitly trust the [team].CodeAnalysis.Rules.targets file. To do this, use the following:

Run regedit
Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\MSBuild\SafeImports
Add a new string value called [team].CodeAnalysis.Rules.targets and set its value to the full path of the targets file.

FAQ: Why is FxCop 1.32 not available for download? [David Kean]

David M. Kean — Wed, 12 Jul 2006 05:22:00 GMT

Update: While SharePoint Portal Server 2003 will not run side-by-side with .NET 2.0, SharePoint Portal Server 2003 SP2 will. For more information, see: http://support.microsoft.com/kb/907763.

We have had a lot of users contacting us since we released FxCop 1.35, asking for a link to be able to download a copy of FxCop 1.32. There appears to be some misconceptions with FxCop 1.35 that we thought we would try to clear up in this post.

Misconception #1: FxCop only analyzes .NET 2.0 assemblies.
Although FxCop 1.35 does require the .NET Framework 2.0 to be installed, it can analyze assemblies compiled against all versions of .NET, including .NET 1.0 and .NET 1.1.

Misconception #2: .NET 1.x and .NET 2.0 cannot be installed on the same system.
Both .NET 1.x and .NET 2.0 and Visual Studio 2002/2003 and Visual Studio 2005 can be happily run side-by-side on a system without affecting each other. If you do find any bugs with these configurations, then we need to know about it.

Misconception #3: FxCop 1.35 requires Visual Studio 2005.
FxCop 1.35 does not and never has, required any version of Visual Studio to be installed.

There are also a number of other reasons why we have not made FxCop 1.32 available:

Bugs. 1.32 is over a year old; since then, there have been 150+ bug fixes, (including all in Visual Studio 2005 Code Analysis), that all made it into 1.35.
Security. As part of the bugs fixes, we fixed some of the security rules that were giving completely wrong analysis. Because of this, you do not want to base any security decisions based on the analysis that 1.32 gives.
Noise Reduction. For 1.35, we have made significant changes to the amount of noise that FxCop fires against code, including generated and C++/CLI.
Support. FxCop is, officially, an unsupported tool, however, individual members of the Code Analysis team spend a significant amount of work (and personal) time in the FxCop forums answering questions. Attempting to support old versions of FxCop means that we spend less time working on newer features and better analysis for our customers.

If the above doesn't convince you to move FxCop 1.35, there are also a number of new features such as 5 new rules, in source suppression and GAC support.

FAQ: Why does FxCop warn against catch(Exception)? - Part 3 [Nick Guerrera]

nicholg — Tue, 20 Jun 2006 07:16:00 GMT

This is the third installment in a three-part series on why FxCop warns against catch(Exception):
FAQ: Why does FxCop warn against catch(Exception)? - Part 1
FAQ: Why does FxCop warn against catch(Exception)? - Part 2
FAQ: Why does FxCop warn against catch(Exception)? - Part 3

I said from the beginning that this issue is controversial, and some of your feedback certainly confirms that. I want to make it clear that I respect everyone’s right to disagree with me, to exclude or disable the FxCop warning, and to implement a less rigid exception policy in their application code as they see fit. Furthermore, all of the opinions I’ve expressed are entirely my own and they represent a stricter interpretation of the Framework Design Guidelines than absolutely required. I believe strongly that the approach that I’ve outlined helps to find and fix defects sooner during development and testing and therefore helps to deliver more robust production software. Nevertheless, the choice to adopt a different strategy for your application is entirely yours.

On the other hand, as I mentioned in the previous post, this FxCop rule is of paramount importance for class library code. When class libraries call back to application code (via virtual methods, interface methods, events, or delegates), it is disastrous if they swallow or disguise the arbitrary exceptions that may be raised. (To see just how aggravating this can be for library consumers, witness the frustration with the WebBrowser control that readers expressed earlier.) Furthermore, class library code cannot make any assumptions about the implications of arbitrary exceptions for application code further up the call stack, so it must let them go so that the application can decide how to handle them.

With that said, let me now address the most recent comments with more of my own personal opinions. :)

Jeremy: “… I hope you do realize that a number of the recommendations you have given to people, myself included, basically amount to ‘let your app crash, your customers and business partners be damned.’ …"

No, I most certainly do not realize that, because it’s simply not true. Applications which catch only the precise exceptions that they are prepared to handle gracefully are easier to develop and maintain over the long run. When this strategy is combined with strong testing, the application will ship with fewer defects and there will be very few unhandled exceptions in the wild. The truth is that once an unexpected exception has been raised in your application, customers and partners are likely to suffer one way or another. The impact of corrupt program state can range from security vulnerability to plain incorrect output, which can end up costing customers more time and money than dealing with a crash.

Please don’t misconstrue this to mean that it’s ok to write sloppy software which crashes regularly in common cases. Clearly that’s unacceptable and I never said otherwise. However, the right way to avoid this fate is to design your software carefully, implement it methodically, and test it thoroughly.

Jeremy: “I think all of your readers know full well that applications need to be designed to fail fast and do so clearly in order to ease the diagnosis and correction of software defects.”

I’m glad that we agree that applications should be designed to “fail fast.” From my point of view, once an exception is raised in your application and you haven’t decided exactly how to handle it on its own terms, then the application has already “failed” and process termination represents the “fast” part of the equation. :)

Jeremy: “We do this, however, by modularizing software and testing it at an appropriate level of granularity, not by letting the whole app fall down in production.”

I do agree that it’s possible to sandbox components (for example, by using separate app-domains and ensuring that all shared data is immutable) such that the failure of a single component does not imply failure for the entire process. This then becomes, as you say, a question of granularity. You can think of each component as a mini-process, and then apply all of my arguments on a component-by-component basis. That is to say that when an isolated component throws an unexpected exception, its state must be discarded and it must be reloaded before it can reliably be consumed again. If your application is hardened in this way, then you would in fact need to catch (Exception) in all of the locations that you mentioned in your first comment in order to save the host process from termination. I missed that in my original reply and I apologize.

However, I’d like to point out that it’s difficult and costly to implement this strategy correctly and I still maintain that the approach I've been recommending is perfectly viable for most applications.

Jeremy: “Your recommendations will only work well for the people replying to your posts if you are interested in personally supporting their products when deployed in the field.”

Given the choice between an application that abuses catch (Exception) and another which catches only the exceptions that it can handle gracefully, I'd choose to support the second application in a heart-beat.

Jeremy: “Their customers and partners don't care about what FxCop might have recommended to the developer.”

Not directly, but they do care about software quality, reliability, and overall correctness. Let’s take two familiar examples: Microsoft Excel and the C# compiler. I don’t want Excel to crash, but it would be much worse if it ever produced an incorrect value in a spreadsheet that I use to manage my personal finances. Similarly, I prefer to see the compiler ICE (Internal Compiler Error) in favor of emitting bad code. Of course, in an ideal world, Excel would never crash and the compiler would never ICE, but I’ve seen both happen and I’m sure it was in my best interest even if it upset me at the time.

Niall: “I think you have to realise that exception handling is not just for the developer's benefit. The application is there to serve the user, not the developer, so simply bombing out because you can't display a new form is going to require the user to restart the application more than is really required.”

Yes, the application is there to serve the user, not the developer and I couldn’t agree more. In that situation, you have to ask yourself why you couldn’t display the form. If the only reason you can provide is that your catch (Exception) block was hit, then you really have no idea whether it’s in the best interest of the user to continue executing. For example, what if one of your assemblies just failed to load, or you’ve run out of memory, or the root cause is actually a corruption in shared data? What will go wrong next? On the other hand, if you catch (IOException) while trying to read the CSV file that will ultimately be used to populate the new form, then you know beyond a shadow of a doubt that the correct application behavior is to inform the user that the file could not be opened and allow them to continue to use the application which remains in a consistent state.

Niall: “In a previous project I worked on, we had a lot of places where exceptions were caught and error reports were sent back to the dev team. Therefore, the exceptions weren't just disappearing quietly, they were known to the developers.

In many circumstances, the application would then continue. This is because a lot of our handling of exceptions would result in the form the exception came from closing or not appearing. Basically that element of the workflow did not occur. For almost all cases, this left the application in a state that allowed it to continue without problems. Of course, it wasn't 100% perfect. We did have a threshold of a certain number of exception reports in a certain amount of time would cause the handler to exit the app, though.”

Both exception logging and using an exception count threshold are popular approaches for applications which catch all exceptions in places. In fact, this is actually exactly how the current version of FxCop works. Our experience with FxCop’s current exception handling policy has not been positive at all and so I would not suggest this approach universally. Nevertheless, as the application developer, it’s up to you to choose the appropriate policy.

Niall: “Especially when the environment is such that you cannot deploy a fix at a day's notice, having the users restarting the application frequently when you could provide better is basically developing to suit the developers instead of the users.”

If it turns out that your application is crashing “frequently” enough that users have to restart it all the time, then it wasn’t ready to ship in the first place. By the time you’re ready to ship, you should have uncovered nearly all of the exceptions that you need to handle or prevent, and those that remain should be extremely uncommon. Besides careful testing on your end during the development cycle, it’s important to provide regular preview releases for your customers and partners to pound on. During that time, it will be invaluable that exception-related bugs are easy to diagnose and fix quickly. By the time you ship, you will have software which neither crashes nor swallows bugs!

Niall: “Of course, it can make diagnosing problems more difficult, but the role of the software is to make the user's job easier, not the developer's. Sometimes the developer just has to work a bit harder because otherwise the work goes on the user's plate.”

I never meant to imply that ease of diagnosis is an end unto itself. It is a means through which you can deliver better software with fewer defects, which most definitely serves to make the user’s life easier. Indeed, the developer often does have to work harder: uncovering the specific exceptions that need to be handled and the additional code that needs to be in place to prevent the others is often harder than slapping in an additional catch (Exception) block, but it’s the right thing to do…

FAQ: Why does FxCop warn against catch(Exception)? - Part 2 [Nick Guerrera]

nicholg — Sun, 18 Jun 2006 08:04:00 GMT

This is the second installment in a three-part series on why FxCop warns against catch(Exception):
FAQ: Why does FxCop warn against catch(Exception)? - Part 1
FAQ: Why does FxCop warn against catch(Exception)? - Part 2
FAQ: Why does FxCop warn against catch(Exception)? - Part 3

On Wednesday, I explained why catch (Exception) is a bad idea, and many of you replied with interesting comments. Since it was too cumbersome to write everything I had to say in the comments section, I’ve replied to your comments below.

K: “Do you have a list of the 'unchecked' exceptions?”

No. I don’t have a definitive list of the exceptions which should always be prevented and never caught. The best advice I can offer here is to follow the API documentation on a case-by-case basis. Don’t immediately assume that you need catch blocks for each of the exceptions that are listed in the documentation for a particular API. Instead, for each exception, ask you yourself if there’s a simple way to prevent it. If there is, then put in the preventative code and leave out the catch block.

This can be tough to discern in some circumstances. For example, it may seem that a call to File.Exists can prevent FileNotFoundException, but there’s a race condition where the operation will still fail if the file is deleted in between the time File.Exists returns true and the call is initiated. Also, there are some methods in the .NET Framework which misuse exception types. For example, in an ideal world, you should never catch ArgumentException, but Enum.Parse throws it to indicate that the input does not represent one of the enum values. Since there’s no way to prevent that short of rewriting Enum.Parse, you have to consider ArgumentException ‘checked’ in that specific case.

If you’re unsure about a specific API, try asking for help on http://forums.microsoft.com

Gill: “… there is one issue that troubles me: what if my program handles 10 specific exceptions I defined in the same way (when all these exceptions hint at different problems that are related), in this case I would want some catch blocks to perform the same code. If these exceptions don't share a common base, there is no way to make all of them perform the same code short of using the same lines (or method call) in each catch block.”

I don’t think there are that many methods out there which throw 10 unrelated and unpreventable exceptions, but I can relate to your frustration with API which throw unrelated exceptions to indicate related failures. Refactoring the shared handler code in to a helper method is the simplest way to deal with the issue. If you find yourself catching the same set of exceptions from the same method in more than one place, consider refactoring out the entire try/catch/catch/… series in to a helper method of its own.

Gill: “Furthermore, if all developers worked correctly and used this guideline my code might be facing unexpected exceptions from 3rd party code bugs. If this 3rd party isn't available to fix the bug, my program can fail at unexpected times.”

I don’t follow the reasoning here. If you hit a bug in 3^rd party code, then catch (Exception) is just going to make things worse. You should treat this unhandled exception no different from any other. It may turn out that you can work around the problem by using the API differently or adding a catch handler for the specific exception type that was raised if it turns out to be recoverable.

Richard: “Of course, it would help if the Exception class was abstract, and the Framework never threw a general Exception! For example, try calling System.Drawing.ColorTranslator.FromHtml("#aaax")”

Youch! You’re right; it’s absolutely terrible to throw an instance of System.Exception and FxCop warns against that as well. I will do my best to argue for reopening and fixing this bug!

Anonymous: “If my program has a feature to auto-save unsaved work every 10 minutes, and the auto-save procedure (which may use a third-party library) throws an unchecked exception, are you suggesting that the program should simply crash out, because this exception must not be handled?”

Yes, that is in fact exactly what I’m suggesting. A bug is a bug is a bug. It doesn’t matter if it’s in your code or 3^rd party code, catch (Exception) will just make it harder to find and fix. Having an auto-save feature is a great way to mitigate the risk of data loss. However, if the auto-save code itself is buggy, then all bets are off. It’s sort of like discovering that your parachute won’t open…

Jeff: “Well here is my slight problem with this. The best example I can give you as to why you absolutely have [to] Catch(Exception ex) to do this is a bug I reported back in Beta 2 … The Browser Control …”

Chris: “… the WebBrowser control will silently eat the NullReferenceException. I want to know when if my code has a bug, but the WebBrowser hides my bugs.”

That’s awful! I will talk to the owners of the Web browser control about getting this fixed. One of the things that I failed to mention in my original post is that it’s much worse to swallow exceptions in library code than in application code. If you’re developing a reusable library, this rule (like many others in FxCop) is doubly important!

Pop Catalin Sever: “Let the entire application crash? Are you kidding? That's really unacceptable. And btw if you notify the user that something bad has happened in most cases he will help out recover the application or some data. If you just let the application close I think that very likely you're going to be in big trouble.”

Let the application continue to run in an indeterminate state and carelessly corrupt data? Are you kidding? ;)

While I agree that the user should be notified that something has gone wrong, I don’t agree that the application should continue running afterwards. Instead, a friendly dialog should allow the user to send an error report before the application closes. If data loss is a potential issue in your application, then implement an auto-save feature. It’s worth noting that this is exactly the approach that’s used in Microsoft Office.

Beginning in .NET 2.0, you don’t need to implement the crash dialog box yourself. If you let the exception go unhandled, a default dialog box will be displayed that allows the user to send an error report to Microsoft. Note that for Windows Forms applications, you need to call Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException) to make this work.

If you prefer, you can hook the AppDomain.UnhandledException event and display your own dialog that allows users to send a bug report directly to you.

Jeremy: “Here are another three cases where you absolutely must catch Exception (and at the very least provide for adequate logging, even if you then rethrow):

1. In every method you spin up in a new thread.
2. In every method called arbitrarily on threads you don't control (ie. WebMethods, methods exposed via remoting, delegates passed across remoting, windows service control overrides, etc.)
3. Main

Seeing a pattern here? :)”

It sounds like you got burned by the default exception handling policy for secondary threads in .NET 1.0 and 1.1. Thankfully, the situation is vastly improved in .NET 2.0. See http://msdn2.microsoft.com/en-us/library/ms228965.aspx.

If you can’t move to 2.0 just yet, then a better approach than sprinkling catch (Exception) in all of these places is to hook AppDomain.UnhandledException (and Application.ThreadException for Windows Forms applications). In your handler, you can throw up a dialog like the default dialog in .NET 2.0 and call Environment.Exit afterwards.

FAQ: Why does FxCop warn against catch(Exception)? - Part 1 [Nick Guerrera]

nicholg — Thu, 15 Jun 2006 09:11:00 GMT

This is the first installment in a three-part series on why FxCop warns against catch(Exception):
FAQ: Why does FxCop warn against catch(Exception)? - Part 1
FAQ: Why does FxCop warn against catch(Exception)? - Part 2
FAQ: Why does FxCop warn against catch(Exception)? - Part 3

This question comes up a lot, and I think there’s a lot of confusion and controversy about the rule. Many people seem to think that it’s noisy, annoying, and not worth their time. I find that very unfortunate because following its guidance can really help you build better software. Here’s my attempt to convince the Nay-Sayers that catch(Exception) is almost always a terrible idea.

I’ve heard a lot of arguments against DoNotCatchGeneralExceptionTypes, but they generally boil down to one or both of the following:

“If I call an API which doesn’t document which exceptions it can throw, then I have no choice but to catch all possible exceptions!”
“My application needs to be robust; it can’t crash just because of an exception that I forgot to handle!”

Both arguments are ill-conceived because they presume that you can handle an exception even if you don’t know what failure it represents or how it impacts the code that will execute next. There’s an implicit assumption in both arguments that the mere act of catching an exception is equivalent to handling it appropriately, which simply isn’t true.

For the sake of the discussion to follow, exceptions can be divided in to two general categories:

Those that signal bugs (i.e. API misuse), or catastrophic system failures
(e.g. ArgumentException, NullReferenceException, ExecutionEngineException.)
Those that signal unpreventable yet recoverable error conditions.
(e.g. FileNotFoundException, SocketException.)

In languages like Java, which have a notion of checked exceptions, only exceptions of the second kind are eligible to be checked while exceptions of the first kind must be left unchecked. On that basis and for lack of better terminology, I will hereafter refer to exceptions in the first bucket as ‘unchecked’ and exceptions in the second bucket as ‘checked’. (Note the quotes.) I am using the terms loosely to mean that if exceptions were checked in .NET, then those in the first bucket would remain unchecked while those in the second bucket could become checked.

Independent of where you stand on the checked exception debate, this distinction is very important to hold in your mind when writing exception handling code. In particular, do you really ever want to catch the ‘unchecked’ exceptions at all? Probably not! Instead, you should prevent them from occurring in the first place. For example, check if a variable is null before dereferencing it, don’t catch (NullReferenceException).

If a bug in your code manifests itself as an exception (and most of the ‘unchecked’ exceptions are just that), then it’s best to let the application terminate right at the point of failure. When the bug is discovered, you’ll get exactly the diagnostic information you need to fix it quickly, add the appropriate regression tests, and move on. On the other hand, debugging a system which aggressively swallows general exceptions feels like you’re one of the police investigators in “CSI: Miami”. The culprit has left the crime scene and you have to work backwards from the subtle clues in your program’s incorrect behavior.

And that’s the principal reason to avoid catch (Exception): it hides bugs in your code. These bugs are far more costly to resolve and since they can go undetected, the quality of your software suffers.

Some readers might be thinking that it would be helpful if the .NET Framework exception class hierarchy reflected the ‘checked’ vs. ‘unchecked’ nature of exceptions. In fact, it’s rather seductive to imagine a base class, say System.CheckedException, for all of the ‘checked’ exceptions. The argument follows that you could then replace catch (Exception) with catch (CheckedException)… and the problem would be solved since you no longer catch those insidious ‘unchecked’ exceptions. Unfortunately, this approach would be just as flawed. FxCop would still warn against catch (CheckedException) because it’s still far too general. By definition, ‘checked’ exceptions are unpreventable and must therefore be caught. Nevertheless, catching them is the easy part; the hard part is deciding what to do next, and that decision is purely a function of the specific exception type and it’s meaning in the given context. For example, to recover from FileNotFoundException for your configuration file, you might use a default configuration, and to recover from a SocketException, you might fall back to a local store until the network becomes available again. However, if you don’t know what to do about it, then let it go.

Returning to the first argument against this rule, please don’t get me wrong, I definitely empathize with the need for accurate exception information in API documentation. However, in the absence of such documentation, the safest approach is to treat all API as
“innocent until proven guilty.” Wait until you have hard evidence that a particular exception can be raised before you attempt to handle it.

Also, be sure to test your exception handling code. For example, delete a file out from underneath your application while it’s running and see how it deals with FileNotFoundException. It’s simply not sufficient to write optimistic and untested code, just because the exception is mentioned in the API documentation. I can’t tell you how many times I’ve seen untested catch handlers fail to work as expected. The classic example is a formatting exception raised in the error message that’s never provoked from a test. Spurious and unnecessary catch (Exception) blocks can completely torpedo your code coverage! (Remember: if it’s not tested, it’s broken.)

One important thing to note is that if you follow our advice and catch fewer exceptions, then exceptions will naturally travel further up the call stack. Sometimes they’ll terminate the application, but other times someone further up the call stack will know what to do and your only job is to clean up after yourself in finally blocks as the stack unwinds.

To summarize, here are some important things to consider when dealing with exceptions in managed code:

Do not catch preventable (‘unchecked’) exceptions.
Only catch the specific unpreventable (‘checked’) exceptions that you are certain can be raised and that you know how to handle.
Test your exception handling code.
Use finally blocks liberally for clean-up code to keep your state as consistent as possible in case an exception that you cannot handle needs to be handled further up the stack.

And finally, I’d like to point out that our team has learned this lesson the hard way. There are actually far too many catch (Exception) blocks in FxCop itself and it has caused us a great deal of grief. We’re working on removing them and I’m confident it will help us to deliver better software!