外部アノテーション
仕組み
ソースが利用できない外部ライブラリを使用している場合、コードアノテーションを指定するための属性をそこで使用することは現実的ではないようです。
この場合、 外部アノテーションを利用することで、すでにコンパイルされたエンティティに JetBrains Rider のコード解析エンジンが認識する属性を補完できます。 外部アノテーションを使用すると、ライブラリのコンパイル時に宣言されていなかった属性 (メソッド、パラメーター、その他の宣言) をエンジンに参照させることで、エンジンを「騙す」ことができます。
外部アノテーションは XML ファイルで指定されています。 ソリューションをロードする際、JetBrains Rider は特定の場所に命名された XML ファイルを探し、そこからアノテーションを読み取ります。 これらの XML ファイルは XmlDoc に似た構造をしています。 例: .NET フレームワーク 4.0 のアセンブリ System.Xml からのメソッド XmlReader.Create(Stream input) に NotNull 契約を付けてアノテーションを付けると、XML ファイルは次のようになります。
JetBrains 外部アノテーション
上記のアプローチは、.NET フレームワーククラスライブラリやその他の頻繁に使用されるライブラリ内の膨大な数のシンボルにアノテーションを付ける際に使用されます。 これらのライブラリ向けの外部アノテーションは、より良いコード解析を行うために JetBrains Rider と一緒にインストールされます。 一部の機能 (ASP.NET MVC サポートなど) も外部アノテーションに依存しています。
JetBrains 外部アノテーションのソースコードは、GitHub: https://github.com/JetBrains/ExternalAnnotations(英語) の MIT ライセンスで入手できます。 このリポジトリに貢献したり、外部のアノテーションの例として使用することは大歓迎です。
外部アノテーションを作成する
コンパイル済みアセンブリの契約を指定するための外部アノテーションを作成できます。 JetBrains Rider が外部アノテーション付きの XML ファイルを認識するためには、このファイルを [Assembly.Name].ExternalAnnotations.xml という命名にする必要があります。 アノテーション付きバイナリの使用方法に応じて、次の場所にアノテーションファイルを作成できます。
バイナリを（NuGet などで）公開する場合は、アノテーション付き [Assembly.Name].dll ファイルと同じフォルダーにアノテーション [Assembly.Name].ExternalAnnotations.xml ファイルを配置します。
プロジェクトに含まれる一部のバイナリにアノテーションを付ける場合は、プロジェクトまたはソリューションファイルの隣の ExternalAnnotations フォルダーに各アセンブリのアノテーションファイルを配置します。
このフォルダーにアノテーションファイルを配置するとき、ファイルはアセンブリ名、つまり [Assembly.Name].xml に基づいて名前を付ける必要があります。 ExternalAnnotations のサブフォルダーに存在することもできますが、そのフォルダーにはアセンブリ名、つまり ExternalAnnotations/[Assembly.Name]/[AnyName].xml が必要です。
このようにして、 VCS の下にアノテーションを保持して、チームがそれらから利益を得られるようにすることもできます。
外部アノテーションの作成を説明するために、 MyTestClass クラスを持つ TestLib アセンブリと public static string ReverseString(String inputString) メソッドを使用するとします。 アセンブリのドキュメントから、メソッドが純粋で null を返さないこと、そのパラメーターが null になることはないことを知っているとします。
最初は、JetBrains Rider は ReverseString の動作を認識していないため、次のコードに問題は見つかりません：
コンパイルされたアセンブリの外部アノテーションを作成する
ファイルシステムで TestLib.dll を見つけて、 TestLib.dll が参照されているプロジェクトまたはソリューションファイルの横にある同じフォルダーまたは ExternalAnnotations フォルダーに TestLib.ExternalAnnotations.xml という名前のファイルを作成します。
編集のために TestLib.ExternalAnnotations.xml を開き、以下を入力してください:
<assembly name="TestLib"> <member name="M:TestLib.MyTestClass.ReverseString(System.String)"> <attribute ctor="M:JetBrains.Annotations.NotNullAttribute.#ctor" /> <attribute ctor="M:JetBrains.Annotations.PureAttribute.#ctor" /> <parameter name="inputString"> <attribute ctor="M:JetBrains.Annotations.NotNullAttribute.#ctor" /> </parameter> </member> </assembly>ソリューションを再ロードします。 現在、JetBrains Rider は
ReverseStringの不適切な使用を検出し、null パラメーターの問題をハイライトします：
... 戻り値の不要なチェック:
ライブラリシンボルに適用されている外部アノテーションを確認するには、 クイックドキュメント機能を利用できます。 シンボル上で Ctrl+Q を押すだけでその属性を調べることができます。 我々のケースでは、
ReverseStringに[NotNull]および[Pure]属性がアノテーションされ、パラメーターに[NotNull]がアノテーションされていることがわかります。
外部アノテーションを配布する
外部アノテーションを使用するもう 1 つのケースは、配布するライブラリまたは任意のライブラリに対して外部アノテーションを公開することです。 この場合、ReSharper、Rider、Fleet も使用しているライブラリのユーザーは、より多くの提案と修正を受け取ることになります。
ライブラリの外部アノテーションは、NuGet パッケージとして公開し、そこからインストールできます。 外部アノテーションのパッケージ化の詳細については、 ReSharper プラグイン開発ガイドを参照してください。