ReSharper 2020.1ヘルプ

外部注釈

使い方

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

この場合は、外部注釈を使用できます。これにより、ReSharperのコード分析エンジンによって認識される属性を使用して、すでにコンパイル済みのエンティティを補完できます。外部注釈を使用すると、ライブラリのコンパイル時には宣言されていなかった属性(メソッド、パラメータ、その他の宣言用)を表示することで、エンジンを「騙す」ことができます。

外部注釈はXMLファイルで指定されています。ソリューションをロードするとき、ReSharperは特定の場所にある特定の名前のXMLファイルを探し、そこから注釈を読み取ります。これらのXMLファイルはXmlDocに似た構造をしています。例:.NET フレームワーク 4.0のアセンブリ System.Xml からのメソッド XmlReader.Create(Stream input)NotNull 契約を付けて注釈を付けると、XMLファイルは次のようになります。

<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外部注釈

.NET フレームワーククラスライブラリ、およびその他の頻繁に使用されるライブラリでは、上記の方法で膨大な量のシンボルに注釈を付けました。これらのライブラリ用の外部注釈はReSharperと共にインストールされ、より良いコード分析を保証します。一部の機能(たとえば、ASP.NET MVC 5.2のサポート)も外部注釈に依存しています。

JetBrains外部注釈のソースコードは、GitHub:https://github.com/JetBrains/ExternalAnnotations(英語)のMITライセンスで入手できます。このリポジトリに貢献したり、外部の注釈の例として使用することは大歓迎です。

外部注釈を作成する

コンパイル済みアセンブリの契約を指定するための外部注釈を作成できます。ReSharperが外部注釈付きのXMLファイルを確実に認識するようにするには、このファイルの名前を[Assembly.Name] .ExternalAnnotations.xmlにする必要があります。注釈付きバイナリの使用方法に応じて、次の場所に注釈ファイルを作成できます。

  • バイナリを(NuGetなどで)公開する場合は、注釈付き[Assembly.Name] .ExternalAnnotations.xmlファイルと同じフォルダーに注釈[Assembly.Name] .dllファイルを配置します。

  • プロジェクトに含まれる一部のバイナリに注釈を付ける場合は、プロジェクトまたはソリューションファイルの隣の外部注釈フォルダーに各アセンブリの注釈ファイルを配置します。

    このフォルダーに注釈ファイルを配置するとき、ファイルはアセンブリ名、つまり[Assembly.Name] .xmlに基づいて名前を付ける必要があります。外部注釈のサブフォルダーに存在することもできますが、そのフォルダーにはアセンブリ名、つまりExternalAnnotations / [Assembly.Name] / [AnyName] .xmlが必要です。

    このようにして、VCSの下に注釈を保持して、チームがそれらから利益を得られるようにすることもできます。

外部注釈の作成を説明するために、static string ReverseString(String inputString) メソッドを持つ MyTestClass クラスを持つTestLibアセンブリを使用するとします。アセンブリのドキュメントから、メソッドが純粋であり、nullを返さないこと、およびそのパラメータがnullであってはならないことがわかっていると想定します。

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

External annotations

コンパイルされたアセンブリの外部注釈を作成する

  1. ファイルシステムでTestLib.dllを見つけて、TestLib.ExternalAnnotations.xmlが参照されているプロジェクトまたはソリューションファイルの横にある同じフォルダーまたは外部注釈フォルダーにTestLib.dllという名前のファイルを作成します。

  2. 編集のために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>

  3. 解決策を再読み込みしてください。ReSharperは ReverseString の誤った使用箇所を検出し、nullパラメータに関する問題を強調しています。

    External annotations
    ...戻り値の不要なチェック:
    External annotations

  4. ライブラリシンボルに適用される外部注釈を表示するには、クイック・ドキュメント機能を使用します。シンボル上で Control+Q を押すだけでその属性を調べることができます。我々のケースでは、ReverseString[NotNull] および [Pure] 属性が注釈され、パラメータに [NotNull]が注釈されていることがわかります。

    Viewing quick documentation
    属性の灰色は、アセンブリコードからではなく、外部注釈から来ることを意味します。

外部注釈を配布する

外部注釈を使用するもう1つのケースは、配布するライブラリ、または好きなライブラリに対して外部注釈を公開することです。この場合、ReSharperまたはRiderも使用しているライブラリのユーザーは、より多くの提案や修正を得ます。

ライブラリの外部注釈は、NuGetパッケージとしてReSharperギャラリー(英語)に公開してインストールすることができます。外部注釈のパッケージ化の詳細については、ReSharperプラグイン開発ガイドを参照してください。

最終更新日: 2020年5月26日

関連ページ:

クイック・ドキュメント

ReSharper | 編集 | クイックドキュメントを表示するReSharperを使用すると、エディター内のシンボルのドキュメントをすばやく確認できます。エディターでシンボルの使用箇所の上にマウスを移動すると、簡単な説明を含むポップアップが表示されます。ライブラリシンボルの場合、ポップアップでAl...

シンボル情報をクリップボードにコピー

ReSharperには、シンボル情報をクリップボードにコピーするための便利なコマンドが2つあります。これらのコマンドを頻繁に使用する場合は、対応するコマンドにショートカットを割り当てるか(見出しのコマンドエイリアスを参照)、または行動に移動するを使用できます。XML-Doc IDをコピー:ReSha...

ソースコードの注釈

ReSharperのコード注釈の恩恵を受ける最も簡単な方法は、ソースコードのシンボルに注釈属性を追加し、ReSharperがソリューションをより正確かつ洞察力で分析できるようにすることです。デフォルトでは、すべての注釈属性クラスは属性でマークされているため、コンパイラはコード内の属性の使用を無視しま...

契約の注釈

契約注釈では、与えられた入力に対する期待される出力を定義することができます。言い換えれば、関数の参照型とブール型引数とその戻り値の間の依存関係を定義することができます。契約注釈のメカニズムにより、より簡単で安全な方法で消費できるAPIを作成できます。契約注釈の代わりに、より単純な代替手段を使用したい...