中央パッケージ管理 (CPM)

2025-02-05

依存関係管理は、NuGet のコア機能です。 1 つのプロジェクトの依存関係の管理は簡単です。マルチプロジェクトソリューションの依存関係の管理は、サイズと複雑さのスケールを開始する際に困難になる可能性があります。多くの異なるプロジェクトの共通の依存関係を管理する状況では、NuGet の中央パッケージ管理 (CPM) 機能を利用して、このすべてを 1 か所で簡単に実行できます。

これまで、NuGet パッケージの依存関係は、次の 2 つの場所のいずれかで管理されてきました。

packages.config - プロジェクトによって参照されるパッケージの一覧を保持するために、以前のプロジェクトの種類で使用される XML ファイル。
<PackageReference /> - MSBuild プロジェクトで使用される XML 要素は、NuGet パッケージの依存関係を定義します。

NuGet 6.2以降では、Directory.Packages.props ファイルと MSBuild プロパティを追加することで、プロジェクト内の依存関係を一元的に管理できます。

この機能は、次のバージョン以降のすべての NuGet 統合ツールで使用できます。

古いツールでは、中央パッケージ管理の構成と機能は無視されます。この機能を最大限に使用するには、すべてのビルド環境で最新の互換性のあるツールバージョンが使用されていることを確認します。

一元的なパッケージ管理は、互換性のあるツールが使用されている限り、すべての <PackageReference>ベースの MSBuild プロジェクト (従来の CSPROJ 含む) に適用されます。

中央パッケージ管理の有効化

パッケージの一元管理を開始するには、リポジトリのルートに Directory.Packages.props ファイルを作成し、MSBuild プロパティの ManagePackageVersionsCentrally を trueに設定する必要があります。

手動で作成することも、dotnet CLI を使用することもできます。

dotnet new packagesprops

その後、パッケージ ID とバージョンを定義する <PackageVersion /> 要素を使用して、プロジェクトに必要な各パッケージバージョンを定義します。

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
  </ItemGroup>
</Project>

その後、プロジェクトごとに<PackageReference />を定義しますが、対応するVersion項目からバージョンが取得されるため、<PackageVersion />属性は省略します。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" />
  </ItemGroup>
</Project>

これで、中央のパッケージ管理を使用し、中央の場所でバージョンを管理します。

中央パッケージ管理ルール

Directory.Packages.props ファイルには、リポジトリのディレクトリとそのコンテキスト内の場所に関する多くの規則があります。わかりやすくするために、特定のプロジェクトに対して評価される Directory.Packages.props ファイルは 1 つだけです。

つまり、リポジトリに複数の Directory.Packages.props ファイルがある場合、プロジェクトのディレクトリに最も近いファイルが評価されます。これにより、リポジトリのさまざまなレベルで追加の制御が可能になります。

次のリポジトリ構造を考えてみましょう。

📂 (root)
 ├─📄 Directory.Packages.props
 |
 ├─📂Solution1
 |  ├─ 📄Directory.Packages.props
 |  |
 |  └─ 📂 Project1
 |      └─📄Project1.csproj
 |
 └─ 📂 Solution2
    └─ 📂 Project2
        └─ 📄 Project2.csproj

Project1.csprojは最初にDirectory.Packages.propsディレクトリにRepository\Solution1\ファイルを読み込みます。必要に応じて、親ファイルを手動でインポートする必要があります。

<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
  <ItemGroup>
    <PackageVersion Update="Newtonsoft.Json" Version="12.0.1" />
  </ItemGroup>
</Project>

Project2.csproj は、ルートディレクトリ内の Directory.Packages.props ファイルを評価します。

手記： MSBuild では、各 Directory.Packages.props は自動的にはインポートされず、プロジェクトディレクトリまたは親ディレクトリで最初に見つかったものだけがインポートされます。複数の Directory.Packages.props ファイルがある場合は、親ディレクトリ内のすべてのファイルを手動でインポートする必要があります。

作業の開始

リポジトリを完全にオンボードするには、次の手順に従います。

Directory.Packages.props という名前のリポジトリのルートに新しいファイルを作成し、一元的に定義されたパッケージバージョンを宣言し、MSBuild プロパティの ManagePackageVersionsCentrally を trueに設定します。
<PackageVersion />で Directory.Packages.props 項目を宣言します。
プロジェクトファイルで、<PackageReference /> 属性なしで Version 項目を宣言します。

中央パッケージ管理がどのように見えるかについては、サンプルリポジトリを参照してください。

転移可能なピン留め

推移的なピン留めと呼ばれる機能を選択することで、明示的な最上位レベルの <PackageReference /> がなくても、推移的なパッケージバージョンを自動的にオーバーライドできます。これにより、必要に応じて、推移的な依存関係が、ユーザーの代わりに暗黙的に最上位の依存関係に昇格します。パッケージを推移的にピン留めする場合、ダウングレードは許可されないことに注意してください。依存関係によって要求されたバージョンよりも低いバージョンにパッケージをピン留めしようとすると、復元時に NU1109 エラーが発生します。

この機能を有効にするには、プロジェクトまたは CentralPackageTransitivePinningEnabled、true で、MSBuild プロパティ Directory.Packages.props を Directory.Build.props に設定します。

<PropertyGroup>
  <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
</PropertyGroup>

トランジティブピン留めとパッケージング

パッケージが推移的にピン留めされている場合、プロジェクトは依存関係によって要求されたものよりも高い値を使用します。プロジェクトからパッケージを作成する場合、パッケージが確実に機能するように、NuGet は推移的にピン留めされた依存関係を nuspec 内の明示的な依存関係に昇格させます。

次の例では、PackageA 1.0.0 は PackageB 1.0.0に依存しています。

<Project>
  <ItemGroup>
    <PackageVersion Include="PackageA" Version="1.0.0" />
    <PackageVersion Include="PackageB" Version="2.0.0" />
  </ItemGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="PackageA" />
  </ItemGroup>
</Project>

pack コマンドを使用してパッケージを作成すると、両方のパッケージが依存関係グループに表示されます。

      <group targetFramework="net6.0">
        <dependency id="PackageA" version="1.0.0" exclude="Build,Analyzers" />
        <dependency id="PackageB" version="2.0.0" exclude="Build,Analyzers" />
      </group>

このため、ライブラリを作成するときに推移的なピン留めの使用を慎重に評価する必要があります。これは、予期していなかった依存関係につながる可能性があるためです。

パッケージバージョンの上書き

VersionOverride 項目の <PackageReference /> プロパティを使用して、個々のパッケージバージョンをオーバーライドできます。これにより、一元的に定義されたすべての <PackageVersion /> がオーバーライドされます。

<Project>
  <ItemGroup>
    <PackageVersion Include="PackageA" Version="1.0.0" />
    <PackageVersion Include="PackageB" Version="2.0.0" />
  </ItemGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="PackageA" VersionOverride="3.0.0" />
  </ItemGroup>
</Project>

この機能を無効にするには、MSBuild プロパティ CentralPackageVersionOverrideEnabled を false に設定し、プロジェクトや Directory.Packages.props、Directory.Build.props インポートファイルで指定してください。

<PropertyGroup>
  <CentralPackageVersionOverrideEnabled>false</CentralPackageVersionOverrideEnabled>
</PropertyGroup>

この機能を無効にすると、VersionOverride 項目に <PackageReference /> を指定すると、復元時に機能が無効であることを示すエラーが発生します。

中央パッケージ管理の無効化

特定のプロジェクトの中央パッケージ管理を無効にする場合は、MSBuild プロパティの ManagePackageVersionsCentrally を falseに設定して無効にすることができます。

<PropertyGroup>
  <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
</PropertyGroup>

グローバルパッケージ参照

手記

この機能は、Visual Studio 2022 17.4 以降、.NET SDK 7.0.100.preview7 以降、および NuGet 6.4 以降でのみ使用できます。

グローバルパッケージ参照は、リポジトリ内のすべてのプロジェクトでパッケージを使用することを指定するために使用されます。これには、バージョン管理を行うパッケージ、ビルドを拡張するパッケージ、またはすべてのプロジェクトで必要なその他のパッケージが含まれます。グローバルパッケージ参照は、次のメタデータを使用して PackageReference 項目グループに追加されます。

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
これにより、パッケージが開発依存関係としてのみ使用され、コンパイル時のアセンブリ参照が防止されます。
PrivateAssets="All"
これにより、グローバルパッケージ参照がダウンストリームの依存関係によって取得されなくなります。

GlobalPackageReference 項目は、リポジトリ内のすべてのプロジェクトで使用される Directory.Packages.props に配置する必要があります。

<Project>
  <ItemGroup>
    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.5.109" />
  </ItemGroup>
</Project>

複数のパッケージソースを使用する場合の警告

中央パッケージ管理を使用する場合、構成で複数のパッケージソースが定義されている場合、NU1507 警告が表示されます。この警告を解決するには、パッケージソースをパッケージソースマッピングにマップするか、単一のパッケージソースを指定します。

There are 3 package sources defined in your configuration. When using central package management, please map your package sources with package source mapping (https://aka.ms/nuget-package-source-mapping) or specify a single package source.

次の方法で共有

中央パッケージ管理 (CPM)

中央パッケージ管理の有効化

中央パッケージ管理ルール

作業の開始

転移可能なピン留め

トランジティブピン留めとパッケージング

パッケージ バージョンの上書き

中央パッケージ管理の無効化

グローバル パッケージ参照

複数のパッケージ ソースを使用する場合の警告

フィードバック

その他のリソース

パッケージバージョンの上書き

グローバルパッケージ参照

複数のパッケージソースを使用する場合の警告