外部アノテーション

使い方

ソースが利用できない外部ライブラリを使用している場合、コードアノテーションを指定するための属性をそこで使用することは現実的ではないようです。

この場合、外部アノテーションを使用すると、すでにコンパイルされたエンティティを、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 5.2 のサポート）も外部アノテーションに依存しています。

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 アセンブリと static string ReverseString(String inputString) メソッドを使用するとします。アセンブリのドキュメントから、メソッドが純粋で null を返さないこと、そのパラメーターが null になることはないことを知っているとします。

当初、JetBrains Rider は ReverseString がどのように機能するのかを認識していないため、次のコードで問題は見つかりません。

外部アノテーションを配布する

外部アノテーションを使用するもう 1 つのケースは、配布するライブラリまたは任意のライブラリに対して外部アノテーションを公開することです。この場合、ReSharper、Rider、Fleet も使用しているライブラリのユーザーは、より多くの提案と修正を受け取ることになります。

ライブラリの外部アノテーションは、NuGet パッケージとして公開し、そこからインストールできます。外部アノテーションのパッケージ化の詳細については、ReSharper プラグイン開発ガイドを参照してください。