Visual Studio 2017 および .NET SDK 1.0.0 から、NuGet PackageReference 機能が追加されました。
PackageReference を使うと、パッケージの依存関係をプロジェクト ファイル内で直接管理できます。
復元を実行すると、推移的な依存関係が自動的に解決され、プロジェクト グラフ内のパッケージごとに適切な参照が選ばれます。
NuGet バージョン 5.3 では、.NET SDK スタイルのプロジェクト用に PackageDownload というコンパニオン機能が導入され、プロジェクトにそのファイルを含めずにパッケージをダウンロードできるようになりました。
PackageDownload の仕様
PackageDownload は、すべての .NET SDK スタイルのプロジェクトに対応するユーティリティ機能であり、PackageReference と連携して機能します。
PackageDownload 項目は、PackageReference と比較すると、異なる属性をサポートしています。 次の表に記載されている属性のみがサポートされています。
| 属性 | 説明 | 例 |
|---|---|---|
| バージョン | [] で囲まれた正確なバージョンのみがサポートされます。 複数のバージョンを指定するには、; で区切ります。 |
[1.0.0]、[1.0.0];[2.0.0] |
PackageDownload を介して取得したパッケージは PackageReference を介して取得したパッケージと同じインストール処理が行われます。 つまり、パッケージの署名が検証され、パッケージのソース マッピングが考慮されます。 PackageDownload で新しく取得したすべてのパッケージは、グローバル パッケージ フォルダーにインストールされます。
| 機能 | PackageReference | PackageDownload |
|---|---|---|
| パッケージ資産の選択 | パッケージのアセンブリは自動的にプロジェクトに追加され、コンパイルと実行時に使うことができます | パッケージの資産はプロジェクトに含まれません。 |
| 依存関係 | 自動的に解決され、1 つのバージョンにフラット化されます | まったく考慮されません |
| pack | パッケージ仕様に含まれています | パッケージ仕様に含まれていません |
| 推移性 | PackageReference 項目は、依存関係プロジェクトに自動的に反映されます | PackageDownload 項目は、依存関係プロジェクトでは無視されます |
| バージョン | 1.0.0 や [1.0.0, ) などのバージョン範囲がサポートされています。 バージョンは 1 つだけ指定できます。 |
正確なバージョンのみがサポートされています。 複数のバージョンをダウンロードできます。 |
| dotnet list package | すべての依存関係が含まれています | PackageDownload のパッケージは dotnet list package で表示されません。 |
PackageDownload は取得以外の方法でプロジェクトに関連付けられないため、同じパッケージの複数のバージョンをダウンロードできます。
PackageDownload の制限事項
適用範囲が限定された高度な機能であることを考えると、PackageReference と同様のツールのサポートはありません。
- PackageDownload 項目を変更する VisualStudio や dotnet.exe の機能はありません。 プロジェクト ファイル内で手動で変更する必要があります。
- dotnet add、remove、list コマンドは PackageDownload 項目を考慮していません。
- PackageDownload 項目はパッケージ ロック ファイルの一部では "ありません"。
PackageDownload アプリケーション
PackageDownload の主な用途は、従来の NuGet パッケージ構造に従わない、主にビルド時の依存関係を持つパッケージをダウンロードすることです。
理想的には、すべての依存関係を PackageReference を介して表現することですが、それが不可能なシナリオの場合、または、よくあることですが、まだ実用的ではない場合は、この機能を使い、プロジェクトに関連付けられていない packages.config ファイルを使って、それを達成できる同様の方法で、特定の場所へのパッケージの download を単に実行することができます。
例:
<Project Sdk="Microsoft.Build.NoTargets/1.0.80"> <!-- This is not a project we want to build. -->
<PropertyGroup>
<RestorePackagesPath>packages/</RestorePackagesPath> <!-- Changes the global packages folder-->
<MSBuildProjectExtensionsPath>$(RestorePackagesPath)obj/</MSBuildProjectExtensionsPath> <!-- It's still PackageReference, so project intermediates are still created. -->
<TargetFramework>net5.0</TargetFramework> <!-- This is not super relevant, as long as your SDK version supports it. -->
<DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder> <!-- If a package is resolved to a fallback folder, it may not be downloaded.-->
<AutomaticallyUseReferenceAssemblyPackages>false</AutomaticallyUseReferenceAssemblyPackages> <!-- We don't want to build this project, so we do not need the reference assemblies for the framework we chose.-->
</PropertyGroup>
<ItemGroup>
<PackageDownload Include="MySpecialPackage" version="[6.0.0]" />
</ItemGroup>
</Project>