project.json と UWP

2025-02-05

大事な

このコンテンツは非推奨です。プロジェクトでは PackageReference 形式を使用する必要があります。 project.json プロジェクトを PackageReference に移行方法について説明します。

このドキュメントでは、NuGet 3 以降 (Visual Studio 2015 以降) の機能を使用するパッケージ構造について説明します。 .nuspec の minClientVersion プロパティを使用して、3.1 に設定することで、ここで説明する機能が必要であることを示すことができます。

既存のパッケージへの UWP サポートの追加

既存のパッケージがあり、UWP アプリケーションのサポートを追加する場合は、ここで説明するパッケージ形式を採用する必要はありません。この形式を採用する必要があるのは、記述されている機能が必要で、NuGet クライアントのバージョン 3 以降に更新されたクライアントでのみ動作する場合のみです。

既に netcore45 をターゲットにしています

既に netcore45 をターゲットにしていて、ここで機能を利用する必要がない場合は、アクションは必要ありません。 netcore45 パッケージは、UWP アプリケーションで使用できます。

Windows 10 固有の API を利用したい

この場合は、uap10.0 ターゲットフレームワークモニカー (TFM または TxM) をパッケージに追加する必要があります。パッケージに新しいフォルダーを作成し、Windows 10 で動作するようにコンパイルされたアセンブリをそのフォルダーに追加します。

Windows 10 固有の API は必要ありませんが、新しい .NET 機能が必要であるか、netcore45 がまだない

この場合は、パッケージに dotnet TxM を追加します。他の TxMs とは異なり、dotnet は、サーフェス領域やプラットフォームを意味しません。パッケージは、依存関係が動作するすべてのプラットフォームで動作することが示されています。 dotnet TxM を使用してパッケージをビルドする場合、依存する BCL パッケージ (System.Text、System.Xmlなど) を定義する必要がある場合、.nuspecに TxM 固有の依存関係が多数存在する可能性があります。これらの依存関係が動作する場所によって、パッケージが動作する場所が定義されます。

依存関係を確認する方法

一覧表示する依存関係を確認するには、次の 2 つの方法があります。

サードパーティ製のツール NuSpec Dependency Generator を使用します。このツールはプロセスを自動化し、ビルド時に依存パッケージを使用して .nuspec ファイルを更新します。 NuSpec.ReferenceGenerator NuGet パッケージを介して入手できます。
(難しい方法)ILDasm を使用して、.dll を調べて、実行時に実際に必要なアセンブリを確認します。次に、それぞれの NuGet パッケージの由来を確認します。

dotnet TxM をサポートするパッケージの作成に役立つ機能の詳細については、project.json トピックを参照してください。

大事な

パッケージが PCL プロジェクトで動作することを目的としている場合は、警告や潜在的な互換性の問題を回避するために、dotnet フォルダーを作成することを強くお勧めします。

ディレクトリ構造

この形式を使用する NuGet パッケージには、次の既知のフォルダーと動作があります。

フォルダ	動作
建てる	MSBuild ターゲットが含まれており、このフォルダー内の props ファイルはプロジェクトに異なる方法で統合されますが、それ以外の場合は変更はありません。
ツール	`install.ps1` と `uninstall.ps1` は実行されません。 `init.ps1` はこれまで通り機能します。
コンテンツ	コンテンツは、ユーザーのプロジェクトに自動的にコピーされません。プロジェクトに含めるコンテンツのサポートは、今後のリリースで予定されています。
Lib	多くのパッケージの場合、`lib` は NuGet 2.x と同じように機能しますが、その中で使用できる名前のオプションが拡張され、パッケージを使用するときに適切なサブフォルダーを選択するためのロジックが向上します。ただし、`ref`と組み合わせて使用すると、`lib` フォルダーには、`ref` フォルダー内のアセンブリによって定義されたサーフェス領域を実装するアセンブリが含まれます。
Ref	`ref` は、コンパイルするアプリケーションのパブリックサーフェス (パブリック型とメソッド) を定義する .NET アセンブリを含む省略可能なフォルダーです。このフォルダー内のアセンブリには実装がない場合があり、コンパイラのサーフェス領域を定義するために純粋に使用されます。パッケージに `ref` フォルダーがない場合、`lib` は参照アセンブリと実装アセンブリの両方になります。
ランタイム	`runtimes` は、CPU アーキテクチャや OS 固有、プラットフォームに依存するバイナリなど、OS 固有のコードを含む省略可能なフォルダーです。

パッケージ内の MSBuild ターゲットと props ファイル

NuGet パッケージには、パッケージがインストールされている MSBuild プロジェクトにインポートされる .targets ファイルと .props ファイルを含めることができます。 NuGet 2.x では、これは、.csproj ファイルに <Import> ステートメントを挿入することによって行われました。NuGet 3.0 では、特定の "プロジェクトへのインストール" アクションはありません。代わりに、パッケージの復元プロセスは、[projectname].nuget.props と [projectname].NuGet.targetsの 2 つのファイルを書き込みます。

MSBuild は、これら 2 つのファイルを検索することを認識し、プロジェクトビルドプロセスの開始時と終了時近くに自動的にインポートします。これは NuGet 2.x とよく似た動作を提供しますが、大きな違いが 1 つあります。この場合、ターゲット/プロップスファイルの順序は保証されていません。ただし、MSBuild には、<Target> 定義の BeforeTargets 属性と AfterTargets 属性を使用してターゲットを並べ替える方法が用意されています (Target Element (MSBuild)を参照してください)。

Lib と Ref

NuGet v3 では、lib フォルダーの動作が大幅に変更されていません。ただし、すべてのアセンブリは TxM に基づく名前のサブフォルダー内に存在する必要があり、lib フォルダーのすぐ下に配置することはできません。 TxM は、パッケージ内の特定の資産が動作するプラットフォームの名前です。論理的には、これらはターゲットフレームワークモニカー (TFM) の拡張機能です。たとえば、net45、net46、netcore50、dnxcore50 はすべて TxM の例です (ターゲットフレームワークの参照)。 TxM は、フレームワーク (TFM) と他のプラットフォーム固有のサーフェス領域を参照できます。たとえば、UWP TxM (uap10.0) は、.NET の表面領域と、UWP アプリケーションの Windows のサーフェス領域を表します。

lib 構造体の例:

lib
├───net40
│       MyLibrary.dll
└───wp81
        MyLibrary.dll

lib フォルダーには、実行時に使用されるアセンブリが含まれています。ほとんどのパッケージでは、ターゲット TxMs ごとに lib 下のフォルダーがすべて必要です。

Ref

コンパイル中に別のアセンブリを使用する必要がある場合があります (現在、.NET 参照アセンブリでこれを行います)。このような場合は、ref ("参照アセンブリ" の略) という最上位フォルダーを使用します。

ほとんどのパッケージ作成者は、ref フォルダーを必要としません。これは、コンパイルと IntelliSense に一貫性のあるサーフェス領域を提供する必要があるが、TxMs ごとに実装が異なるパッケージに役立ちます。この最大のユースケースは、NuGet での .NET Core の出荷の一環として生成される System.* パッケージです。これらのパッケージには、一貫性のある一連の ref アセンブリによって統合されているさまざまな実装があります。

機械的には、ref フォルダーに含まれるアセンブリは、コンパイラに渡される参照アセンブリです。あなたがたのために、csc.exeを使用したユーザーには、C# /reference オプションスイッチに渡すアセンブリがこちらです。

ref フォルダーの構造は、libと同じです。次に例を示します。

└───MyImageProcessingLib
        ├───lib
        │   ├───net40
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   ├───net451
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   └───win81
        │           MyImageProcessingLibrary.dll
        │
        └───ref
            ├───net40
            │       MyImageProcessingLibrary.dll
            │
            └───portable-net451-win81
                    MyImageProcessingLibrary.dll

この例では、ref ディレクトリ内のアセンブリはすべて同じになります。

ランタイム

runtimes フォルダーには、特定の "ランタイム" で実行するために必要なアセンブリとネイティブライブラリが含まれています。これは、一般にオペレーティングシステムと CPU アーキテクチャによって定義されます。これらのランタイムは、win、win-x86、win7-x86、win8-64などのランタイム識別子 (RID) を使用して識別されます。

プラットフォーム固有の API を使用するためのネイティブヘルパー

次の例は、いくつかのプラットフォームに対して純粋に管理された実装を持ち、Windows 8 でネイティブヘルパーを使用し、Windows 8 固有のネイティブ API を呼び出すことができるパッケージを示しています。

└───MyLibrary
        ├───lib
        │   └───net40
        │           MyLibrary.dll
        │
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net40
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyNativeLibrary.dll
            │
            └───win8-x86
                ├───lib
                │   └───net40
                │           MyLibrary.dll
                │
                └───native
                        MyNativeLibrary.dll

上記のパッケージを考えると、次のことが起こります。

Windows 8 以外の場合は、lib/net40/MyLibrary.dll アセンブリが使用されます。
Windows 8 では、runtimes/win8-<architecture>/lib/MyLibrary.dll が使用され、native/MyNativeHelper.dll がビルドの出力にコピーされます。

上記の例では、lib/net40 アセンブリは純粋にマネージドコードですが、ランタイムフォルダー内のアセンブリはネイティブヘルパーアセンブリに対して p/invoke を行い、Windows 8 に固有の API を呼び出します。

選択されるのは 1 つの lib フォルダーのみであるため、ランタイム固有のフォルダーがある場合は、非ランタイム固有の libよりも選択されます。ネイティブフォルダーは追加であり、存在する場合はビルドの出力にコピーされます。

マネージドラッパー

ランタイムを使用するもう 1 つの方法は、ネイティブアセンブリに対して純粋にマネージドラッパーであるパッケージを配布することです。このシナリオでは、次のようなパッケージを作成します。

└───MyLibrary
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net451
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyImplementation.dll
            │
            └───win8-x86
                ├───lib
                │   └───net451
                │           MyLibrary.dll
                │
                └───native
                        MyImplementation.dll

この場合、対応するネイティブアセンブリに依存しないこのパッケージの実装がないため、そのフォルダーとして最上位レベルの lib フォルダーはありません。マネージドアセンブリ (MyLibrary.dll) がどちらの場合もまったく同じである場合は、最上位レベルの lib フォルダーに配置できますが、ネイティブアセンブリがない場合、win-x86 または win-x64 以外のプラットフォームにインストールされている場合、パッケージのインストールが失敗しないため、最上位レベルのライブラリは使用されますが、ネイティブアセンブリはコピーされません。

NuGet 2 および NuGet 3 用のパッケージの作成

packages.config を使用してプロジェクトで使用できるパッケージと、project.json を使用するパッケージを作成する場合は、次のことが適用されます。

Ref とランタイムは NuGet 3 でのみ機能します。どちらも NuGet 2 では無視されます。
install.ps1 や uninstall.ps1 に依存して機能することはできません。これらのファイルは、packages.configを使用するときに実行されますが、project.jsonでは無視されます。そのため、パッケージを実行せずに使用できる必要があります。 init.ps1 は引き続き NuGet 3 で実行されます。
ターゲットと Props のインストールが異なるので、両方のクライアントでパッケージが期待どおりに動作することを確認してください。
lib のサブディレクトリは、NuGet 3 の TxM である必要があります。 lib フォルダーのルートにライブラリを配置することはできません。
コンテンツは NuGet 3 では自動的にはコピーされません。パッケージのコンシューマーは、ファイル自体をコピーしたり、タスクランナーなどのツールを使用してファイルのコピーを自動化したりできます。
ソースファイルと構成ファイルの変換は、NuGet 3 では実行されません。

NuGet 2 と 3 をサポートしている場合、minClientVersion はパッケージが動作する NuGet 2 クライアントの最小バージョンである必要があります。既存のパッケージの場合、変更する必要はありません。