次の方法で共有

参照アセンブリ

参照アセンブリ は、ライブラリのパブリック API サーフェスを表すために必要な最小限のメタデータのみを含む特殊な種類のアセンブリです。 これには、ビルド ツールでアセンブリを参照するときに重要なすべてのメンバーの宣言が含まれます。ただし、すべてのメンバーの実装と、その API コントラクトに影響を与えないプライベート メンバーの宣言は除外されます。 これに対し、通常のアセンブリは 実装アセンブリと呼ばれます。

参照アセンブリを実行用に読み込むことはありませんが、実装アセンブリと同じ方法でコンパイラ入力として渡すことができます。 通常、参照アセンブリは、特定のプラットフォームまたはライブラリのソフトウェア開発キット (SDK) と共に配布されます。

参照アセンブリを使用すると、開発者は、そのバージョンの完全な実装アセンブリを持たずに、特定のライブラリ バージョンを対象とするプログラムをビルドできます。 たとえば、コンピューター上の一部のライブラリの最新バージョンのみを使用しているが、そのライブラリの以前のバージョンを対象とするプログラムを構築するとします。 実装アセンブリに対して直接コンパイルすると、以前のバージョンでは使用できない API メンバーを誤って使用する可能性があります。 この間違いは、ターゲット コンピューターでプログラムをテストする場合にのみ見つかります。 以前のバージョンの参照アセンブリに対してコンパイルすると、コンパイル時エラーがすぐに発生します。

参照アセンブリは、コントラクト、つまり、具象実装アセンブリに対応しない API のセットを表すこともできます。 コントラクト アセンブリと呼ばれるこのような参照 アセンブリを使用して、同じ API のセットをサポートする複数のプラットフォームをターゲットにすることができます。 たとえば、.NET Standard は、異なる .NET プラットフォーム間 で 共有される一連の共通 API を表すコントラクト アセンブリnetstandard.dllを提供します。 これらの API の実装は、.NET Framework でのmscorlib.dll や . NET Core での System.Private.CoreLib.dll など、プラットフォームごとに異なるアセンブリに含まれています。 .NET Standard を対象とするライブラリは、.NET Standard をサポートするすべてのプラットフォームで実行できます。

参照アセンブリの使用

プロジェクトの特定の API を使用するには、アセンブリへの参照を追加する必要があります。 実装アセンブリまたは参照アセンブリへの参照を追加できます。 参照アセンブリは、使用可能な場合は常に使用することをお勧めします。 これにより、API デザイナーが使用することを意図したターゲット バージョンでサポートされている API メンバーのみを使用できるようになります。 参照アセンブリを使用すると、実装の詳細に依存しないようにすることができます。

.NET Framework ライブラリの参照アセンブリは、ターゲット パックと共に配布されます。 これらを取得するには、スタンドアロン インストーラーをダウンロードするか、Visual Studio インストーラーでコンポーネントを選択します。 詳細については、「 開発者向けの .NET Framework のインストール」を参照してください。 .NET Core と .NET Standard の場合、参照アセンブリは必要に応じて (NuGet 経由で) 自動的にダウンロードされ、参照されます。 .NET Core 3.0 以降の場合、コア フレームワークの参照アセンブリは Microsoft.NETCore.App.Ref パッケージにあります ( Microsoft.NETCore.App パッケージは、3.0 より前のバージョンで使用されます)。

Visual Studio で [参照の追加] ダイアログを使用して .NET Framework アセンブリへの 参照を追加 すると、一覧からアセンブリを選択すると、プロジェクトで選択されているターゲット フレームワーク のバージョンに対応する参照アセンブリが Visual Studio によって自動的に検索されます。 参照プロジェクト項目を使用して MSBuild プロジェクトに直接 参照を追加 する場合も同様です。アセンブリ名を指定するだけで、完全なファイル パスは指定できません。 -reference コンパイラ オプション (C# および Visual Basic) を使用するか、Roslyn API の Compilation.AddReferences メソッドを使用して、コマンド ラインでこれらのアセンブリへの参照を追加する場合は、適切なターゲット プラットフォーム バージョンの参照アセンブリ ファイルを手動で指定する必要があります。 .NET Framework 参照アセンブリ ファイルは、 \Reference Assemblies\Microsoft\Framework\%%ProgramFiles(x86) にあります。NETFramework ディレクトリ。 .NET Core の場合、PreserveCompilationContext プロジェクト プロパティを true に設定することで、ターゲット プラットフォームの参照アセンブリを出力ディレクトリの publish/refs サブディレクトリにコピーするように発行操作を強制できます。 その後、これらの参照アセンブリ ファイルをコンパイラに渡すことができます。 Microsoft.Extensions.DependencyModel パッケージからDependencyContextを使用すると、パスを見つけるのに役立ちます。

実装が含まれていないため、参照アセンブリを読み込んで実行することはできません。 これを試みると、 System.BadImageFormatExceptionが発生します。 参照アセンブリの内容を調べる場合は、.NET Framework のリフレクションのみのコンテキスト ( Assembly.ReflectionOnlyLoad メソッドを使用) または .NET および .NET Framework の MetadataLoadContext に読み込むことができます。

参照アセンブリの生成

ライブラリの参照アセンブリを生成すると、ライブラリ コンシューマーがさまざまなバージョンのライブラリに対してプログラムをビルドする必要がある場合に便利です。 これらのすべてのバージョンに実装アセンブリを配布するのは、サイズが大きいため実用的ではない可能性があります。 参照アセンブリのサイズは小さく、ライブラリの SDK の一部として配布すると、ダウンロード サイズが小さくなり、ディスク領域が節約されます。

IDE とビルド ツールでは、参照アセンブリを利用して、複数のクラス ライブラリで構成される大規模なソリューションの場合のビルド時間を短縮することもできます。 通常、増分ビルド のシナリオでは、依存するアセンブリを含め、入力ファイルのいずれかが変更されたときにプロジェクトが再構築されます。 実装アセンブリは、プログラマが任意のメンバーの実装を変更するたびに変更されます。 参照アセンブリは、そのパブリック API が影響を受けるときにのみ変更されます。 そのため、実装アセンブリの代わりに参照アセンブリを入力ファイルとして使用すると、場合によっては依存プロジェクトのビルドをスキップできます。

参照アセンブリを生成できます。

NuGet パッケージを使用して参照アセンブリを配布する場合は、実装アセンブリに使用される lib\ サブディレクトリではなく、パッケージ ディレクトリの ref\ サブディレクトリに含める必要があります。

参照アセンブリの構造

参照アセンブリは、関連する概念である メタデータのみのアセンブリの拡張です。 メタデータのみのアセンブリでは、メソッド本体が 1 つの throw null 本体に置き換えられますが、匿名型を除くすべてのメンバーが含まれます。 throw null本体を使用する理由は、PEVerify を実行して渡すことができる (したがって、メタデータの完全性を検証する) ためです。

参照アセンブリは、メタデータのみのアセンブリからメタデータ (プライベート メンバー) をさらに削除します。

  • 参照アセンブリには、API サーフェイスで必要な参照のみが含まれます。 実際のアセンブリには、特定の実装に関連する追加の参照がある場合があります。 たとえば、 class C { private void M() { dynamic d = 1; ... } } の参照アセンブリは、 dynamicに必要な型を参照しません。
  • プライベート関数メンバー (メソッド、プロパティ、およびイベント) は、削除がコンパイルに影響を与えない場合に削除されます。 InternalsVisibleTo 属性がない場合は、内部関数メンバーも削除されます。

参照アセンブリ内のメタデータは、引き続き次の情報を保持します。

  • プライベート型と入れ子になった型を含むすべての型。
  • すべての属性 (内部属性も含む)。
  • すべての仮想メソッド。
  • 明示的なインターフェイスの実装。
  • アクセサーは仮想であるため、明示的に実装されたプロパティとイベント。
  • 構造体のすべてのフィールド。

参照アセンブリには、アセンブリ レベルの ReferenceAssembly 属性が含 まれます。 この属性はソースで指定できます。コンパイラはそれを合成する必要はありません。 この属性により、ランタイムは実行のために参照アセンブリの読み込みを拒否します (ただし、リフレクションのみのモードで読み込むことができます)。

正確な参照アセンブリ構造の詳細は、コンパイラのバージョンによって異なります。 新しいバージョンでは、パブリック API サーフェスに影響しないと判断された場合は、より多くのメタデータを除外することを選択できます。

注

このセクションの情報は、C# バージョン 7.1 または Visual Basic バージョン 15.3 以降の Roslyn コンパイラによって生成された参照アセンブリにのみ適用されます。 .NET Framework ライブラリと .NET Core ライブラリの参照アセンブリの構造は、参照アセンブリを生成する独自のメカニズムを使用するため、いくつかの詳細で異なる場合があります。 たとえば、 throw null 本体ではなく、メソッド本体が完全に空の場合があります。 ただし、一般的な原則は引き続き適用されます。使用可能なメソッドの実装はなく、パブリック API の観点から観察可能な影響を受けるメンバーに対してのみメタデータが含まれています。

こちらも参照ください