從 package.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 套件 ，並選擇每個目標架構、組態、平臺或其他樞紐的套件參考。

限制

  • 在 Visual Studio 2015 與更早版本中，無法使用 NuGet PackageReference。 已移轉專案只能在 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 套件的 [頂層] 選項，將套件分類為頂層可轉移的相依性。 針對包含無法轉移的資產 (在 build、buildCrossTargeting、contentFiles 或 analyzers 資料夾中) 的套件，以及標示為開發相依性 (developmentDependency = "true") 的套件，系統會自動為它們設定此選項。

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

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

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

  8. 驗證解決方案可建置並執行。 如果您遇到問題，請在 GitHub 上提出問題 \(英文\)。

如何復原為 packages.config

  1. 關閉已移轉專案。

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

  3. 開啟專案。

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

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

    update-package -reinstall

移轉之後建立套件

完成移轉之後，建議您新增 nuget.build.tasks.pack \(英文\) nuget 套件的參考，然後使用 msbuild -t:pack 來建立套件。 雖然在某些情況下，您可以使用 dotnet.exe pack 而不是 msbuild -t:pack，但不建議這麼做。

套件相容性問題

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

當套件是在移轉之後安裝時，系統會忽略 "install. ps1" 指令碼

  • 描述：在安裝或卸載套件時，不會執行 PackageReference、install.ps1 和 uninstall.ps1 PowerShell 腳本。

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

當套件是在移轉之後安裝時，會無法使用「內容」資產

  • 描述:P ackageReference 不支援套件 content 資料夾中的資產，而且會忽略。 PackageReference 新增對 contentFiles 的支援，以獲得更好的可轉移支援和共用內容。

  • 潛在影響：中的 content 資產不會複製到專案和專案程序代碼中，而專案程式代碼取決於這些資產的存在需要重構。

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

  • 描述：在安裝或卸載套件時，PackageReference 不支援 XDT 轉換， .xdt 而且會忽略檔案。

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

當套件是在遷移之後安裝時，系統會忽略 lib 根目錄中的組件

  • 描述：使用 PackageReference 時，會忽略資料夾根 lib 目錄中沒有目標 Framework 特定子資料夾的元件。 NuGet 會尋找與專案目標 Framework 對應之目標 Framework Moniker (TFM) 相符的子資料夾，並將相符的元件安裝到專案中。

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

發現問題嗎？ 請回報！

如果您遇到移轉體驗的問題，請在 NuGet GitHub 存放庫中提出問題 \(英文\)。