Working with Resharper’s External Annotation XML Files

Resharper 4.0 has external annotation XML files that you can create to give Resharper more information about your code.  For example, you can tell Resharper that a particular method does not accept a null argument.  For example, the following method does not accept a null argument:

using System;
 
namespace Utility
{
    public static class Text
    {
        public static int GetLength(String text)
        {
            if (text == null) throw new ArgumentNullException("text");
            return text.Length;
        }
    }
}

An external annotation file can be created to inform Resharper of this fact and have it warn you when possible null values are passed as an argument:

            String text = null;
            Utility.Text.GetLength(text);

First, you need to create a directory within the Resharper ExternalAnnotations directory.  This ExternalAnnotations directory is usually in the form of “%SystemDrive%\Program Files\JetBrains\ReSharper\vBuild#\Bin\ExternalAnnotations” for example “C:\Program Files\JetBrains\ReSharper\v4.0.816.4\Bin\ExternalAnnotations”.

The directory we need to create is the same name as our assembly (without the extension).  In our case this would be “C:\Program Files\JetBrains\ReSharper\v4.0.816.4\Bin\ExternalAnnotations\Utility”.

Next, we need to create an XML file to contain the information required by Resharper.  The name of this file is the same as the directory name, plus “.xml”.  So, the full file name would be “C:\Program Files\JetBrains\ReSharper\v4.0.816.4\Bin\ExternalAnnotations\Utility\Utility.xml”.  This file essentially has an assembly element with child member elements that provide meta-data about methods and arguments.  In our case we want to tell Resharper that the Utility.Text.GetLength(String) method does not accept null values for the argument named “text”.  To do this we populate the file with the following XML:

<?xml version="1.0" encoding="utf-8" ?>
<assembly name="Utility">
    <member name="M:Utility.Text.GetLength(System.String)">
        <parameter name="text">
            <attribute ctor="M:JetBrains.Annotations.NotNullAttribute.#ctor" />
        </parameter>
    </member>
</assembly>

After restarting Visual Studio, Resharper will now warn that “text”, when passed to GetLength, in the following code, has a “Possible ‘null’ assignment to entity marked with “NotNull” attribute”.

            String text = null;
            Utility.Text.GetLength(text);

I’ve tried this with the GA build and with both Visual Studio 2005 (SP1) and Visual Studio 2008.


For more information about the annotation options, search for AssertionConditionType in the Resharper help and browse around “%SystemDrive%\Program Files\JetBrains\ReSharper\vBuild#\Bin\ExternalAnnotations” for examples.

5 thoughts on “Working with Resharper’s External Annotation XML Files”

  1. This is cool, but it is just a replacement for the BIGGEST PROBLEM OF C# (IMHO): It doesn’t know about non-nullable types
    http://codebetter.com/blogs/patricksmacchia/archive/2007/07/25/i-want-non-nullable-types-in-c-4.aspx

    Actually I don’t understand why R# needs such annotation file. It already knows from Debug.Assert(myParam != null) that myParam shouldn’t be null so why does it needs this extra Xml files to duplicate the info? It needs to cache the info for perf reasons?

  2. Hi Peter, I tried this with VS2008 and R#4.0.819.19

    Works ok when I explicitly mark params/methods with the annotation attributes, but XML annotations aren’t working. Tried to put this Utility.xml into ExternalAnnotations\Utility or directly into ExternalAnnotations (they have NUnit.Framework.xml at that level), or along with local .cproj file, or local bin\Debug – neither worked.

    Noticed you’ve put xml < ?xml version="1.0" encoding="utf-8" ?> header on the top while all other predefined annotations don’t have it, but that shouldn’t make any difference.

    Also, my R# installation is located in \JetBrains\ReSharper\v4.0\ and not in \JetBrains\ReSharper\v4.0.816.4\ as yours – wonder if it might be a point, sounds like you’re using a pre-release build?

    Anyway, thanks for the tip and if you have any ideas please reply – it would be nice to make the stuff working!

  3. Hi, a way I was able to make it working, paybe it would be helpful for someone.

    1. file should be named [dll-name-without-extension].ExternalAnnotations.xml (so, an xml for Foo.dll would be named Foo.ExternalAnnotations.xml)

    2. xml file should be located side-by-side with the dll

    3. it works for a _dll_ reference, not a project one (thus, R# would eek a warning in a Boo project that references a Foo.dll)

  4. When i got this awsome warning from resharper i went looking for a NotNullAttribute class. I never found one of coarse. It would however be pretty cool if such an attribute existed. You could define a method like the following.

    using System;
    namespace Utility
    {
    public static class Text
    {
    public static int GetLength([NotNull]String text)
    {
    if (text == null) throw new ArgumentNullException(“text”);
    return text.Length;
    }
    }
    }

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>