Code Analysis Team Blog : Configuration

Code Metrics Customization

conorm — Fri, 16 Nov 2007 02:54:22 GMT

A number of people have asked:

Is there a way to customize the existing code metrics or add additional ones?

The simple answer at this time is No. There are no extension points or customizations available at this time for code metrics. This feature was added late in the cycle for VS 2008 and we were out of time to design and add the required hooks. We will use this release to gather feedback about the sorts of extensions you want.

To that end please feel free to respond to this post with information about any customizations or additional metrics that would be of interest to you. This will help us a lot in our future planning.

New for Visual Studio 2008 - Code Analysis Policy improvements

David M. Kean — Thu, 20 Sep 2007 17:00:00 GMT

One not very well known feature that lights up when connected to a Team Foundation Server, is the ability to enforce that Code Analysis be run before every check-in. Called a Code Analysis Policy, this feature allows your team to find and fix Code Analysis warnings earlier in the product cycle rather than later, where code changes are riskier and more expensive to make.

To add a Code Analysis Policy to a Team Project, see the following topic on the MSDN Library, How to: Add Check-In Policies.

In Visual Studio 2005, while a useful feature, there were a few usability issues that customers ran into time and time again:

Migrating the Code Analysis settings stored in the policy on the Team Foundation Server to the individual projects was confusing. At times, I literally sat in amazement as I watched my own colleagues new to Code Analysis Policy struggle to perform the (what should have been an easy) task of finding a menu item.
Once the settings had been migrated, users were confused as to why the settings in the individual projects didn't match exactly what was stored in the project. For example, rules turned off in the policy, were still turned on in the project.

Our team actually knew about the confusion that issue 2 would cause when Visual Studio 2005 shipped. Surprisingly as it sounds, this behavior was actually the lesser of two evils. With the time that was available in the ship cycle they knew that they had two distinct choices, either a) have the policy completely override the settings stored in the project, or b) merge the policy settings with the project settings. Because a) prevented the scenario of allowing users to turn on more rules than the policy specified (in effect being stricter than the policy), the later was chosen as the preferred behavior.

Issue 1 was somewhat of a surprise. Code Analysis Policy along with the rest of Code Analysis was a late edition to Visual Studio 2005, probably too late to get any real user feedback and perform any actionable usability studies. We didn't hear about the troubles users were having with this until after the product had already shipped.

Once Visual Studio 2008 planning began, improving both of these issues was one of our top priorities, so we set about a feature crew to fix it.

Code Analysis Policy Failure Details dialog

Clearly users were first of all struggling to actually perform the migration; they were told by the Policy Failure that their projects settings were out-of-date, but not actually how to go about updating them. Even if they somehow figured out that a menu item might do this, looking intuitively on the individual project's context menus didn't help - the menu item that performed the job, Migrate Code Analysis Policy Settings to Solution (what a mouthful!), was hidden under File -> Source Control and on the solution's context menu.

The first thing we did to solve this confusion was to add a new dialog (displayed when double-clicking on a Code Analysis policy failure) that provided extra information about the situation they were in, what projects were out-of-date and how to go about solving it.

We also chose to tell them at this time that their build date was out-of-date - something that we previously only told them after they had updated their project settings and then attempted to check-in again (breaking their workflow).

New Policy Menu Items

The way to solve the second issue was easy; provide the user a choice:

Some users preferred policy to win out and completely overwrite the local project settings, whereas, others wanted to be able to specify additional rules above and beyond what was specified in the policy (ie the current Visual Studio 2005 behavior). The new Analyze menu (which I'll talk about in a future post), now provides two menu items, Replace with Check-in Policy and Merge with Check-in Policy, for performing both of these actions, respectively.

Hopefully these changes will make using Code Analysis Policy a little more pleasant experience in Visual Studio 2008. The new dialog and menu items themselves made into Beta 2 (albeit with slightly different text and names), so install it today and tell what you think.

New for Visual Studio 2008 - Custom Dictionaries

David M. Kean — Mon, 20 Aug 2007 17:00:00 GMT

Once you turn on the new spelling rules that we've added to Visual Studio 2008, you will want to start to customize the words that it fires on; this is where the new custom dictionary support comes in. A custom dictionary in its basic form, similar to the concept in Microsoft Word, allows you to silence the spell checker over the words that are not in the standard dictionary, such as company and product names.

Adding a custom dictionary to a project

To add a custom dictionary to a C# and Visual Basic project is simple:

In Solution Explorer, right-click on the project and choose Add -> New Item...
Under Templates, select XML File, enter a name for the dictionary, such as CodeAnalysisDictionary.xml and click Add
In Solution Explorer, right-click on the XML file and choose Properties
In the Properties tool window, under Build Action choose CodeAnalysisDictionary
In Solution Explorer, double-click on the newly created dictionary to open it
In the XML editor, paste the following, replacing [productname] and [companyname] with your team's equivalents:

<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
    <Words>
        <Recognized>
            <Word>[productname]</Word>
            <Word>[companyname]</Word>
        </Recognized>
    </Words>
</Dictionary>

You are now ready to start entering your own custom words. Simply add a new <Word> element for each word in your project that does not exist in the dictionary. Each word is case-insensitive, so any casing of the word will be recognized. Code Analysis will automatically pick up the custom dictionary the next time it is run.

Sharing a custom dictionary between projects

Once you have worked through the above steps, the following will be added automatically to your MSBuild-based project (ie csproj or vbproj):

This means that similar to other Code Analysis properties and items, this information can be placed a common targets file to be shared by multiple projects.

If you do not want to have all projects share a common MSBuild targets file, you can instead do the following:

Place the custom dictionary file created above in a shared location, such as alongside the solution
In Solution Explorer, right-click on a project and choose Add Item...
Browse to and click the custom dictionary to select it
On the Add button, click the down arrow to drop a menu and choose Add As Link
In Solution Explorer, right-click on the custom dictionary and choose Properties
In the Properties tool window, under Build Action choose CodeAnalysisDictionary
Repeat steps 2 - 6 for each project you want to share the custom dictionary

Advanced usage of a custom dictionary

I have shown you above basic usage of the new dictionary support the Code Analysis team has added to Visual Studio 2008. Those that have previously used custom dictionaries with FxCop, will realize that there are more things that you can add to these files that will customize other naming-based rules. However, for now I will leave you with the above and talk about advanced usage of a custom dictionary in future posts.

New for Visual Studio 2008 - Spelling rules

David M. Kean — Sun, 12 Aug 2007 17:00:00 GMT

Surprisingly, one the biggest requests for Code Analysis in Visual Studio 2005 was to include the spelling rules that shipped with the FxCop standalone. We had Microsoft consultants tell us that they actually had trouble moving some customers from FxCop to Code Analysis because they were not included. Apparently teams care about spelling. :)

Well, we've listened and I'm glad to tell you that we are shipping the following rules in Visual Studio 2008:

IdentifiersShouldBeSpelledCorrectly
CompoundWordsShouldBeCasedCorrectly
ResourceStringsShouldBeSpelledCorrectly
ResourceStringCompoundWordsShouldBeCasedCorrectly

These new rules (along with the rest of the previously FxCop-only rules) now cause the analysis in Visual Studio 2008 to become a true superset of what is available in FxCop.

API Rules

By default, the IdentifiersShouldBeSpelledCorrectly and CompoundWordsShouldBeCasedCorrectly, which both fire on the naming of API members, use the installed language of Visual Studio to determine the locale to spell check the identifiers in. To customize this, simply add the <CodeAnalysisCulture> MSBuild property to your project with a culture representing the language of the API you are writing:

It is advisable to explicitly specify above when you have developers working on different languages versions of Visual Studio. Unfortunately, due to some complex licensing reasons, we were only able to ship the English lexicons so only the English-based (en-US, en-GB, en-CA and en-AU in particular) cultures actually affect the spell checker. All other cultures cause the rules to silently disable themselves.

Resource Rules

The <CodeAnalysisCulture> property is used to indicate the language of your API identifiers; it is not, however, used to determine the language of your ResX-based resources. Instead, for these we use the same mechanism that the runtime uses (or more correctly, what the ResourceManager uses) to locate resources; the AssemblyCultureAttribute and the NeutralResourcesLanguageAttribute attributes. The former is applied to satellitte assemblies and should never be placed on an assembly with code. Whereas, the later is applied to an assembly with code to indicate the neutral culture of the assembly. These attributes are simply applied at the assembly level and are usually placed in each language's associated AssemblyInfo.cs/AssemblyInfo.vb file. The same cultures as above are supported.

Without one of these attributes on your assembly, the resources contained within it will never be checked by ResourceStringsShouldBeSpelledCorrectly and ResourceStringCompoundWordsShouldBeCasedCorrectly. Luckily, If you forget to apply the attribute, Mark assemblies with NeutralResourceLanguageAttribute, a new performance rule we've added, will remind you.

As you start to running the spelling rules - you might find that you need to add to the list of words that it recognizes - in the next post I will talk about the new custom dictionary support that we've added to Visual Studio 2008.

$(CodeAnalysisTreatWarningsAsErrors) MSBuild property

David M. Kean — Wed, 08 Aug 2007 10:00:00 GMT

For Visual Studio 2008, we have added a new MSBuild property that allows you to easily treat all Code Analysis warnings as build errors. This can be useful for example, if you want to force that any firing of a Code Analysis rule to break the build during a nightly Team Build without needing to individually set this for every rule.

To use, simply add the <CodeAnalysisTreatWarningsAsErrors> property to your project file (or a common targets file) and set it to true:

Now, in the next run of Code Analysis, all rules will be displayed as errors:

TIP: How to change the (Orcas) Managed Code Analysis naming/design rules to fire on internals

David M. Kean — Tue, 08 May 2007 18:00:00 GMT

A while ago I mentioned that FxCop (and hence Managed Code Analysis) naming and design rules only fire on publicly visible types and members.

As you may recall, there were a couple of reason for this:

The .NET Framework Design Guidelines, which FxCop/Managed Code Analysis enforces, only contains guidelines for publicly visible API. What internal Microsoft teams (and you) do with their internal types and members is completely up to them.
Noise. If you tend to wrap a lot of native types and members, then this internal API could be potentially fire numerous violations.

In that same post, I also showed how to override this behavior in in FxCop. Now, since then, I've been asked by a few readers on whether it was possible to do this within Visual Studio 2005, unfortunately, the answer up until now was no.

However, the good news is that in the newly released Visual Studio 'Orcas' Beta 1, we sneaked in a small feature in that allows you to override this on a per-project basis.

To turn it on, simply do the following:

Using Visual Studio, open your project
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

Under the first <PropertyGroup> element, add a new <CodeAnalysisOverrideRuleVisibilities> element with its value set to true:

In Solution Explorer, right-click the project and choose Reload Project, answering Yes to both prompts

The naming and design rules (such as IdentifiersShouldBeCasedCorrectly and IdentifiersShouldBeSpelledCorrectly) will now run against all types and members, not just those visible outside of the assembly.

If you want to enable this for all your projects, see the following: FAQ: How do I share Managed Code Analysis rule settings over multiple projects?.

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: 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.

TIP: How to quickly enable Code Analysis on multiple projects [David Kean]

David M. Kean — Fri, 11 Aug 2006 18:00:00 GMT

Daniel Fisher has posted a entry on using a macro to quickly enable Code Analysis on multiple projects. The macro also allows you to apply the same rule selections across an entire solution.

Thanks Daniel!

TIP: How to change the FxCop naming/design rules to fire on internals [David Kean]

David M. Kean — Wed, 09 Aug 2006 06:56:00 GMT

By default, the FxCop naming and design rules only fire on publicly visible types and members. There are a couple reasons for this:

The .NET Framework Design Guidelines, which FxCop enforces, only contains guidelines for publicly visible API. What internal Microsoft teams (and you) do with their internal types and members is completely up to them.
Noise. If you tend to wrap a lot of native types and members, then this internal API could be potentially fire numerous violations.

However, if you would feel like you would like to be consistent with both your internal and customer facing API, then a little known feature is the ability to override this default in FxCop.

To do this, simply do the following:

Using FxCop, open your FxCop project
Choose Project -> Options
Choose the Spelling & Analysis tab and check Run all overridable rules against all targets
Click OK

Unfortunately, it is not possible to currently change this in Visual Studio Code Analysis.

FAQ: How do I indicate to DoNotDeclareReadOnlyMutableReferenceTypes that a type is immutable? [David Kean]

David M. Kean — Wed, 05 Apr 2006 03:45:00 GMT

DoNotDeclareReadOnlyMutableReferenceTypes is a rule that checks for visible read-only fields that are mutable reference types (classes). A mutable type is a type whose instance data can be changed once it has been constructed. For example, the following type is considered mutable:

namespace Microsoft.Samples
{
    public class Mutable
    {
        private int _Value;

        public Mutable(int value)
        {
            _Value = value;
        }

        public int Value
        {
            get { return _Value; }
            set { _Value = value; }
        }
    }
} 

Whereas the following type is not, and is therefore considered immutable:

namespace Microsoft.Samples
{
    public class Immutable
    {
        private readonly int _Value;

        public Immutable(int value)
        {
            _Value = value;
        }

        public int Value
        {
            get { return _Value; }
        }
    }
} 

Although not strictly required, I find it good practice to place the readonly modifier on any member that shouldn’t be changed outside of the constructor.

Unfortunately, due to the complex and costly analysis required to differentiate between a mutable type and an immutable type, DoNotDeclareReadOnlyMutableReferenceTypes, simply fires on any reference type that isn’t in its list of known immutable Framework types.

For example, given the above two types, the following declarations would both be considered violations, even though the Immutable type is immutable:

namespace Microsoft.Samples
{
    public static class CommonDefaults
    {
        public static readonly Mutable DefaultMutable = new Mutable(1);             // CA2104: DoNotDeclareReadOnlyMutableReferenceTypes
        public static readonly Immutable DefaultImmutable = new Immutable(1);       // CA2104: DoNotDeclareReadOnlyMutableReferenceTypes
    }
} 

However, it is possible to change this. To make DoNotDeclareReadOnlyMutableReferenceTypes aware of your immutable types, simply do the following:

Using a text editor, create a new text file called ImmutableTypes.txt and place this file alongside your FxCop project file, or within the FxCop installation folder.
Using a new line for each type, enter the fully-qualified name of each class you want to mark as immutable, for example:

Microsoft.Samples.Immutable
Microsoft.Samples.Immutable1
Save the file and you’re done, FxCop will now consider these classes immutable.

Note: This requires FxCop 1.32 or above.

As always, if you have any questions or issues with FxCop or Managed Code Analysis (including the DoNotDeclareReadOnlyMutableReferenceTypes) head over to the FxCop Forum.