C# の外部アノテーション

使い方

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

この場合、外部アノテーションを使用すると、すでにコンパイルされたエンティティを、JetBrains Fleet のコード分析エンジンによって認識される属性で補完できます。外部アノテーションを使用すると、ライブラリのコンパイル時に宣言されていなかった属性 (メソッド、パラメーター、その他の宣言) をエンジンに参照させることで、エンジンを「騙す」ことができます。

外部アノテーションは XML ファイルで指定されます。ソリューションをロードするとき、JetBrains Fleet は特定の場所にある特定の名前の XML ファイルを検索し、そこからアノテーションを読み取ります。これらの XML ファイルは、XmlDoc に似た構造を持っています。例: NotNull 契約を使用して、.NET フレームワーク 4.0 のアセンブリ System.Xml のメソッド XmlReader.Create(Stream input) にアノテーションを付けるには、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 フレームワーククラスライブラリやその他の頻繁に使用されるライブラリ内の膨大な数のシンボルにアノテーションを付ける際に使用されます。これらのライブラリの外部アノテーションは、より優れたコード分析を確実にするために、JetBrains Fleet とともにインストールされます。一部の機能 (ASP.NET MVC サポートなど) も外部アノテーションに依存しています。

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

外部アノテーションを作成する

外部アノテーションを作成して、コンパイル済みアセンブリの契約を指定できます。JetBrains Fleet が外部アノテーションを含む 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 Fleet は 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 Fleet は ReverseString の誤った使用箇所を検出し、null パラメーターの問題をハイライトします。
... 戻り値の不要なチェック:

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

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

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

2025 年 5 月 15 日

関連ページ：

スマートモード

JetBrains Fleet は、軽量テキストエディターとしても、インテリジェントなコードエディターとしても機能します。システムリソースを最適化するため、リソースを大量に消費する機能は必要な場合にのみ有効になります。スマートモードを有効にすると、個々のファイルまたは複数のファイルを含むフォルダーをシームレスに操作できます。スマートモードを有効にする右上隅にあるスマートモードのステータスアイコンをクリックします。表示されるポップアップで、「有効にする」をクリックします。必要なインデックス作成と準...

C# ソースコードのアノテーション

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

C# の契約のアノテーション

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