從 .NET Framework 移植到 .NET 的概觀

本文提供將程式碼從 .NET Framework 移植到 .NET (先前稱為 .NET Core) 時應考量項目的概觀。 從 .NET Framework 移植到 .NET，對許多專案來說都相當簡單。 專案的複雜度會決定在專案檔初始移轉之後，您將執行多少工作。

.NET 提供應用程式模型的專案，例如程式庫、主控台應用程式和桌面應用程式，通常需要稍微變更。 需要新應用程式模型的專案，例如從 ASP.NET 移至 ASP.NET Core，需要執行更多工作。 來自舊應用程式模型的許多模式都有可在轉換期間使用的對等項目。

Windows 桌面技術

為 .NET Framework 建立的許多應用程式都會使用桌面技術，例如 Windows Forms 或 Windows Presentation Foundation (WPF)。 Windows Forms 和 WPF 都已移植到 .NET，但這些仍是僅限 Windows 的技術。

移轉 Windows Forms 或 WPF 應用程式之前，請考量下列相依性：

• .NET 的專案檔會使用與 .NET Framework 不同的格式。
• 您的專案可能會使用 .NET 中無法使用的 API。
• 第三方控制項和程式庫可能尚未移植到 .NET，而且只能供 .NET Framework 使用。
• 您的專案會使用 .NET 中不再提供的技術。

.NET 使用 Windows Forms 和 WPF 的開放原始碼版本，並包含相較於 .NET Framework 的增強功能。

如需將桌面應用程式移轉至 .NET 的教學課程，請參閱下列其中一篇文章：

• 將 .NET Framework WPF 應用程式移轉至 .NET
• 將 .NET Framework Windows Forms 應用程式移轉至 .NET

Windows 特定 API

應用程式仍然可以在 .NET 支援的平台上對原生程式庫執行 P/Invoke。 此技術不限於 Windows。 不過，如果您要參考的程式庫是 Windows 特定的程式庫，例如 user32.dll 或 kernel32.dll，則程式碼只能在 Windows 上運作。 針對您想要讓應用程式執行的每個平台，您必須尋找平台特定版本，或讓您的程式碼夠通用而足以在所有平台上執行。

將應用程式從 .NET Framework 移植到 .NET 時，您的應用程式可能會使用 .NET Framework 提供的程式庫。 .NET Framework 中提供的許多 API 並未移植到 .NET，因為它們依賴 Windows 特定技術，例如 Windows 登錄或 GDI+ 繪圖模型。

Windows 相容性套件提供大部分的 .NET Framework API 介面給 .NET，並透過 Microsoft.Windows.Compatibility NuGet 封裝提供。

如需詳細資訊，請參閱使用 Windows 相容性套件將程式碼移植到 .NET。

.NET Framework 相容性模式

.NET Framework 相容性模式是在 .NET Standard 2.0 中引進。 此相容性模式可讓 .NET Standard 和 .NET 專案可參考 .NET Framework 程式庫，就如同是為專案的目標 Framework 編譯一般。 不過，某些 .NET 實作可能會支援比其他實作更大的 .NET Framework 區塊。 例如，.NET Core 3.0 會將 .NET Framework 相容性模式延伸至 Windows Forms 和 WPF。參考 .NET Framework 程式庫並無法適用所有專案，例如若程式庫使用 WPF API，但它確實會解除封鎖許多移植案例。 如需詳細資訊，請參閱分析相依性以將程式碼從 .NET Framework 移植到 .NET。

參考 .NET Framework 程式庫並無法適用所有情況，因為它取決於使用的 .NET Framework API，以及專案的目標架構是否支援這些 API。 此外，某些 .NET Framework API 只能在 Windows 上運作。 .NET Framework 相容性模式會解除封鎖許多移植案例，但您應該測試專案以確保它們也可以在執行階段運作。 如需詳細資訊，請參閱分析相依性以將程式碼從 .NET Framework 移植到 .NET。

SDK 樣式專案中的目標架構變更

如先前所述，.NET 的專案檔會使用與 .NET Framework 不同的格式，稱為 SDK 樣式專案格式。 即使您未從 .NET Framework 移至 .NET，您仍應將專案檔升級為最新格式。 在 SDK 樣式專案中，指定目標架構的方式不同。 在 .NET Framework 中，<TargetFrameworkVersion> 屬性會與指定 .NET Framework 版本的 Moniker 搭配使用。 例如，.NET Framework 4.7.2 看起來像下列程式碼片段：

<PropertyGroup>
  <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
</PropertyGroup>

SDK 樣式專案使用不同的屬性來識別目標架構，即 <TargetFramework> 屬性。 以 .NET Framework 為目標時，Moniker 的開頭會是 net，且結尾會是 .NET Framework 版本，且沒有任何句點。 例如，要以 .NET Framework 4.7.2 為目標的 Moniker 是 net472：

<PropertyGroup>
  <TargetFramework>net472</TargetFramework>
</PropertyGroup>

如需所有目標 Moniker 的清單，請參閱 SDK 樣式專案中的目標架構。

無法使用的技術

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

• 應用程式定義域

  不支援建立其他應用程式定義域。 若要隔離程式碼，請使用不同的程序或容器作為替代方案。

• 遠端

  遠端處理用於跨應用程式定義域進行通訊，這已不再支援。 如需跨處理序的簡易通訊，請考量使用處理序間通訊 (IPC) 機制來代替遠端處理，例如 System.IO.Pipes 類別或 MemoryMappedFile 類別。 如需更複雜的案例，請考量使用架構 StreamJsonRpc 或 ASP.NET Core (使用 gRPC 或 RESTful Web API 服務)。

  由於不支援遠端處理，因此在委派物件上呼叫 BeginInvoke() 和 EndInvoke() 將擲回 PlatformNotSupportedException。

• 程式碼存取安全性 (CAS)

  CAS 是 .NET Framework 支援的沙箱化技術，但在 .NET Framework 4.0 中被取代。 它已由安全性透明度取代，而且在 .NET 中不受支援。 請改用作業系統提供的安全性界限，例如虛擬化、容器或使用者帳戶。

• 安全性透明度

  與 CAS 類似，安全性透明度沙箱技術已不再建議針對 .NET Framework 應用程式使用，而且 .NET 中不支援。 請改用作業系統提供的安全性界限，例如虛擬化、容器或使用者帳戶。

• System.EnterpriseServices

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

• Windows Workflow Foundation (WF)

  .NET 中不支援 WF。 如需替代方案，請參閱 CoreWF。

如需這些不受支援技術的詳細資訊，請參閱 .NET 6+ 上無法使用的 .NET Framework 技術。

跨平台

.NET (先前稱為 .NET Core) 的設計是要跨平台運作。 如果您的程式碼不依賴 Windows 特定技術，則可以在其他平台 (例如 macOS、Linux 和 Android) 上執行。 這類程式碼包含專案類型，例如：

• 程式庫
• 以主控台為基礎的工具
• 自動化
• ASP.NET 網站

.NET Framework 是僅適用 Windows 的元件。 當您的程式碼使用 Windows 特定技術或 API，例如 Windows Forms 和 WPF 時，程式碼仍然可以在 .NET 上執行，但無法在其他作業系統上執行。

您的程式庫或主控台型應用程式可以跨平台使用，而不需要進行太多變更。 移植到 .NET 時，可能會想要將此納入考量，並在其他平台上測試您的應用程式。

.NET Standard 的未來

.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。 執行此工具之後，在大部分情況下，應用程式需要額外的工作才能完成移轉。 此工具包含可協助完成移轉的分析器安裝。 此工具適用下列類型的 .NET Framework 應用程式：

• Windows Forms
• WPF
• ASP.NET MVC
• 主控台
• 類別庫

此工具使用本文所列的其他工具，例如 try-convert，並且會引導移轉程序。 如需工具的詳細資訊，請參閱 .NET 升級小幫手概觀。

try-convert

try-convert 工具是一項 .NET 全域工具，可將專案或整個解決方案轉換成 .NET SDK，包括將桌面應用程式移至 .NET。 不過，如果您的專案具有複雜的建置程序，例如自訂工作、目標或匯入，則不建議使用此工具。

如需詳細資訊，請參閱 try-convert GitHub 存放庫。

.NET Portability Analyzer

.NET 可攜性分析器是一種工具，可分析組件並提供詳細的可攜性報告。 它會報告在您指定的目標 .NET 平台上，要移植的應用程式或程式庫中遺漏的 .NET API。

若要在 Visual Studio 中使用 .NET 可攜性分析器，請從市集安裝延伸模組。

如需詳細資訊，請參閱 .NET 可攜性分析器。

平台相容性分析器

平台相容性分析器會分析您是否使用將在執行階段擲回 PlatformNotSupportedException 的 API。 不過，若您是從 .NET Framework 4.7.2 或更新版本移轉，則不太可能找到這些 API 中的任一個，但能夠檢查也很好。 如需在 .NET 上擲回例外狀況的 API 的詳細資訊，請參閱一律在 .NET Core 上擲回例外狀況的 API。

如需詳細資訊，請參閱平台相容性分析器。

移植時的考量

將應用程式移植到 .NET 時，請依序考量下列建議：

✔️ 考量使用 .NET 升級小幫手來移轉您的專案。 雖然此工具處於預覽，但它會將本文中詳述的大部分手動步驟自動化，並提供繼續您的移轉路徑的絕佳起點。

✔️ 考量先檢查您的相依性。 您的相依性必須以 .NET、.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 6 為目標，這是長期支援 (LTS) 版本。

✔️ 針對 Windows Forms 和 WPF 專案，以 .NET 6+ 為目標。 .NET 6 包含桌面應用程式的許多改善。

✔️ 如果您要移轉可能也與 .NET Framework 專案搭配使用的程式庫，請考量以 .NET Standard 2.0 為目標。 您也可以讓程式庫有多重目標，同時以 .NET Framework 和 .NET Standard 為目標。

✔️ 如果移轉之後，您遇到遺漏 API 的錯誤，請新增 Microsoft.Windows.Compatibility NuGet 封裝 的參考。 大部分的 .NET Framework API 介面可透過 NuGet 封裝提供給 .NET 使用。

另請參閱

• .NET 升級小幫手的概觀
• ASP.NET 至 ASP.NET Core 移轉
• 將 .NET Framework WPF 應用程式移轉至 .NET
• 將 .NET Framework Windows Forms 應用程式移轉至 .NET
• 伺服器應用程式的 .NET 5 與 .NET Framework