.NET平台系列24：從.NET Framework遷移到.NET Core/.NET5的技術指南

• 2021 年 6 月 14 日
• 筆記
• .NET Framework, .NET：.NET Core, .NET：.NET5, .NET：.NET6

　　本文講解了在將程式碼從 .NET Framework 移植到 .NET（舊稱為 .NET Core）時應考慮的事項。 對於許多項目，從 .NET Framework 移植到 .NET 是相對簡單的。 項目的複雜性決定了在項目文件的初始遷移之後要做多少工作。

　　應用模型在 .NET 中可用的項目（如庫、控制台應用和桌面應用）通常不需要太大的更改。 需要使用新應用模型的項目（如從 ASP.NET 遷移到 ASP.NET Core）需要的工作要多一點。 舊應用模型中的很多模式都有可以在轉換過程中使用的等效項。

.NET Framework 中有一些技術在 .NET 中是不存在：

• 應用程式域

  不支援創建額外應用程式域。 對於程式碼隔離，將流程或容器用作備用。

• 遠程處理

  遠程處理用於跨不再受支援的應用程式域進行通訊。 對於跨進程通訊，可將進程間通訊 (IPC) 機制視為遠程處理的備用方案，如 System.IO.Pipes 類或 MemoryMappedFile 類。

• 程式碼訪問安全性 (CAS)

  CAS 是受 .NET Framework 支援、但在 .NET Framework 4.0 中已停用的沙盒技術。 它已被 Security Transparency 取代，並且在 .NET 中不受支援。 請改用作業系統提供的安全邊界，如虛擬化、容器或用戶帳戶。

• 安全透明度

  與 CAS 類似，這種沙盒技術不再被推薦用於 .NET Framework 應用程式，而且在 .NET 中也不受支援。 請改用作業系統提供的安全邊界，如虛擬化、容器或用戶帳戶。

• System.EnterpriseServices

  .NET 不支援 System.EnterpriseServices (COM+)。

• Windows Workflow Foundation (WF) 和 Windows Communication Foundation (WCF)

  .NET 5 及更高版本（包括 .NET Core）不支援 WF 和 WCF。 有關替代方法，請參閱 CoreWF 和 CoreWCF。

若要詳細了解這些不受支援的技術，請參閱 .NET Framework 技術在 .NET Core 和 .NET 5 及更高版本上不可用。

　　許多為 .NET Framework 創建的應用程式都使用桌面技術，如 Windows 窗體或 Windows Presentation Foundation (WPF)。 雖然 Windows 窗體和 WPF 均已移植到 .NET 中，但這些仍是僅適用於 Windows 的技術。

在遷移 Windows 窗體或 WPF 應用程式之前，請先考慮以下依賴項：

1. 適用於 .NET 的項目文件使用與 .NET Framework 不同的格式。
2. 你的項目可能會使用在 .NET 中不可用的 API。
3. 第三方控制項和庫可能還沒有移植到 .NET 中，仍只對 .NET Framework 可用。
4. 你的項目使用在 .NET 中不再可用的技術。

.NET 使用 Windows 窗體和 WPF 的開放源程式碼版本，並對 .NET Framework 進行了增強。

有關將桌面應用程式遷移到 .NET 5 的教程，請參閱以下文章之一：

• 將 .NET Framework WPF 應用遷移到 .NET
• 將 .NET Framework Windows 窗體應用遷移到 .NET

　　應用程式仍可以在 .NET 支援的平台上對本機庫進行平台調用。 這項技術並不僅限於 Windows。 但是，如果你引用的庫是特定於 Windows 的（如 user32.dll 或 kernal32.dll），那麼程式碼只能在 Windows 上正常運行。 對於想要在其上運行應用的每個平台，你都必須查找特定於平台的版本，或者讓你的程式碼足夠通用以在所有平台上運行。

　　當將應用程式從 .NET Framework 移植到 .NET 時，應用程式可能使用了隨 .NET Framework 一起分發的庫。 許多在 .NET Framework 中可用的 API 都沒有移植到 .NET 中，因為它們依賴特定於 Windows 的技術，如 Windows Registry 或 GDI+ 繪圖模型。

　　Windows Compatibility Pack 為 .NET 提供了大部分的 .NET Framework API 面，並通過 Microsoft.Windows.Compatibility NuGet 包提供。

　　有關詳細資訊，請參閱使用 Windows Compatibility Pack 將程式碼移植到 .NET 中。

　　.NET Framework 兼容性模式是在 .NET Standard 2.0 中引入的。 使用此兼容性模式，.NET Standard 和 .NET 5 及更高版本（以及 .NET Core 3.1）項目可以在僅適用於 Windows 的情況下引用 .NET Framework 庫。 引用 .NET Framework 庫不適用於所有項目（如庫使用 Windows Presentation Foundation (WPF) API 時），但它的開啟了很多移植方案。 有關詳細資訊，請參閱分析依賴項以將程式碼從 .NET Framework 移植到 .NET 中。

　　.NET（舊稱為 .NET Core）是為跨平台而設計的。 如果程式碼不依賴特定於 Windows 的技術，那麼它可以在 macOS、Linux 和 Android 等其他平台上運行。 這包括如下項目類型：

• 庫
• 基於控制台的工具
• 自動化
• ASP.NET 站點

　　.NET Framework 是僅適用於 Windows 的組件。 當程式碼使用特定於 Windows 的技術或 API（如 Windows 窗體和 Windows Presentation Foundation (WPF)）時，程式碼仍可以在 .NET 上運行，但不能在其他作業系統上運行。

　　庫或基於控制台的應用程式不需要太多更改就可以跨平台使用。 當移植到 .NET 時，可能需要考慮這一點，並在其他平台上測試應用程式。

　　.NET Standard 是針對多個 .NET 實現推出的一套正式的 .NET API 規範。 推出 .NET Standard 的背後動機是要提高 .NET 生態系統中的一致性。 自 .NET 5 起，採用了一種不同的方法來建立一致性；使用這種新方法，在很多情況下，都不需要使用 .NET Standard。 有關詳細資訊，請參閱 .NET 5 和 .NET Standard。

　　.NET Standard 2.0 是支援 .NET Framework 的最後一個版本。

　　可以使用不同的工具來幫助自動執行遷移的某些方面，而不是將應用程式從 .NET Framework 手動移植到 .NET 中。 移植複雜的項目本身就是一個複雜的過程。 這些工具可能在此過程中有所幫助。

　　即使你使用工具來幫助移植應用程式，也應查閱本文中的「移植時的注意事項」部分。

• .NET 升級助手

　　.NET 升級助手是一款可以在不同類型的 .NET Framework 應用上運行的命令行工具。 它旨在幫助將 .NET Framework 應用升級到 .NET 5。 在運行此工具後，大多數情況下，應用將需要更多操作才能完成遷移。 此工具會安裝可以幫助完成遷移的分析器。 此工具適用於以下類型的 .NET Framework 應用程式：

• Windows 窗體
• WPF
• ASP.NET MVC
• 控制台
• 類庫

　　此工具使用本文中列出的其他工具，並指導遷移過程。 若要詳細了解此工具，請參閱 .NET 升級助手概述。

• try-convert

　　try-convert 工具是一款 .NET 全局工具，可用於將項目或整個解決方案轉換為 .NET SDK，包括將桌面應用遷移到 .NET 5。 但是，如果你的項目有複雜的生成進程（如自定義任務、目標或導入），則不建議使用此工具。

　　有關詳細資訊，請參閱 try-convert GitHub 存儲庫。

• .NET 可移植性分析器

.NET 可移植性分析器是一種工具，可分析程式集並為應用程式或庫提供有關缺失的 .NET API 的詳細報告，以便在指定的目標 .NET 平台上實現可移植性。

若要使用 Visual Studio 中的 .NET 可移植性分析器，請從市場中安裝此擴展。

有關詳細資訊，請參閱 .NET 可移植性分析器。

• 平台兼容性分析器

　　平台兼容性分析器分析你是否在使用將會在運行時拋出 PlatformNotSupportedException 的 API。 儘管這並不常見，但如果從 .NET Framework 4.7.2 或更高版本進行移動，最好進行檢查。 若要詳細了解會在 .NET 上拋出異常的 API，請參閱始終在 .NET Core 上拋出異常的 API。

　　有關詳細資訊，請參閱平台兼容性分析器。

將應用程式移植到 .NET 時，請按順序考慮以下建議。

✔️ 考慮使用 .NET 升級助手來遷移項目。 儘管此工具處於預覽階段，但它自動執行本文中詳細介紹的大部分手動步驟，並為你繼續遷移路徑提供了一個很好的起點。

✔️ 考慮先檢查依賴項。 依賴項必須定目標到 .NET 5、.NET Standard 或 .NET Core。

✔️ 務必從 NuGet packages.config 文件遷移到項目文件中的 PackageReference 設置。 使用 Visual Studio 轉換 package.config 文件。

✔️ 考慮升級到最新的項目文件格式，即使你還不能移植應用，也不例外。 .NET Framework 項目使用過時的項目格式。 儘管最新的項目格式（稱為「SDK 樣式項目」）是為 .NET Core 及更高版本創建的，它們也適用於 .NET Framework。 擁有最新格式的項目文件可以為將來移植應用打下良好的基礎。

✔️ 務必將 .NET Framework 項目重新定目標到 .NET Framework 4.7.2 及更高版本。 在 .NET Standard 不支援現有 API 情況下，這可確保最新備用 API 的可用性。

✔️ 考慮定目標到 .NET 5（而不是 .NET Core 3.1）。 雖然 .NET Core 3.1 是長期支援 (LTS) 版本，但 .NET 5 是最新的，並且 .NET 6 也將在發布後成為 LTS。

✔️ 務必為 Windows 窗體和 WPF 項目定目標到 .NET 5。 .NET 5 包含許多對桌面應用的改進。

✔️ 若要遷移也可以用於 .NET Framework 項目的庫，請考慮定目標到 .NET Standard 2.0。 也可以為庫設定多個目標，同時定目標到 .NET Framework 和 .NET Standard。

✔️ 如果遷移之後出現缺少 API 的錯誤，請務必添加對 Microsoft.Windows.Compatibility NuGet 包的引用。 大部分 .NET Framework API 面是通過 NuGet 包提供給 .NET 的。

參考文獻：

• //docs.microsoft.com/en-us/dotnet/core/porting/

• .NET 升級助手概述
• ASP.NET 到 ASP.NET Core 遷移
• 將 .NET Framework WPF 應用遷移到 .NET
• 將 .NET Framework Windows 窗體應用遷移到 .NET
• 將 .NET Framework 庫移植到 .NET 中
• 適用於伺服器應用的 .NET 5 與 .NET Framework