C#: How to Implement and use a NotNull and CanBeNull attribute

Question

I want to let programmers and myself know that a method does not want null and if you do send null to it anyways, the result will not be pretty.

There is a NotNullAttribute and a CanBeNullAttribute in Lokad Shared Libraries, in the Lokad.Quality namespace.

But how does that work? I looked at the source-code of those two attributes, and it looks like this:

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Parameter |
                AttributeTargets.Property | AttributeTargets.Delegate |
                AttributeTargets.Field, AllowMultiple = false, Inherited = true)]
[NoCodeCoverage]
public sealed class NotNullAttribute : Attribute
{
}

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Parameter |
                AttributeTargets.Property | AttributeTargets.Delegate |
                AttributeTargets.Field, AllowMultiple = false, Inherited = true)]
[NoCodeCoverage]
public sealed class CanBeNullAttribute : Attribute
{
}

Two empty classes inheriting from Attribute. How are they used? Do you have to look up xml-documentation and know that it is there? Cause I tried to both make my own copy of the attribute and to use the Lokad version, but when I tried to send a null directly in, I got no message. Neither from ReSharper nor from VS. Which I kind of expected actually. But how are they used? Can I somehow make VS generate warnings for me if I try to send something that is null in there? Or is it just used in some kind of testing framework? Or?

To comment on your specific case, those attributes don't do anything and are just "documentation". The other answers give good alternatives, though. — Sander, Apr 27 '09 at 07:53

Marc Gravell · Accepted Answer · 2009-04-27T08:00:33.110

46

In the mid-term, "code contracts" (in 4.0) will be a better answer to this. They are available now (with academic or commercial licences), but will be more integrated in VS2010. This can provide both static analysis and runtime support.

(edit) example:

Contract.RequiresAlways( x != null );

Simple as that... the code contracts engine works at the IL level, so it can analyse that and throw warnings/errors from calling code during build, or at runtime. For backwards compatibility, if you have existing validation code, you can just tell it where the sanity checking ends, and it'll do the rest:

if ( x == null ) throw new ArgumentNullException("x");
Contract.EndContractBlock();

edited Apr 27 '09 at 08:00

answered Apr 27 '09 at 07:42

Marc Gravell

1,026,079
266
2,566
2,900

That looked very smooth! Will it work in VS 2008 as well? What do you mean by "more integrated"? – Svish Apr 27 '09 at 12:39
Yes; the links I posted were for the VS2008 variant. By "more integrated", I mean that AFAIK, it is built into the IDE and runtime, rather than being a separate add-on. I haven't checked (indeed, can't) - but this *might* possibly mean it works in the Express Edition too (the add-on doesn't). – Marc Gravell Apr 27 '09 at 12:59
Cool. Have you tried this add-on out yet? Easy to install and to use? Is it safe to use in a Production environment? (Will other employees kill me if I add it? :P) – Svish Apr 27 '09 at 13:34
1

I just fired up my old CTP build of VS2010, but it looks like the "bits" weren't ready when the last CTP went out. Tell you what, I'll try it and find out ;-p – Marc Gravell Apr 27 '09 at 13:44
Looks pretty usable. You enable it by adding a reference to Microsoft.Contracts.dll, and by setting a tick in a checkbox on the "Coer Contracts" tab of project properties. The static checker is for build-time messages. – Marc Gravell Apr 27 '09 at 13:59
I get that "Coer Contracts" when I install that add-on? This will have to be done on all the machines that are going to use this Solution, right? How about deployment? That Microsoft.Contracts.dll isn't in .Net Framework by default? – Svish Apr 27 '09 at 14:11
Not until .NET 4.0, no. However, if you set to only use contracts for debug builds, you might not need to deploy it. And if you want runtime checks, I *expect* that you can just deploy the dll for the runtime support. The install is primarily for Visual Studio purposes. – Marc Gravell Apr 27 '09 at 14:16
But if I started to use that Microsoft.Contracts.dll, when .NET 4.0 comes out, would I need to stop referencing my "local" copy Microsoft.Contracts.dll? Or would it be more work to "port" it? – Svish Apr 27 '09 at 14:24
As I understand it, the classes/namespaces etc are the same - it is only the assembly that changes. So with 4.0 you simply drop the extra reference (no other changes). But since 4.0 is pre-beta... – Marc Gravell Apr 27 '09 at 15:19
1

Note that code contracts [seem to have fell out of favor in VS 2017.](https://stackoverflow.com/questions/40767941/does-vs2017-work-with-codecontracts) – jrh Sep 19 '17 at 16:10

score 19 · Answer 2 · answered Apr 27 '09 at 07:43

This can be done either with AOP, whereby an Advice verifies at run-time whether a method parameter is null and whether nulls are allowed. See PostSharp and Spring.NET for AOP.

As for ReSharper, see Annotated Framework:

We have analyzed a great share of .NET Framework Class Library, as well as NUnit Framework, and annotated it through external XML files, using a set of custom attributes from the JetBrains.Annotations namespace, specifically:

StringFormatMethodAttribute (for methods that take format strings as parameters)

InvokerParameterNameAttribute (for methods with string literal arguments that should match one of caller parameters)

AssertionMethodAttribute (for assertion methods)

AssertionConditionAttribute (for condition parameters of assertion methods)

TerminatesProgramAttribute (for methods that terminate control flow)

CanBeNullAttribute (for values that can be null)

NotNullAttribute (for values that can not be null)

You can get the ReSharper Annotations from NuGet: https://www.nuget.org/packages/JetBrains.Annotations/ — aboy021, Aug 21 '13 at 22:55
But resharper annotations are just a comment readable for resharper.. they are not checked at runtime — Revious, Mar 06 '15 at 13:48
You link no longer points to the quoted text, the quoted text has been moved to [External Annotations](https://www.jetbrains.com/help/resharper/Code_Analysis__External_Annotations.html), although since the OP is annotating his own code, External Annotations aren't appropriate. — Jade, Apr 14 '18 at 04:51

score 9 · Answer 3 · answered Oct 31 '13 at 14:28

These annotations are for ReSharper, and are copied from the JetBrains.Annotations namespace. A framework can put them in their own namespace, however, ReSharper will NOT pick up these annotations automatically - you need to tell ReSharper to use the custom namespace in the options dialog. Once you've selected the new namespace, ReSharper's analysis will pick up the attributes and give you highlights and warnings.

score 3 · Answer 4 · edited May 23 '17 at 10:31

As pointed by Anton Gogolev, attributes can be created using PostSharp.(note that CodeContract is using static method calls inside body of method)

UPDATE Feb 2013: new 3.0 release of PostSharp (currently in Beta) will support Validating parameters, fields and properties

1) Article validate-parameters-using-attributes has implementation of

public class NotEmpty : ParameterAttribute

public class NotNull : ParameterAttribute

[AttributeUsage(AttributeTargets.Parameter)]

public abstract class ParameterAttribute : Attribute

{
public abstract void CheckParameter(ParameterInfo parameter, object value); 
}

It also Required a method attribute with a method boundary aspect to process the parameter attributes.

2) In the comment to the article there are links to very similar implementation for NonNull/NonEmpty

[return: NonNull] public SomeObject SomeMethod([NonNull] AnotherObject param1)

The source code is located In google code Torch/DesignByContract

3) another more complicate example is described in http://badecho.com/2011/11/validating-method-parameters-with-postsharp/

C#: How to Implement and use a NotNull and CanBeNull attribute

4 Answers4

Linked