共用方式為


中央套件管理 (CPM)

相依性管理是 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 目錄則不會。

開始使用

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

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

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

可轉移釘選

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

您可以將項目或Directory.Packages.propsDirectory.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.propsDirectory.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 提供任何意見反應