外部アノテーション
使い方
ソースが利用できない外部ライブラリを使用している場合、コードアノテーションを指定するための属性をそこで使用することは現実的ではないようです。
この場合、外部アノテーションを使用すると、すでにコンパイルされたエンティティを、ReSharper のコード分析エンジンによって認識される属性で補完できます。外部アノテーションを使用すると、ライブラリのコンパイル時に宣言されていなかった属性 (メソッド、パラメーター、その他の宣言) をエンジンに参照させることで、エンジンを「騙す」ことができます。
外部アノテーションは XML ファイルで指定されています。ソリューションをロードするとき、ReSharper は特定の場所にある特定の名前の XML ファイルを探し、そこからアノテーションを読み取ります。これらの XML ファイルは XmlDoc に似た構造をしています。例: .NET フレームワーク 4.0 のアセンブリ System.Xml
からのメソッド XmlReader.Create(Stream input)
に NotNull
契約を付けてアノテーションを付けると、XML ファイルは次のようになります。
JetBrains 外部アノテーション
上記のアプローチは、.NET フレームワーククラスライブラリやその他の頻繁に使用されるライブラリ内の膨大な数のシンボルにアノテーションを付ける際に使用されます。これらのライブラリの外部アノテーションは、より優れたコード分析を確実にするために ReSharper とともにインストールされます。一部の機能 (ASP.NET MVC サポートなど) も外部アノテーションに依存しています。
JetBrains 外部アノテーションのソースコードは、GitHub:https://github.com/JetBrains/ExternalAnnotations(英語) の MIT ライセンスで入手できます。このリポジトリに貢献したり、外部のアノテーションの例として使用することは大歓迎です。
外部アノテーションを作成する
コンパイル済みアセンブリの契約を指定するための外部アノテーションを作成できます。ReSharper が外部アノテーション付きの 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 になることはないことを知っているとします。
当初、ReSharper は 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>ソリューションを再ロードします。現在、ReSharper は
ReverseString
の不適切な使用を検出し、null パラメーターの問題を強調しています。... 戻り値の不要なチェック:
ライブラリシンボルに適用される外部アノテーションを表示するには、クイックドキュメント機能を使用します。シンボル上で Control+Q を押すだけでその属性を調べることができます。我々のケースでは、
ReverseString
に[NotNull]
および[Pure]
属性がアノテーションされ、パラメーターに[NotNull]
がアノテーションされていることがわかります。属性の灰色は、それらがソースまたはアセンブリコードからではなく、外部アノテーションからのものであることを意味します。
外部アノテーションを配布する
外部アノテーションを使用するもう 1 つのケースは、配布するライブラリまたは任意のライブラリに対して外部アノテーションを公開することです。この場合、ReSharper、Rider、Fleet も使用しているライブラリのユーザーは、より多くの提案と修正を受け取ることになります。
ライブラリの外部アノテーションは、NuGet パッケージとして公開し、そこからインストールできます。外部アノテーションのパッケージ化の詳細については、ReSharper プラグイン開発ガイドを参照してください。
関連ページ:

クイックドキュメント
ReSharper を使用すると、エディター内でシンボルのドキュメントをすばやく確認できます。シンボルがサポートされている形式 (C# の XML-docs など) でドキュメント化されている場合、すべてのドキュメントが適切な形式で表示されます。それ以外の場合は、基本的なシンボル情報が表示されます (完全なメソッドシグネチャーまたは型の可視性と名前空間など)。シンボルのクイックドキュメントを表示キャレットを配置するエディターのシンボル参照、ファイル構造ウィンドウまたはその他の ReSharper...

コード参照をクリップボードにコピーする
キャレットのシンボルの名前やその XML ドキュメント ID、ファイルへのパス、VCS パスなど、現在の場所のコンテキストをログに記録または共有する必要がある場合は、を押して目的の参照をコピーできます。ポップアップから: シンボル名をコピーする:シンボル(宣言または使用箇所)でこのコマンドを呼び出すと、完全修飾名がクリップボードに自動的にコピーされます。名前または名前空間のみが必要な場合は、ポップアップで選択できます。リフレクションを使用する場合など、さまざまな状況でシンボルの完全修飾名が必要...

ソースコードのアノテーション
ReSharper のコードアノテーションの恩恵を受ける最も簡単な方法は、ソースコードのシンボルにアノテーション属性を追加し、ReSharper がソリューションをより正確かつ洞察力で分析できるようにすることです。デフォルトでは、すべてのアノテーション属性クラスは属性でマークされているため、コンパイラーはコード内の属性の使用を無視します。つまり、'JetBrains.Annotations.dll' アセンブリへのバイナリ参照は生成されません。ただし、プロジェクトで「JETBRAINS_ANNO...

契約アノテーション
契約アノテーションでは、与えられた入力に対する期待される出力を定義することができます。言い換えれば、関数の参照型とブール型引数とその戻り値の間の依存関係を定義することができます。契約アノテーションのメカニズムにより、より簡単で安全な方法で消費できる API を作成できます。を使って関数を装飾することによって契約アノテーションを実装することができます。あなたのソースコード、JetBrains.Annotations 名前空間を参照するでそれをやりたいなら。外部アノテーションを使用して既存のバイナリ...