External annotations

How it works

If you are using an external library, whose sources are not available to you, it does not seem feasible to use the attributes there for specifying code annotations.

In this case, you can use External Annotations, which allow you to complement the already compiled entities with attributes recognized by ReSharper for Visual Studio Code's code analysis engine. External annotations let you 'cheat' the engine, by making it see the attributes (for methods, parameters, and other declarations), which were not declared at the time the library was compiled.

External annotations are specified in XML files. When loading solution, ReSharper for Visual Studio Code looks for specifically named XML files in specific locations and reads annotations from there. These XML files have a structure similar to XmlDoc. For example, to annotate the method XmlReader.Create(Stream input) from the assembly System.Xml of .NET Framework 4.0, with the NotNull contracts, the XML file would look as follows:

<assembly name="System.Xml, Version=4.0.0.0">
    <!--The attribute name contains the assembly name. If you don't specify the version,
    this file's attributes will be applied to all versions of the assemblies of that name -->
    <member name="M:System.Xml.XmlReader.Create(System.IO.Stream)">
        <!--This shows the name of the member whose attributes are complemented;
        the notation is the same as XmlDoc -->
        <attribute ctor="M:JetBrains.Annotations.NotNullAttribute.#ctor" />
            <!--attribute constructor names are also specified using XmlDoc notation -->
        <parameter name="input">
            <attribute ctor="M:JetBrains.Annotations.NotNullAttribute.#ctor" />
        </parameter>
    </member>
</assembly>

JetBrains external annotations

The approach described above was used to annotate a huge amount of symbols in the .NET Framework Class Library, as well as in other frequently used libraries. External annotations for these libraries are installed with ReSharper for Visual Studio Code to ensure better code analysis. Some features (for example, ASP.NET MVC support) also rely on external annotations.

The source code of JetBrains external annotations is available under the MIT license on GitHub: https://github.com/JetBrains/ExternalAnnotations. You are welcome to contribute to this repository or use it as an example for your own external annotations.

15 May 2025