中央套件管理（CPM）

發行項
12/14/2023

相依性管理是 NuGet 的核心功能。管理單一專案的相依性很容易。管理多項目解決方案的相依性可能會很困難，因為它們開始調整大小和複雜度。在管理許多不同專案的一般相依性的情況下，您可以利用 NuGet 的中央套件管理（CPM）功能，從單一位置輕鬆完成這一切。

在過去，NuGet 套件相依性已在兩個位置的其中一個中管理：

packages.config - 在舊版項目類型中使用的 XML 檔案，用來維護專案所參考的套件清單。
<PackageReference /> - MSBuild 專案中使用的 XML 元素會定義 NuGet 套件相依性。

從 NuGet 6.2 開始，您可以使用新增檔案和 MSBuild 屬性，集中管理專案中的 Directory.Packages.props 相依性。

從下列版本開始，此功能適用於所有 NuGet 整合式工具。

較舊的工具將會忽略中央套件管理組態和功能。若要充分利用此功能，請確定您的所有組建環境都使用最新的相容工具版本。

只要使用相容的工具，中央套件管理就會套用至所有 <PackageReference>架構的 MSBuild 專案（包括舊版 CSPROJ）。

啟用中央套件管理

若要開始使用中央套件管理，您必須在存放庫的根目錄建立 Directory.Packages.props 檔案，並將 MSBuild 屬性 ManagePackageVersionsCentrally 設定為 true。

接著，您會使用 <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 檔案。

這表示，如果您在存放庫中有多個 Directory.Packages.props 檔案，則會評估最接近您專案目錄的檔案。這可讓您在存放庫的各種層級上額外控制。

以下是範例，請考慮下列存放庫結構：

Repository
 |-- Directory.Packages.props
 |-- Solution1
     |-- Directory.Packages.props
     |-- Project1
 |-- Solution2
     |-- Project2

Project1 會評估 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 會評估 Directory.Packages.props 目錄中的 Repository\ 檔案。

注意： MSBuild 不會自動為您匯入每 Directory.Packages.props 一個，只有最接近專案的第一個。如果您有多個 Directory.Packages.props，則必須手動匯入父系一個，而根 Directory.Packages.props 目錄則不會。

開始使用

若要完整上線您的存放庫，請考慮採取下列步驟：

在名為 Directory.Packages.props 的存放庫根目錄建立新檔案，以宣告您集中定義的套件版本，並將 MSBuild 屬性 ManagePackageVersionsCentrally 設定為 true。
在中Directory.Packages.props宣告<PackageVersion />專案。
在項目檔中宣告 <PackageReference /> 不含 Version 屬性的專案。

如需中央套件管理外觀的概念，請參閱我們的範例存放庫。

可轉移釘選

即使沒有明確的最上層 <PackageReference /> ，您也可以加入加入稱為可轉移釘選的功能，自動覆寫可轉移套件版本。這會在必要時以隱含方式將可轉移的相依性提升至最上層相依性。

您可以將項目或Directory.Packages.props匯Directory.Build.props入檔案中的 MSBuild 屬性CentralPackageTransitivePinningEnabled設定為 true ，以啟用此功能：

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

覆寫套件版本

您可以使用專案上的 <PackageReference /> 屬性來覆寫個別套件版本VersionOverride。這會以集中方式覆寫任何 <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>

您可以將項目或Directory.Packages.props匯Directory.Build.props入檔案中的 MSBuild 屬性CentralPackageVersionOverrideEnabled設定為 false ，以停用此功能：

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

停用此功能時，在任何<PackageReference />專案上指定 VersionOverride 會導致還原時間發生錯誤，指出功能已停用。

停用中央套件管理

如果您想要停用任何特定專案的中央套件管理，您可以將 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.

注意

集中套件管理正在積極開發中。感謝您試用，並在 NuGet/Home 提供任何意見反應。

中央套件管理 （CPM）