共用方式為

從 packages.config 移轉至 PackageReference

Visual Studio 2017 15.7 版和更新版本支援將專案從 packages.config 管理格式移轉至 PackageReference 格式。

使用 PackageReference 的好處

  • 在單一位置管理所有專案相依性：就像專案對專案參考和元件參考一樣，NuGet 套件參考 （使用 PackageReference 節點） 會直接在專案檔案內管理，而不是使用個別的 packages.config 檔案。
  • 最上層相依性的整潔檢視：與 packages.config不同，PackageReference 只會列出您直接安裝在專案中的 NuGet 套件。 因此，NuGet 套件管理員 UI 和專案檔案不會因下層相依性而雜亂無章。
  • 效能改善：使用 PackageReference 時，套件會維護在 global-packages 資料夾中 （如 管理全域套件和快取資料夾 中所述，而不是在解決方案內的 packages 資料夾中。 因此，PackageReference 執行速度更快，消耗的磁碟空間更少。
  • 精細控制相依性和內容流程：使用 MSBuild 的現有功能可讓您有條件地參考 NuGet 套件，並根據每個目標架構、設定、平臺或其他樞紐選擇套件參考。

局限性

  • NuGet PackageReference 無法在 Visual Studio 2015 和更早版本中使用。 移轉的專案只能在 Visual Studio 2017 和更新版本中開啟。
  • 移轉目前不適用於 C++ 和 ASP.NET 專案。
  • 某些套件可能與 PackageReference 不完全相容。 如需詳細資訊，請參閱 套件相容性問題。

此外，與 packages.config相比，PackageReferences 的工作方式也存在一些差異。例如，PackageReference 不支援 升級版本的條件約束 ，但 PackageReference 新增了 浮動版本的支援。

已知問題

  1. 右鍵選單中無法使用Migrate packages.config to PackageReference...選項

問題

第一次開啟專案時，NuGet 可能尚未初始化，直到執行 NuGet 作業為止。 這會導致移轉選項不會顯示在 packages.config 或 References 的右鍵操作功能表中。

因應措施

執行下列任一 NuGet 動作：

  • 開啟套件管理員 UI — 在 References 上以滑鼠右鍵按一下，並選取 Manage NuGet Packages...
  • 開啟套件管理員主控台，從Tools > NuGet Package Manager中選取Package Manager Console
  • 執行 NuGet 還原- 以滑鼠右鍵按一下 [方案總管] 中的解決方案節點，然後選取 Restore NuGet Packages
  • 建置此專案將同時觸發 NuGet 還原

您現在應該能夠看到遷移選項。 請注意，不支援此選項，而且不會針對 ASP.NET 和 C++ 專案類型顯示。

移轉步驟

備註

在移轉開始之前，Visual Studio 會建立專案的備份，讓您視需要復 原至 packages.config 。

  1. 使用 packages.config 開啟包含專案的解決方案。

  2. 在 [方案總管] 中，以滑鼠右鍵按一下 [參考 ] 節點或 packages.config 檔案，然後選取 [將 packages.config 移轉至 PackageReference...]。

  3. 移轉器會分析專案的 NuGet 套件參考，並嘗試將它們分類為 最上層相依性 （您直接安裝的 NuGet 套件） 和 可轉移相依性 （安裝為最上層套件相依性的套件）。

    備註

    PackageReference 支援可轉移套件還原，並動態解析相依性，這表示不需要明確安裝可轉移相依性。

  4. （選用）您可以選擇將分類為可轉移相依性的 NuGet 套件視為最上層相依性，方法是選取套件的 最上層 選項。 此選項會自動針對包含非可轉移流動資產的套件（ 、 、 buildbuildCrossTargeting或contentFiles資料夾analyzers中的資產）以及標示為開發相依性（）developmentDependency = "true"的套件設定。

  5. 檢閱任何 套件相容性問題。

  6. 選取 [ 確定 ] 以開始移轉。

  7. 在移轉結束時，Visual Studio 會提供一份報告，其中包含備份路徑、已安裝套件清單 （最上層相依性）、參考為可轉移相依性的套件清單，以及移轉開始時識別的相容性問題清單。 報告會儲存至備份資料夾。

  8. 驗證解決方案是否建置並執行。 如果您遇到問題，請 在 GitHub 上提出問題。

如何回退至 packages.config

  1. 關閉移轉的專案。

  2. 將專案檔案和 packages.config 從備份（通常位於 <solution_root>\MigrationBackup\<unique_guid>\<project_name>\）複製到專案資料夾。 如果obj資料夾存在於專案根目錄中，請刪除該資料夾。

  3. 開啟專案。

  4. 使用 [工具 > ] NuGet 套件管理員 > [套件管理員主控台 ] 功能表命令開啟套件管理員主控台。

  5. 在主控台中執行下列命令：

    update-package -reinstall

移轉後建立套件

移轉完成後，建議您將套件中繼資料從 .nuspec 檔案複製到 MSBuild 屬性，然後您可以使用 msbuild -t:pack 來建立套件。 如果您使用 Visual Studio 2022 或更早版本，您也必須安裝 NuGet.Build.Tasks.Pack 套件。 從 Visual Studio 2026 開始，套件內建於 MSBuild 中。

套件相容性問題

packages.config 中支援的某些層面不受 PackageReference 支援。 遷移器會分析並偵測此類問題。 任何具有下列一或多個問題的套件在移轉之後可能無法如預期般運作。

移轉後安裝套件時，會忽略「install.ps1」腳本

  • 描述：使用 PackageReference，安裝或解除安裝套件時不會執行 install.ps1 和 uninstall.ps1 PowerShell 腳本。

  • 潛在影響：依賴這些指令碼來設定目的地專案中某些行為的套件可能無法如預期般運作。

移轉後安裝套件時，「content」資產無法使用

  • 說明：PackageReference不支援套件資料夾 content 中的資產，且會忽略。 PackageReference 新增支援 contentFiles ，以獲得更好的可轉移支援和共用內容。

  • 潛在影響：在content中的資產不會複製到專案中，依賴這些資產存在的專案程式碼需要重構。

升級後安裝套件時，不會套用XDT轉換

  • 說明： PackageReference 不支援 XDT 轉換，且 .xdt 安裝或解除安裝套件時會忽略檔案。

  • 潛在影響：XDT 轉換不會套用至任何專案 XML 檔案，最常見的是 web.config.install.xdtweb.config.uninstall.xdt和 ，這表示在安裝或解除安裝套件時不會更新專案的 web.config 檔案。

移轉之後安裝套件時，會忽略 lib 根目錄中的元件

  • 描述：使用 PackageReference，會忽略位於資料夾根 lib 目錄中而沒有目標架構特定子資料夾的元件。 NuGet 會尋找與專案目標框架名稱 (TFM) 相符的子資料夾，並將相符的程序集安裝到專案中。

  • 潛在影響：沒有符合對應專案目標架構的目標架構名稱（TFM）的子資料夾的套件，在轉換之後可能無法如預期般運作，或在移轉期間安裝失敗。

發現問題嗎？ 舉報吧！

如果您在移轉體驗中遇到問題，請 在 NuGet GitHub 存放庫上提出問題。

  • Last updated on