Where to copy Resharper external annotation XML files to be found by Visual Studio

Question

I have created a XML annotation file for one of my libraries and want to make it available for all my projects without needing to copy it in each project binary folder.

For what I have read this can be done by copying it into the Resharper installation folder but I have tried a few places without success.

I have copied it in the following folders:

C:\Users\myuser\AppData\Local\JetBrains\Installations\ReSharperPlatformVs14\ExternalAnnotations\MyCompany

C:\Users\myuser\AppData\Local\JetBrains\ReSharper\vAny\vs14.0\Bin\ExternalAnnotations

The xml file has the exact same name as the dll that annotates, but xml extension. And the contents are like the follow:

<assembly name="Company.Tools.Libs.Logging">
  <member name="M:Company.Tools.Libs.Logging.Interfaces.IBasicLogger.WriteDebug(System.String,System.Object[])">
    <attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor(System.String)" />
    <argument>"format"</argument>
  </member>
  <member name="M:Company.Tools.Libs.Logging.Interfaces.IBasicLogger.WriteInfo(System.String,System.Object[])">
    <attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor(System.String)" />
    <argument>"format"</argument>
  </member>
  <member name="M:Company.Tools.Libs.Logging.Interfaces.IBasicLogger.WriteWarning(System.String,System.Object[])">
    <attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor(System.String)" />
    <argument>"format"</argument>
  </member>
  <member name="M:Company.Tools.Libs.Logging.Interfaces.IBasicLogger.WriteError(System.String,System.Object[])">
    <attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor(System.String)" />
    <argument>"format"</argument>
  </member>
  <member name="M:Company.Tools.Libs.Logging.Interfaces.IBasicLogger.WriteFatal(System.String,System.Object[])">
    <attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor(System.String)" />
    <argument>"format"</argument>
  </member>
</assembly>

What am I missing here?

UPDATE:

As @citizenmatt has said my xml was wrong, and the argument nodes need to be nested inside the attribute element. Doing this with a simple project I used to replicate the issue make it work, but that was by creating the external annotations in the same folder as the dll and with .ExternalAnnotation prefix.

I am still trying to find out where to copy it on my machine so its picked by Resharper without distributing it along the dll.

UPDATE 2:

After discussing with @citizenmatt I have decided to ship my annotations along the dll. He had a good point, adding it on the installation dir of Resharper will make them disappear in every new installation plus its not a very intuitive place. Also, I haven't been able to get VS to get my annotations from there.

Answer 1

If I remember correctly, I think it needs to be in a sub-folder of ExternalAnnotations. You'll also need to close and reopen your solution before it will be picked up.

You can also ship the file next to the .dll, as long as it ends with .ExternalAnnotations.xml, e.g. foo.dll would need foo.ExternalAnnotations.dll.

Alternatively, you can ship the annotations in an extension. This is packaged up as a nuget package with a custom file layout. You can see the community extensions project for an example of the nuspec file (if your assembly is a public assembly, you might even want to add a pull request!)

However, the example XML you've shown here is incorrect - the argument element needs to be a child of the attribute element. It's telling ReSharper how to build an argument that should be applied - the ctor attribute gives ReSharper the constructor (and the class), and then we need to pass arguments to that constructor - so each argument element needs to be a child of the attribute element. In other words:

<member name="M:Company.Tools.Libs.Logging.Interfaces.IBasicLogger.WriteDebug(System.String,System.Object[])">
<attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor(System.String)">
  <argument>format</argument>
</attribute>