プロジェクトファイルの `PackageReference`

[アーティクル]
08/10/2023

<PackageReference> MSBuild 項目を使うパッケージ参照では、個別の packages.config ファイルを持つのではなく、プロジェクトファイル内で直接 NuGet パッケージの依存関係を指定します。 PackageReference の使用では、NuGet の他の側面には影響を与えません。たとえば、(パッケージソースを含む) NuGet.Config ファイルの設定が、「NuGet の動作を構成する」で説明されているように引き続き適用されます。

PackageReference の場合、MSBuild 条件を使用し、ターゲットフレームワークまたはその他のグループ化ごとにパッケージ参照を選択することもできます。依存関係とコンテンツフローを細かく制御することもできます。 (詳細については、「NuGet pack and restore as MSBuild targets」(MSBuild ターゲットとしての NuGet のパックと復元) を参照してください)。

プロジェクトの種類のサポート

既定では、PackageReference は、Windows 10 Build 15063 (Creators Update) 以降を対象とする .NET Core プロジェクト、.NET Standard プロジェクト、および UWP プロジェクトに使用されます。ただし、C++ UWP プロジェクトは例外です。 .NET Framework プロジェクトは PackageReference をサポートしていますが、現在の既定は packages.config です。 PackageReference を使用するには、依存関係を packages.config からプロジェクトファイルに "移行" してから、packages.config を削除します。

完全な .NET Framework を対象とする ASP.NET アプリには、PackageReference の制限されたサポートしか追加されません。 C++ および JavaScript のプロジェクトタイプはサポートされていません。

PackageReference を追加する

次の構文を使用し、プロジェクトファイルに依存関係を追加します。

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

依存関係のバージョンを制御する

パッケージのバージョンを指定するための規則は、packages.config を使用する場合と同じです。

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

上記の例では、3.6.0 は 3.6.0 以上のあらゆるバージョンを意味し、最も下のバージョンが優先されます。詳細は、「Package versioning」(パッケージバージョン) にあります。

パッケージの依存関係がないプロジェクトに対する PackageReference の使用

詳細: プロジェクトにパッケージをインストールしていないが (プロジェクトファイルに PackageReferences がなく、packages.config ファイルがない)、プロジェクトを PackageReference スタイルで復元する場合、プロジェクトファイルで Project プロパティ RestoreProjectStyle を PackageReference に設定できます。

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>

PackageReference スタイル (既存の csproj または SDK スタイルのプロジェクト) のプロジェクトを参照するとき、この設定が便利になることがあります。そのようなプロジェクトが参照するパッケージを他のプロジェクトで "推移的に" 参照できます。

PackageReference とソース

PackageReference プロジェクトでは、推移的な依存関係バージョンは復元時に解決されます。そのため、PackageReference プロジェクトでは、すべてのソースがすべての復元に使用できる必要があります。

依存関係アセットを制御する

開発ハーネスとしてのみ依存関係を使用するとき、それはパッケージを使用するプロジェクトに公開しないほうが好ましい場合があります。このシナリオでは、PrivateAssets メタデータを使用し、この動作を制御できます。

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

次のメタデータタグは依存関係アセットを制御します。

タグ	説明	Default Value
IncludeAssets	これらのアセットは使用されます	すべて
ExcludeAssets	これらのアセットは使用されません	なし
PrivateAssets	これらのアセットは使用されますが、親プロジェクトに流れません	contentfiles;analyzers;build

これらのタグに使用できる値は次のようになります。単独で表示する all と none を除き、複数の値はセミコロンで区切られます。

Value	説明
compile	`lib` フォルダーの内容と、プロジェクトをフォルダー内のアセンブリに対してコンパイルできるかどうかのコントロール
ランタイム	`lib` と `runtimes` フォルダーの内容と、これらのアセンブリがコピーされて出力ディレクトリをビルドするかどうかのコントロール
contentFiles	`contentfiles` フォルダーの内容
build	`build` フォルダー内の `.props` と `.targets`
buildMultitargeting	(4.0)`buildMultitargeting` フォルダー内の `.props` と `.targets` (フレームワーク間でのターゲット設定用)
buildTransitive	(5.0 以降)`buildTransitive` フォルダー内の `.props` と `.targets` (使用するプロジェクトに推移的にフローするアセット用)。機能に関するページをご覧ください。
analyzers	.NET アナライザー
native	`native` フォルダーの内容
なし	上記のいずれも該当しない。
すべて	上記のすべて (`none` を除く)

<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</PrivateAssets>
    </PackageReference>
    <!-- ... -->
</ItemGroup>

build は PrivateAssets で含まれないため、targets と props は親プロジェクトに流れることに注目してください。たとえば、上記の参照は、AppLogger という名前の NuGet パッケージをビルドするプロジェクトで使用されます。 AppLogger は、AppLogger を使用するプロジェクトと同様に、Contoso.Utility.UsefulStuff から targets と props を使用できます。

Note

.nuspec ファイル内で developmentDependency が true に設定されている場合、パッケージが開発専用の依存関係としてマークされます。これにより、そのパッケージは他のパッケージに依存関係として含まれなくなります。 PackageReference (NuGet 4.8 以降) では、このフラグは、コンパイルからコンパイル時アセットを除外することも意味します。詳しくは、「DevelopmentDependency support for PackageReference (PackageReference に対する DevelopmentDependency のサポート)」をご覧ください。

PackageReference 条件を追加する

条件を使用し、パッケージを含めるかどうかを制御できます。条件では、あらゆる MSBuild 変数や、targets または props ファイルに定義されている変数を使用できます。ただし、現在のところ TargetFramework 変数のみに対応しています。

たとえば、net452 と共に netstandard1.4 を対象とするが、net452 にのみ該当する依存関係があるとします。その場合、パッケージを使用する netstandard1.4 プロジェクトでは、その不要な依存関係を追加することが望まれません。それを回避するために、次のように PackageReference で条件を指定します。

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

このプロジェクトでビルドされたパッケージには、net452 ターゲットのみの依存関係として Newtonsoft.json が追加されることが示されます。

The result of applying a Condition on PackageReference with VS2017

条件は ItemGroup レベルでも適用できます。また、条件はすべての子 PackageReference 要素に適用されます。

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathProperty

この機能を使用できるのは、NuGet 5.0 以降で、かつ Visual Studio 2019 16.0 以降を使用している場合です。

場合によっては、MSBuild ターゲットからパッケージ内のファイルを参照することが望ましい場合があります。 packages.config ベースのプロジェクトでは、パッケージは、プロジェクトファイルに対して相対的なフォルダーにインストールされます。ただし、PackageReference では、パッケージは "グローバルパッケージ" フォルダーから使用されます。このフォルダーは、マシンごとに異なる場合があります。

このギャップを埋めるために、NuGet では、パッケージの使用元となる場所を指すプロパティが導入されました。

例:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

また、NuGet では、ツールフォルダーを含むパッケージのプロパティが自動的に生成されます。

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

MSBuild のプロパティとパッケージ ID には同じ制限がないため、パッケージ ID を MSBuild の表示名 (Pkg という語が接頭辞として付けられます) に変更する必要があります。生成されたプロパティの正確な名前を確認するには、生成された nuget.g.props ファイルを調べます。

PackageReference の別名

まれに、異なるパッケージに同じ名前空間のクラスが含まれている場合があります。 NuGet 5.7 および Visual Studio 2019 Update 7 以降、ProjectReference と同等の PackageReference は Aliases をサポートしています。既定では、別名は用意されていません。別名が指定されている場合、注釈付きパッケージに由来する "すべての" アセンブリは、別名で参照する必要があります。

サンプルの使用方法については、NuGet\Samples を参照してください。

プロジェクトファイルで、次のように別名を指定します。

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

また、コードで次のように使用します。

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

NuGet の警告とエラー

"この機能を使用できるのは、NuGet 4.3 以降で、かつ Visual Studio 2017 15.3 以降を使用している場合です。"

多くのパックと復元シナリオでは、すべての NuGet の警告とエラーがコード化され、NU**** から始まります。すべての NuGet の警告とエラーは、リファレンスドキュメントに記載されています。

NuGet では、次の警告プロパティが監視されます。

TreatWarningsAsErrors: すべての警告をエラーとして扱います。
WarningsAsErrors: 指定した警告をエラーとして扱います。
NoWarn: 特定の警告を非表示にします (プロジェクト全体またはパッケージ全体)。

例 :

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

NuGet 警告の非表示

パックと復元操作中にすべての NuGet 警告を解決することをお勧めしますが、特定の状況では、それらを非表示にすることが認められています。プロジェクト全体で警告を非表示にするには、次のことを検討してください。

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

警告は、グラフ内の特定のパッケージにのみ適用されることがあります。 PackageReference 項目に NoWarn を追加することで、その警告をより選択的に非表示にすることができます。

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Visual Studio での NuGet パッケージ警告の非表示

Visual Studio では、IDE から警告を非表示にすることもできます。

依存関係のロック

"この機能を使用できるのは、NuGet 4.9 以降で、かつ Visual Studio 2017 15.9 以降を使用している場合です。"

NuGet の復元への入力は、プロジェクトファイルのPackageReference 項目のセット (最上位レベルまたは直接の依存関係) であり、出力は推移的依存関係を含むパッケージのすべての依存関係の完全なクロージャーです。入力の PackageReference リストが変更されていない場合、NuGet では常に同じパッケージの依存関係の完全なクロージャーを生成しようとします。ただし、このようにすることができないシナリオがいくつかあります。次に例を示します。

<PackageReference Include="My.Sample.Lib" Version="4.*"/> などの浮動バージョンを使用する場合。ここでの意図はパッケージの復元ごとに最新バージョンに浮動することですが、グラフを特定の最新バージョンにロックして、利用可能な場合は明示的なジェスチャに基づいて後続のバージョンに浮動させることをユーザーが求めるシナリオがあります。
PackageReference のバージョン要件と一致する新しいパッケージのバージョンが公開されている場合。例:
- 1 日目: <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> を指定したが、NuGet リポジトリで利用可能なバージョンが 4.1.0、4.2.0 および 4.3.0 だった場合。この場合、NuGet は 4.1.0 (最小に最も近いバージョン) に解決されています。
- 2 日目: バージョン 4.0.0 が公開されます。 NuGet では完全一致が検索され、4.0.0 への解決が始められます。
指定したパッケージバージョンがリポジトリから削除される場合。 nuget.org ではパッケージの削除が許可されていませんが、すべてのパッケージリポジトリがこの制約を持っているわけではありません。これにより、削除されたバージョンに解決できない場合、NuGet では最適な一致が検索されます。

ロックファイルを有効にする

パッケージの依存関係の完全なクロージャーを保持するために、プロジェクトに対して MSBuild プロパティ RestorePackagesWithLockFile を設定して、ロックファイル機能にオプトインすることができます。

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>

このプロパティが設定されている場合、NuGet の復元でロックファイル (すべてのパッケージの依存関係を一覧表示する packages.lock.json ファイル) が生成されます。

Note

プロジェクトのルートディレクトリに packages.lock.json ファイルが含まれている場合、プロパティ RestorePackagesWithLockFile が設定されていない場合でも、常に復元でロックファイルが使用されます。そのため、この機能にオプトインする別の方法は、プロジェクトのルートディレクトリに空の packages.lock.json ファイルをダミーとして作成することです。

ロックファイルでの `restore` の動作

プロジェクトにロックファイルが存在する場合、NuGet では restore を実行するためにこのロックファイルが使用されます。プロジェクトファイル (または依存プロジェクトのファイル) で言及されたパッケージの依存関係に変更があったかどうか確認するために、NuGet で簡単なチェックが行われます。変更がなかった場合は、ロックファイルで言及されたパッケージを単純に復元します。パッケージの依存関係を再評価することはありません。

NuGet によって、プロジェクトファイルで言及したような定義された依存関係の変更が検出された場合、パッケージグラフが再評価され、プロジェクトの新しいパッケージクロージャを反映するためにロックファイルが更新されます。

実行中にパッケージの依存関係を変更したくない CI/CD やその他のシナリオでは、lockedmode を true に設定することでこれを実行できます。

dotnet.exe の場合は、次を実行します。

> dotnet.exe restore --locked-mode

msbuild.exe の場合は、次を実行します。

> msbuild.exe -t:restore -p:RestoreLockedMode=true

自分のプロジェクトファイルにもこの条件付き MSBuild プロパティを設定できます。

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup>

ロックモードが true である場合、復元ではロックファイルに記載されている正確なパッケージが復元されるか、または、ロックファイルの作成後にプロジェクトの定義されたパッケージの依存関係を更新した場合は、失敗します。

ロックファイルをソースリポジトリの一部にする

アプリケーションを作成する場合、目的の実行可能ファイルとプロジェクトは依存関係チェーンの最初に位置します。NuGet が復元中にこれを使用できるように、ロックファイルをソースコードリポジトリにチェックインします。

ただし、当該プロジェクトが出荷しないライブラリプロジェクトである場合や、他のプロジェクトが依存する共通コードプロジェクトである場合は、ソースコードの一部としてロックファイルをチェックインしないでください。ロックファイルを保持しても問題はありませんが、共通コードプロジェクトのロックされているパッケージの依存関係は、ロックファイル内で記載されているように、この共通コードプロジェクトに依存するプロジェクトの復元/ビルド中に使用されない場合があります。

例:

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

ProjectA が PackageX のバージョン 2.0.0 に依存し、PackageX のバージョン 1.0.0 に依存する ProjectB も参照している場合、ProjectB のロックファイルでは PackageX のバージョン 1.0.0 に対する依存関係が記載されます。ただし、ProjectA をビルドすると、そのロックファイルには PackageX のバージョン 2.0.0 に対する依存関係が含まれます。ProjectB のロックファイルに記載されている 1.0.0 ではありません。したがって、共通コードプロジェクトのロックファイルは、それが依存するプロジェクトのために解決されるパッケージに対して強い力を持っていません。

ロックファイルの拡張機能

以下で説明するように、ロックファイルを使用して復元のさまざまな動作を制御できます。

NuGet.exe オプション	dotnet オプション	対応する MSBuild オプション	説明
`-UseLockFile`	`--use-lock-file`	RestorePackagesWithLockFile	ロックファイルの使用をオプトインします。
`-LockedMode`	`--locked-mode`	RestoreLockedMode	復元のロックモードを有効にします。これは、繰り返し可能なビルドを必要とする CI/CD のシナリオで役立ちます。
`-ForceEvaluate`	`--force-evaluate`	RestoreForceEvaluate	このオプションは、プロジェクトで定義する浮動バージョンを使用するパッケージで役立ちます。既定では、NuGet の復元では、このオプションを指定して復元を実行しない限り、復元ごとのパッケージバージョンの自動更新は行われません。
`-LockFilePath`	`--lock-file-path`	NuGetLockFilePath	プロジェクトのカスタムロックファイルの場所を定義します。既定では、NuGet はルートディレクトリでの `packages.lock.json` をサポートします。同じディレクトリ内に複数のプロジェクトがある場合、NuGet はプロジェクト固有のロックファイル `packages.<project_name>.lock.json` をサポートします。

AssetTargetFallback

AssetTargetFallback プロパティを使用すると、プロジェクトから参照されるプロジェクトの互換性のある追加のフレームワークバージョンと、プロジェクトに使用する NuGet パッケージを指定できます。

PackageReference を使用してパッケージの依存関係を指定し、そのパッケージにプロジェクトのターゲットフレームワークと互換性のある資産が含まれない場合は、AssetTargetFallback プロパティが機能します。参照されたパッケージの互換性は、AssetTargetFallback で指定された各ターゲットフレームワークを使用して再確認されます。 project または package が AssetTargetFallback によって参照されている場合、NU1701 警告が表示されます。

AssetTargetFallback が互換性に与える影響の例については、次の表を参照してください。

プロジェクトフレームワーク	AssetTargetFallback	パッケージフレームワーク	結果
.NET Framework 4.7.2		.NET Standard 2.0	.NET Standard 2.0
.NET Core App 3.1		.NET Standard 2.0、.NET Framework 4.7.2	.NET Standard 2.0
.NET Core App 3.1		.NET Framework 4.7.2	互換性がありません。`NU1202` で失敗します
.NET Core App 3.1	net472;net471	.NET Framework 4.7.2	.NET Framework 4.7.2。`NU1701` が表示されます

; を区切り記号として使用して、複数のフレームワークを指定できます。フォールバックフレームワークを追加するには、次の操作を行います。

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

既存の AssetTargetFallback 値に追加するのではなく、上書きする場合は、$(AssetTargetFallback) は省略できます。

Note

.NET SDK ベースのプロジェクトを使用している場合は、適切な $(AssetTargetFallback) 値が構成されるため、手動で設定する必要はありません。

$(PackageTargetFallback) は、この課題に対処しようとした初期の機能でしたが、根本的には破損しているため、使用 "しないでください"。 $(PackageTargetFallback) から $(AssetTargetFallback) に移行するには、プロパティ名を変更するだけです。

プロジェクトファイルの `PackageReference`

プロジェクトの種類のサポート

PackageReference を追加する

依存関係のバージョンを制御する

パッケージの依存関係がないプロジェクトに対する PackageReference の使用

PackageReference とソース

最新バージョン

依存関係アセットを制御する

PackageReference 条件を追加する

GeneratePathProperty

PackageReference の別名

NuGet の警告とエラー

NuGet 警告の非表示

Visual Studio での NuGet パッケージ警告の非表示

依存関係のロック

ロックファイルを有効にする

ロックファイルでの `restore` の動作

ロックファイルをソースリポジトリの一部にする

ロックファイルの拡張機能

AssetTargetFallback

フィードバック

フィードバック

その他のリソース

プロジェクト ファイルの PackageReference

プロジェクトの種類のサポート

PackageReference を追加する

依存関係のバージョンを制御する

パッケージの依存関係がないプロジェクトに対する PackageReference の使用

PackageReference とソース

最新バージョン

依存関係アセットを制御する

PackageReference 条件を追加する

GeneratePathProperty

PackageReference の別名

NuGet の警告とエラー

NuGet 警告の非表示

Visual Studio での NuGet パッケージ警告の非表示

依存関係のロック

ロック ファイルを有効にする

ロック ファイルでの restore の動作

ロック ファイルをソース リポジトリの一部にする

ロック ファイルの拡張機能

AssetTargetFallback

フィードバック

フィードバック

その他のリソース

プロジェクトファイルの `PackageReference`

ロックファイルを有効にする

ロックファイルでの `restore` の動作

ロックファイルをソースリポジトリの一部にする

ロックファイルの拡張機能