Code Analysis Team Blog : Rules

Fun with Code Analysis Rule Sets

cristend — Wed, 12 Nov 2008 22:55:00 GMT

Two weeks ago, I introduced you to Visual Studio 2010 September '08 CTP (Community Technology Preview). This CTP is available as a Virtual PC (VPC) image which can be downloaded at http://go.microsoft.com/fwlink/?LinkId=129231. The goal of the Community Technology Preview is to obtain feedback from our customers on the new scenarios we have enabled. If you haven't already downloaded the CTP, do it now and take it out for a spin.

There are many new cool features with the CTP such as an Historical Debugger and Impact Analysis of code changes, but today we are going to focus on Rule Sets for code analysis. (For an overview of all the neat stuff happening in code analysis, check out this PDC video http://mschnlnine.vo.llnwd.net/d1/pdc08/WMV-HQ/TL60.wmv ) Configuring code analysis in Visual Studio 2008 and earlier versions required evaluating each individual rule to determine whether it was important enough to turn on and fix for your project. This might be a very time-consuming process that made it difficult to make sure that the most important problems were identified and fixed. With rule sets, code analysis can now be configured much more quickly and easily with sets of rules that are targeted at specific scenarios or areas of emphasis. Let's take a look at how this works.

The following scenario comes from our CTP walkthrough. You can find the walkthrough and more details when you download the CTP as described above. Let's assume that you have the DinnerNow – Kiosk solution open and is the active project. On the Analyze menu, click Configure Code Analysis for DinnerNow.Restaurants.Kiosk. The property page for Code Analysis is displayed:

This screen tells us that Microsoft All Rules will be executed when we run code analysis, but what if we didn't want to run every Microsoft rule? What if we have a specific scenario we wish to target? We can change which rule set to run by clicking on Open which brings up:

We can select which rule set(s) by simply selecting or deselecting the appropriate box. Notice that each rule set has a brief description of the types of rules within the rule set. Further, you can open up each individual rule set and see the specific rules that make up the rules sets. You can also turn on or off individual rules within a rule set. Finally, you can adjust the type of action a rule will trigger. In the past, code analysis rules have been limited to build Warnings, but now you can elevate code analysis rules to build Errors.

As you can see, rules sets provide a powerful way to focus code analysis on the scenarios and rules that matter most to you. You can also create custom rule sets based on your specific needs. We wont go into it today, but if you download the CTP, the Walkthrough explains how to customize a rule set.

Give it a try and let us know what you think.

Cris

New Code Analysis Features in Visual Studio 2010 September '08 CTP

cristend — Thu, 30 Oct 2008 20:05:00 GMT

At this year's PDC, Microsoft released Visual Studio 2010 September '08 CTP (Community Technology Preview). This CTP is available as a Virtual PC (VPC) image which can be downloaded at http://go.microsoft.com/fwlink/?LinkId=129231. The goal of the Community Technology Preview is to obtain feedback from our customers on the new scenarios we have enabled. If you are interested in code analysis, you need to get this CTP and here is why.

The code analysis team is excited to share with you new code analysis features and rules in this CTP, including:

Rule sets - code analysis can now be configured much more quickly and easily with sets of rules that are targeted at specific scenarios or areas of emphasis
Enhanced policy support - enforce your rule set with the code analysis check-in policy
8 New Data Flow rules - find hard-to-detect flaws with these advanced dataflow rules for managed code; including certain SQL injection vulnerabilities

Included with the CTP is a walkthrough guide. Inside the walkthrough is a section dedicated to these exciting code analysis scenarios. Over the next couple of weeks we will continue to blog about rule sets, policy support, and data flow rules so be sure to come back after you get the CTP.

Now go get the CTP and starting sending us your feedback! http://go.microsoft.com/fwlink/?LinkId=129231

New for Visual Studio 2008 SP1 and FxCop 1.36 – Multi-targeting rule

David M. Kean — Mon, 25 Aug 2008 17:00:00 GMT

I've just published a post over my blog about a new feature we added for Visual Studio 2008 SP1 and FxCop 1.36.

New for Visual Studio 2008 SP1 and FxCop 1.36 – Multi-targeting rule

FxCop 1.36 Released!

brettwo — Tue, 19 Aug 2008 23:11:00 GMT

We are pleased to announce that we've released the next version of FxCop. This release has a number of changes since FxCop 1.36 Beta 2, including, but not limited to, the following:

Bug fixes that reduce noise, missing analysis and rule crashes.
New portability rule: Use Only API from Targeted Framework. This rule will fire when the target assembly taking a dependency on a new API only included in a later version or in a service pack.

New option for new portability rule for selecting target framework for analysis.

Set the target framework in the UI via Project -> Option -> Spelling & Analysis -> Target Framework
Set the target framework on the command-line via the /targetframeworkversion switch. e.g: /targetframeworkversion:v2.0, /targetframeworkversion:v3.0, or /targetframeworkversion:v3.5

Compared with FxCop 1.35, FxCop 1.36 Beta 2 had changes including, but not limited to, the following:

200+ bug fixes that reduce noise, missing analysis and rule crashes
Support for analyzing anonymous methods and lambda expressions
New option for skipping analysis over tool generated code

Turn this on in the UI via Project -> Options -> Spelling & Analysis -> Suppress analysis results against generated code
Turn this on on the command-line via the /ignoregeneratedcode switch.

Better support for C++/CLI and the Compact Framework
Language 'friendly' API names in the UI and resolutions (ie Visual Basic syntax if running over a Visual Basic binary)
New globalization, design and usage rules
Performance improvements that cut analysis by 2x and use half as much memory
Documentation that is now available on MSDN

There are also some other underlying changes that we will talk about in some future posts.

Download it, and tell us what you think. If you have any feedback, bug reports or any questions, feel free to head over to the Code Analysis forum and ask away.

Note: If you already have FxCop 1.36 Beta 2 installed, please uninstall it first before you install FxCop 1.36. Otherwise, you may see an error when you install FxCop 1.36 on top of FxCop 1.36 Beta 2.

If you accidentally install FxCop 1.36 without uninstalling FxCop 1.36 Beta 2, please go to Add/Remove program to uninstall FxCop 1.36, and reinstall FxCop 1.36.

[EDIT] Note: FxCop 1.36 RTM shipped with additional tracing turned on. This can make the FxCop output harder to read. To turn tracing off, edit the FxCop.exe.config or FxCopCmd.exe.config files in the FxCop install directory. Find the line that contains <add name="Trace" value="2" /> and change the "2" to "0".

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.

What rules do Microsoft have turned on internally?

David M. Kean — Thu, 09 Aug 2007 17:00:00 GMT

I've recently received a few requests asking about the Code Analysis rules we run internally against Microsoft's own code. While it might come as a surprise, we do not actually run every single rule against our own binaries. There are many reasons for this:

Applicability. Not every rule is applicable to every project, for example, the Design rules might be turned off if you are writing a Windows Application
Noise rate. Some rules have a low signal-to-noise ratio. While we try remove as much noise as possible from a rule, some rules, due to limitations in our analysis engine, still remain to be too noisy to be run regularly over large code bases. For example, some of the performance rules lack real context to make a good judge of whether a particular issue will really affect the performance of an application.
Time. We have to ship eventually - attempting to fix every single violation, for every single binary is just not feasible nor advisable. Therefore we make calls to turn off some rules that may lack value and do not impact the security of the product.

Please note that the following rule sets are applicable only to the Developer Division (although Windows does actually follow the same bar), other divisions, such as MSN, Office, etc each have their own set of enabled rules that may or may not be match what is shown below.

There are two rule sets; the first, Public Rule Set, is for assemblies that design for public consumption. That is, assemblies that are designed to have user take a reference to them in their own projects (such as System.Core.dll). The second, Non-Public Rule Set, is for assemblies are not designed to be consumed by users (such as FxCopCmd.exe). Both sets are listed below:

Public Rule Set:

Design
CA1008	EnumsShouldHaveZeroValue
CA1009	DeclareEventHandlersCorrectly
CA1011	ConsiderPassingBaseTypesAsParameters
CA1012	AbstractTypesShouldNotHaveConstructors
CA1014	MarkAssembliesWithClsCompliant
CA1017	MarkAssembliesWithComVisible
CA1018	MarkAttributesWithAttributeUsage
CA1019	DefineAccessorsForAttributeArguments
CA1023	IndexersShouldNotBeMultidimensional
CA1025	ReplaceRepetitiveArgumentsWithParamsArray
CA1026	DefaultParametersShouldNotBeUsed
CA1027	MarkEnumsWithFlags
CA1028	EnumStorageShouldBeInt32
CA1030	UseEventsWhereAppropriate
CA1032	ImplementStandardExceptionConstructors
CA1034	NestedTypesShouldNotBeVisible
CA1036	OverrideMethodsOnComparableTypes
CA1038	EnumeratorsShouldBeStronglyTyped
CA1039	ListsAreStronglyTyped
CA1040	AvoidEmptyInterfaces
CA1041	ProvideObsoleteAttributeMessage
CA1043	UseIntegralOrStringArgumentForIndexers
CA1044	PropertiesShouldNotBeWriteOnly
CA1045	DoNotPassTypesByReference
CA1046	DoNotOverloadOperatorEqualsOnReferenceTypes
CA1050	DeclareTypesInNamespaces
CA1051	DoNotDeclareVisibleInstanceFields
CA1052	StaticHolderTypesShouldBeSealed
CA1053	StaticHolderTypesShouldNotHaveConstructors
CA1054	UriParametersShouldNotBeStrings
CA1055	UriReturnValuesShouldNotBeStrings
CA1056	UriPropertiesShouldNotBeStrings
CA1057	StringUriOverloadsCallSystemUriOverloads
CA1058	TypesShouldNotExtendCertainBaseTypes
CA1059	MembersShouldNotExposeCertainConcreteTypes

Globalization
CA1300	SpecifyMessageBoxOptions
CA1301	AvoidDuplicateAccelerators
CA1304	SpecifyCultureInfo
CA1305	SpecifyIFormatProvider
CA1306	SetLocaleForDataTypes
CA1307	SpecifyStringComparison
CA1309	UseOrdinalStringComparison
CA2101	SpecifyMarshalingForPInvokeStringArguments

Interoperability
CA1401	PInvokesShouldNotBeVisible
CA1402	AvoidOverloadsInComVisibleInterfaces
CA1403	AutoLayoutTypesShouldNotBeComVisible
CA1404	CallGetLastErrorImmediatelyAfterPInvoke
CA1405	ComVisibleTypeBaseTypesShouldBeComVisible
CA1406	AvoidInt64ArgumentsForVB6Clients
CA1408	DoNotUseAutoDualClassInterfaceType
CA1413	AvoidNonpublicFieldsInComVisibleValueTypes

Naming
CA1700	DoNotNameEnumValuesReserved
CA1701	ResourceStringCompoundWordsShouldBeCasedCorrectly
CA1702	CompoundWordsShouldBeCasedCorrectly
CA1703	ResourceStringsShouldBeSpelledCorrectly
CA1704	IdentifiersShouldBeSpelledCorrectly
CA1707	IdentifiersShouldNotContainUnderscores
CA1708	IdentifiersShouldDifferByMoreThanCase
CA1709	IdentifiersShouldBeCasedCorrectly
CA1710	IdentifiersShouldHaveCorrectSuffix
CA1711	IdentifiersShouldNotHaveIncorrectSuffix
CA1712	DoNotPrefixEnumValuesWithTypeName
CA1713	EventsShouldNotHaveBeforeOrAfterPrefix
CA1714	FlagsEnumsShouldHavePluralNames
CA1715	IdentifiersShouldHaveCorrectPrefix
CA1716	IdentifiersShouldNotMatchKeywords
CA1719	ParameterNamesShouldNotMatchMemberNames
CA1720	IdentifiersShouldNotContainTypeNames
CA1721	PropertyNamesShouldNotMatchGetMethods
CA1722	IdentifiersShouldNotHaveIncorrectPrefix
CA1724	TypeNamesShouldNotMatchNamespaces

Performance
CA1811	AvoidUncalledPrivateCode
CA1812	AvoidUninstantiatedInternalClasses
CA1813	AvoidUnsealedAttributes
CA1815	OverrideEqualsAndOperatorEqualsOnValueTypes
CA1816	DisposeMethodsShouldCallSuppressFinalize
CA1819	PropertiesShouldNotReturnArrays

Portability
CA1900	ValueTypeFieldsShouldBePortable
CA1901	PInvokeDeclarationsShouldBePortable

Reliability
CA2001	AvoidCallingProblematicMethods
CA2002	DoNotLockOnObjectsWithWeakIdentity
CA2004	RemoveCallsToGCKeepAlive
CA2006	UseSafeHandleToEncapsulateNativeResources

Security
CA2102	CatchNonClsCompliantExceptionsInGeneralHandlers
CA2103	ReviewImperativeSecurity
CA2104	DoNotDeclareReadOnlyMutableReferenceTypes
CA2105	ArrayFieldsShouldNotBeReadOnly
CA2106	SecureAsserts
CA2107	ReviewDenyAndPermitOnlyUsage
CA2108	ReviewDeclarativeSecurityOnValueTypes
CA2109	ReviewVisibleEventHandlers
CA2111	PointersShouldNotBeVisible
CA2112	SecuredTypesShouldNotExposeFields
CA2114	MethodSecurityShouldBeASupersetOfType
CA2115	CallGCKeepAliveWhenUsingNativeResources
CA2116	AptcaMethodsShouldOnlyCallAptcaMethods
CA2117	AptcaTypesShouldOnlyExtendAptcaBaseTypes
CA2118	ReviewSuppressUnmanagedCodeSecurityUsage
CA2119	SealMethodsThatSatisfyPrivateInterfaces
CA2120	SecureSerializationConstructors
CA2121	StaticConstructorsShouldBePrivate
CA2122	DoNotIndirectlyExposeMethodsWithLinkDemands
CA2123	OverrideLinkDemandsShouldBeIdenticalToBase
CA2124	WrapVulnerableFinallyClausesInOuterTry
CA2126	TypeLinkDemandsRequireInheritanceDemands
CA2127	SecurityTransparentAssembliesShouldNotContainSecurityCriticalCode
CA2128	SecurityTransparentCodeShouldNotAssert
CA2129	SecurityTransparentCodeShouldNotReferenceNonpublicSecurityCriticalCode

Usage
CA1806	DoNotIgnoreMethodResults
CA2207	InitializeValueTypeStaticFieldsInline
CA2208	InstantiateArgumentExceptionsCorrectly
CA2209	AssembliesShouldDeclareMinimumSecurity
CA2211	NonConstantFieldsShouldNotBeVisible
CA2213	DisposableFieldsShouldBeDisposed
CA2214	DoNotCallOverridableMethodsInConstructors
CA2216	DisposableTypesShouldDeclareFinalizer
CA2217	DoNotMarkEnumsWithFlags
CA2218	OverrideGetHashCodeOnOverridingEquals
CA2220	FinalizersShouldCallBaseClassFinalizer
CA2221	FinalizersShouldBeProtected
CA2224	OverrideEqualsOnOverloadingOperatorEquals
CA2225	OperatorOverloadsHaveNamedAlternates
CA2227	CollectionPropertiesShouldBeReadOnly
CA2228	DoNotShipUnreleasedResourceFormats
CA2229	ImplementSerializationConstructors
CA2230	UseParamsForVariableArguments
CA2233	OperationsShouldNotOverflow
CA2234	PassSystemUriObjectsInsteadOfStrings
CA2235	MarkAllNonSerializableFields
CA2236	CallBaseClassMethodsOnISerializableTypes
CA2237	MarkISerializableTypesWithSerializable
CA2240	ImplementISerializableCorrectly

Non-Public Rule Set:

Globalization
CA2101	SpecifyMarshalingForPInvokeStringArguments

Portability
CA1900	ValueTypeFieldsShouldBePortable
CA1901	PInvokeDeclarationsShouldBePortable

Reliability
CA2002	DoNotLockOnObjectsWithWeakIdentity

Security
CA2100	ReviewSqlQueriesForSecurityVulnerabilities
CA2102	CatchNonClsCompliantExceptionsInGeneralHandlers
CA2103	ReviewImperativeSecurity
CA2104	DoNotDeclareReadOnlyMutableReferenceTypes
CA2105	ArrayFieldsShouldNotBeReadOnly
CA2106	SecureAsserts
CA2107	ReviewDenyAndPermitOnlyUsage
CA2108	ReviewDeclarativeSecurityOnValueTypes
CA2109	ReviewVisibleEventHandlers
CA2111	PointersShouldNotBeVisible
CA2112	SecuredTypesShouldNotExposeFields
CA2114	MethodSecurityShouldBeASupersetOfType
CA2115	CallGCKeepAliveWhenUsingNativeResources
CA2116	AptcaMethodsShouldOnlyCallAptcaMethods
CA2117	AptcaTypesShouldOnlyExtendAptcaBaseTypes
CA2118	ReviewSuppressUnmanagedCodeSecurityUsage
CA2119	SealMethodsThatSatisfyPrivateInterfaces
CA2120	SecureSerializationConstructors
CA2121	StaticConstructorsShouldBePrivate
CA2122	DoNotIndirectlyExposeMethodsWithLinkDemands
CA2123	OverrideLinkDemandsShouldBeIdenticalToBase
CA2124	WrapVulnerableFinallyClausesInOuterTry
CA2126	TypeLinkDemandsRequireInheritanceDemands
CA2127	SecurityTransparentAssembliesShouldNotContainSecurityCriticalCode
CA2128	SecurityTransparentCodeShouldNotAssert
CA2129	SecurityTransparentCodeShouldNotReferenceNonpublicSecurityCriticalCode

Usage
CA2233	OperationsShouldNotOverflow

Now, while the above rules are set and mandated at the Division-level, individual teams can (and do) add additional rules. For example, most assemblies, whether public or not, at a minimum follow the Public Rule Set. The Code Analysis team itself actually turns on every single rule to run over the binaries that we release.

Also note that because they are set at the start of a product cycle and are not changed again until the start of the next cycle, rule sets do not include rules that are new to Visual Studio 2008 (with exception to security rules). This is prevent the situation of the introduction of a new rule causing existing code to be no longer be Code Analysis clean (ie moving the basket).

These rule sets will be revisited for Rosario and beyond.

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

What resolutions or warnings need to provide more information?

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

One of things that we are doing for Orcas, is to basically do what we call a resolution scrub. This is where we print out every single possible resolution/warning and read over them to check for consistency, proper grammer and to see if they provide enough information for the user to both understand and fix the issue.

Unfortunately, we know that we are not there yet. An example of a change we are making is when we analyze the following:

public class IoWriter
{
    public void writeString(string word)
    {
    }

    public void writeXML(string xml)
    {
    }
}

In Visual Studio 2005/FxCop 1.35, the above type would fire the following four warnings with regards to the casing of name and name of its members (see the Framework Design Guidelines for more information):

    1) Correct the casing of member name 'writeString'.
    2) Correct the casing of member name 'writeXML'.
    3) Correct the capitalization of member name 'IoWriter.WriteXML(String):Void'.
    4) Correct the capitalization of 'Io' in type name 'IoWriter'.

As you can see, for what seem to be similar checks, there are three different ways to tell the user of the problem. On top of that, even though 2) and 3) are actually raised for two different issues (one for the casing of 'write' and one for the casing of 'XML'), to the user, both seem to be finding the same problem. All four also fail to mention what the casing of the member and type names should be.

For Orcas, we will be changing the above to the following:

    1) Correct the casing of 'write' in member name 'IoWriter.writeString(String):Void' by changing it to 'Write'.
    2) Correct the casing of 'write' in member name 'IoWriter.writeXML(String):Void' by changing it to 'Write'.
    3) Correct the casing of 'XML' in member name 'IoWriter.writeXML(String):Void' by changing it to 'Xml'.
    4) Correct the casing of 'Io' in type name 'IoWriter' by changing it to 'IO'.

At least now they all have the same wording and all of them now tell the user how to actually fix the warning.

What do you think? Is this enough? Or would you like to see more information in the warning with regards to why, for example, 'XML' and 'Io' in particular are cased incorrectly?

Apart from above, what other warnings have you encountered that do not provide enough information? I'm particularly interested in warnings that do not tell the user; 1) why the problem was raised and/or 2) how to fix the problem.

How to Design Exception Hierarchies

David M. Kean — Thu, 01 Feb 2007 19:00:00 GMT

Krzysztof Cwalina, owner of the Framework Design Guidelines, has written a great post on designing exception hierarchies. He gives a great overview on the different categories of exceptions, which are placed under two main buckets he calls usage and system, and the right situations to throw them.

This post also goes hand-in-hand with some of the previous posts on this blog:

FAQ: What exception should I throw instead of the reserved exceptions that DoNotRaiseReservedExceptionTypes warns against?
FAQ: Why does FxCop warn against catch(Exception)? (Part 1, Part 2 and Part 3)

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.

TIP: Automatically generate Managed Code Analysis/FxCop suppressions

David M. Kean — Thu, 18 Jan 2007 19:00:00 GMT

I see a lot of users attempting to hand code a SuppressMessageAttribute themselves. This can be error prone and is not needed when both Visual Studio and the standalone FxCop can automatically generate these for you.

In Visual Studio 2005

Right-click a Code Analysis warning in the Error List and choose Suppress Message(s).

In Visual Studio Orcas

Right-click a Code Analysis warning in the Error List and choose Suppress Message(s) -> In Source or Suppress Message(s) -> In Project Suppression File

In FxCop

Right-click a warning and choose Copy As -> SuppressMessage.
Paste the contents of the Clipboard at the top of the code element that caused the warning.

Note: In both Visual Studio and FxCop you can select multiple warnings and suppress them all once.

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.

January Orcas CTP Released!

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

Update: A Virtual PC image is also available.

We've just released the Visual Studio 'Orcas' - January CTP. This is the first of the side-by-side installable CTPs, however, before installing, please read the Release Notes and do not install this on a production machine as this will likely break Visual Studio 2005 when uninstalled.

Besides the new features mentioned previously for Code Analysis, you will also see the following new analysis in this CTP:

New Rules:
Reliability\AvoidCallingProblematicMethods
Globalization\SpecifyStringComparision
Globalization\NormalizeStringsToUppercase
Globalization\UseOrdinalStringComparion
Design\DoNotRaiseExceptionsInUnexpectedLocations
Usage\DoNotRaiseExceptionsInExceptionClauses

Changes to Existing Rules:
IdentifiersShouldHaveCorrectPrefix
- Now fires on generic type parameters that do not begin with 'T'

CompoundWordsShouldBeCasedCorrectly
IdentifiersShouldBeCasedCorrectly
UsePreferredTerms
ShortAcronymsShouldBeUppercase
LongAcronymsShouldBePascalCased
IdentifiersShouldNotContainUnderscores
- Now fire on assemblies (with externally visible types) and generic type parameters

You will also see a string of better analysis and less noise in existing rules when compared to both Visual Studio 2005 and FxCop 1.35.

Download it today and tell us what you think!

And now back to your regularly scheduled FxCop documentation...

David M. Kean — Sun, 07 Jan 2007 04:00:00 GMT

As a lot of you noticed, just before Christmas all of our rule documentation links broke from within FxCop. Unfortunately, due to the timing (and with the required people on holidays), we could not get this fixed as soon as we had hoped.

However, as of early this week, the documentation should be back up and running. We apologise profusely and hope that it did not cause you too much of an inconvenience.

To those that thought we were cutting FxCop, I can assure you that the standalone will be sticking around in the future. :)

However, there is good news out of this; the MSDN Wiki Team have moved the MSDN wiki feature across to the main MSDN2 Library. The even better news, is that now Visual Studio users (if they have enabled live MSDN) can now view, edit and add these community blocks from within their Visual Studio help viewer. And with 33% of our rule topics already with at least 1 community content block, check it out!