PackageReference をプロジェクトファイルに

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

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

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

既定では、PackageReference は、C++ UWP プロジェクトを除き、Windows 10 ビルド 15063 (Creators Update) 以降を対象とする .NET プロジェクト、.NET Standard プロジェクト、および UWP プロジェクトに使用されます。 .NET Framework プロジェクトは PackageReference をサポートしていますが、現在の既定は packages.config です。 .NET Framework プロジェクトで 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 で最下位バージョンを優先するバージョン を意味します。

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

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

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

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

PackageReference と提供元

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

フローティング バージョン

浮動バージョンは、PackageReference でサポートされています。

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

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

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

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

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

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

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

これらのタグに使用できる値は次のとおりです。複数の値は、 all と 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 は、Contoso.Utility.UsefulStuff から targets や props を取得できるように、それを利用するプロジェクトも同じく取得できます。

PackageReference 条件を追加する

条件を使用して、パッケージを含めるかどうかを制御できます。 条件では、ターゲットまたは props ファイルで定義されている任意の MSBuild 変数または変数を使用できます。 ただし、現時点では、 TargetFramework 変数のみがサポートされています。

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

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

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

VS2017 で PackageReference に条件を適用した結果

条件は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 では、パッケージの使用元となる場所を指すプロパティが導入されました。

Example:

  <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: 特定の警告を非表示にします（プロジェクト全体またはパッケージ全体で）。

Examples:

<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) がプロジェクト のルート ディレクトリに生成されます。

ロック ファイルでの 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 が復元中に使用できるように、ロック ファイルをソース コード リポジトリにチェックインします。

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

Example:

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 依存関係リゾルバー

NuGet 依存関係リゾルバーは、 依存関係解決ドキュメントで説明されている 4 つの規則に従います。

復元操作のパフォーマンスとスケーラビリティを向上させるために、復元アルゴリズムは 6.12 リリースで書き換えられました。 6.12 リリースの時点では、すべての PackageReference プロジェクトに対して新しい復元アルゴリズムが既定で有効になっています。 新しい復元アルゴリズムは以前の復元アルゴリズムと機能的には同一のものですが、ソフトウェアと同様にバグが発生する可能性があります。 前の実装に戻すには、MSBuild プロパティ RestoreUseLegacyDependencyResolver を true に設定します。

以前のバージョンで再現されていない 6.12、.NET 9、または 17.12 で復元エラーが発生した場合は、GitHub で問題を報告してください。 古いアルゴリズムと新しいアルゴリズムの違いは、コンパイル中やランタイム時など、異なる影響を与える可能性があります。 また、変更によってエラーが発生せず、異なるパッケージ バージョンが復元される可能性もあります。 変更の影響を受ける可能性があると思われる場合は、NuGet 復元アルゴリズムの変更が根本原因であるかどうかを確認するために実行できる手順を次に示します。

復元はMSBuildProjectExtensionsPathディレクトリに結果を書き込みます。これにより、新旧のアルゴリズムを比較して違いを見つけることができます。 通常、これがビルドのobjフォルダーです。 次の手順では、msbuild.exe または dotnet.exe を使用できます。

1. プロジェクトの フォルダーを削除します。

2. msbuild -t:restore を実行します。

3. obj の内容を、new 動作であることを示す場所に保存します。

4. msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true" を実行します。

5. obj の内容を、new 動作であることを示す場所に保存します。

6. 2 つのディレクトリ (特に project.assets.json) のファイルを比較します。

   相違点を強調表示できるツールは、この場合に特に役立ちます (たとえば、Visual Studio Code では両方のファイルを開き、右クリックして [比較の選択] と [選択したファイルと比較] を使用します)。

上記の方法に従うと、project.assets.json ファイル間に正確に 1 つの違いがあるはずです。

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

その他の違いがある場合は、すべての詳細を GitHub で問題を報告してください。

AssetTargetFallback

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

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

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

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

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

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

PrunePackageReference

.NET ランタイムは絶えず進化しており、パフォーマンスが向上し、リリースごとに新しい API が追加されています。 .NET に追加された新機能もパッケージとして提供されるため、以前のターゲット フレームワークを使用する開発者は 、System.Text.Json などのライブラリを使用できます。 これにより、多くの場合、System.Text.Json 8.0.0または.NET 9を対象とするプロジェクトで.NET 8が発生する可能性があります。 この依存関係は不要であり、ビルド競合の解決では、.NET ランタイムで既に使用できるため、パッケージから取得されたアセンブリは使用されません。 NuGet バージョン 6.13 および .NET SDK 9.0.200 以降では、PrunePackageReference.NET SDK ベースのプロジェクトの復元時にこれらのパッケージを排除できます。 最初のバージョンでは推移的なパッケージのみに影響を与えていた排除ですが、.NET SDK 10 以降では、直接パッケージにも排除が影響を与えます。

パッケージの排除は、.NET 9 SDK のオプトイン機能として使用でき、.NET 10 SDK の >= .NET 10.0 を対象とするプロジェクトのすべてのフレームワークに対して既定で有効になっています。

パッケージの排除は、 6.12 でリリースされた既定の依存関係リゾルバーでのみ使用できます。

PrunePackageReference の仕様

排除するパッケージの一覧は、 PrunePackageReference 項目で定義されます。

次のプロパティを使用して、排除動作を変更できます。

.NET SDK では、排除するパッケージの一覧が事前に定義されています。

PrunePackageReference のしくみ

復元中に排除するようにパッケージを指定すると、依存関係グラフから削除されます。 パッケージが除去されると、特定のターゲットフレームワークに対してパッケージが削除されたことを示すメッセージが詳細モードで表示されます。

推移的なパッケージ (つまり、他のパッケージまたはプロジェクトの依存関係) の場合、パッケージはダウンロードされず、NuGet のどの出力にも表示されません。

直接パッケージの場合、 PrivateAssets='all' と IncludeAssets='none' が暗黙的に適用されます。

• IncludeAssets='none' は、ビルド中にこのパッケージのアセンブリが使用されないようにします。 トリミングが存在する前は、ビルド中の競合解決によってプラットフォームアセンブリがパッケージからのアセンブリよりも優先されることが保証されていました。
• PrivateAssets='all' は、パッケージがパッケージまたはプロジェクト参照に含まれていないことを保証します。

Example:

次のようなプロジェクト:

  <PropertyGroup>
    <TargetFrameworks>net9.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.Text.Json" Version="9.0.4" />
  </ItemGroup>

は、次の依存関係を持つ nuspec を持ちます。

<dependencies>
    <group targetFramework=".NETFramework4.7.2">
        <dependency id="System.Text.Json" version="9.0.4" />
    </group>
    <group targetFramework="net9.0">
    </group>
</dependencies>

直接 PackageReference をプロジェクトから完全に削除でき、プロジェクト フレームワークの 1 つが .NET 10 以降である場合は、パッケージの削除を求める NU1510 が発生します。 この提案に従うと、プロジェクト グラフの複雑さが軽減されます。

次の表は、すべてのパッケージの排除動作をまとめたものです。

PrunePackageReference アプリケーション

パッケージの剪定には 2 つの主な利点があります。

• 依存関係グラフ内のパッケージの数を減らすことにより、パフォーマンスの利点が得られます
• 次のようなコンポーネント スキャナーによる誤検知の削減 NuGetAudit

排除は、NuGetAuditModeがallに設定されたパッケージを監査する場合に特に重要です。 .NET 9 を使用している場合は、 RestoreEnablePackagePruning を true に設定して排除を試してみることをお勧めします。