總體移轉策略

  • 發行項

簡介

Windows 應用程式 SDK 提供一組廣泛的 Windows API，這些 API 的實作與作業系統分離，且會經由 NuGet 套件發布給開發人員。 如果您是使用通用 Windows 平台 (UWP) 應用程式的開發人員，建議您將應用程式轉移至 Windows 應用程式 SDK，藉此讓現有技能組合和原始程式碼充分發揮。

藉由 Windows 應用程式 SDK，您可以將最新的執行階段、語言和平台功能都納入應用程式。 每個應用程式都不同，而您的需求和偏好也不同，因此處理應用程式原始程式碼移轉程序的方式也有許多種。 不過，高階的作法及各種功能區域所需的程式碼變更都類似。 因此，在本主題中，我們將會檢視應用程式移轉策略的執行方法，以及特定功能區域的詳細資訊 (和限制)。 另請參閱可支援從 UWP 移植到 WinUI 3 的功能。

大部分 Windows 執行階段 (WinRT) API 都可供 Windows 應用程式 SDK 的應用程式使用。 但有些 API 在桌面應用程式中不受支援，或者有限制。

  • API 如果與 UI 功能有相依性，就是為了專供 UWP 應用程式使用而設計的。
  • 需要套件身分識別的 API。 只有使用 MSIX 的封裝桌面應用程式才可支援這些 API。

我們將針對這些 API，示範可用的替代方案。 這些替代方案多數可在 WinUI 3 或 Windows 應用程式 SDK 中提供的 WinRT COM 介面取得。

舉例來說，在某些 UI 案例，您必須追蹤主要視窗物件，並使用各種以 HWND 為基礎的 API 和互通模式，例如 IInitializeWithWindow::Initialize。

注意

另請參閱桌面應用程式不支援的 Windows 執行階段 API。 Windows 應用程式 SDK 的應用程式是一種桌面應用程式。 其他類型的桌面應用程式還包括 .NET 桌面應用程式，以及 C/C++ Win32 桌面應用程式。 如果有開發人員想以聯集的方式來移轉其他桌面應用程式類型，包括 於) Windows 應用程式 SDK 的應用程式，那就是該類主題的受眾。

我們很樂意聽到您對本移動指南以及您自己的移動體驗的回饋。 歡迎使用本頁面右下方的意見反應區，如下所示：

  • 如對 Windows 應用程式 SDK 有問題和意見，或想開啟討論，請使用 [本產品] 按鈕。 您也可以在 WindowsAppSDK GitHub 存放庫的 [討論] 索引標籤上發起討論。 您也可以透過這些管道，向我們告知您正在處理的問題、目前嘗試過的處理方法，以及適合您應用程式的理想解決方案是什麼。
  • 如要對本移轉指南的缺漏或錯誤資訊表達意見，請使用 [本頁面] 按鈕。

為何要移轉到 Windows 應用程式 SDK？

Windows 應用程式 SDK 的新平台功能和 Windows UI 3 程式庫 (WinUI 3) 為您提供強化應用程式的機會，是為了讓您取悅使用者而開發與設計。

此外，Windows 應用程式 SDK 可向下相容，支援的應用程式下至 Windows 10 版本 1809 (10.0；17763 版)，亦即 Windows 10 的 2018 年 10 月更新版。

轉移 Windows 應用程式 SDK 的價值主張有很多種。 以下是一些考量：

  • 最新的使用者介面 (UI) 平台和控制項，例如 WinUI 3 和 WebView2。
  • 桌面應用程式平台共用的單一 API 介面。
  • 更加頻繁的發布步調，且是與 Windows 分別發布。
  • 一致的 Windows 各版本體驗。
  • .NET 相容性。
  • 向下相容至 Windows 10 版本 1809。
  • 改良的執行階段環境。 請參閱 MSIX 容器。

如需更多資訊，請參閱 Windows 應用程式 SDK。

移轉程序概觀

注意

您可以將 UWP 版本的應用程式想像成您要移轉的來源解決方案/專案 (亦即移轉程序的來源)。 Windows 應用程式 SDK 版本則是目標解決方案 (亦即移轉程序的目標)。

安裝 Windows 應用程式 SDK VSIX

從 Windows 應用程式 SDK 的穩定發布通道下載 Windows 應用程式 SDK Visual Studio 擴充功能 (VSIX) 安裝程式，然後執行安裝。

建立新專案

在 Visual Studio 建立第一個 WinUI 3 專案。 舉例來說，您可以採用已封裝的空白應用程式 (桌面版 WinUI 3) 專案範本。 您可以選擇語言：C# 或 C++；平台：Windows 應用程式 SDK；專案類型：WinUI 或 Desktop，藉此在「建立新專案」對話方塊中找到該專案範本。

您會在「方案總管」看到兩個專案，一個適用於 (桌面)，另一個則是 (套件)。

優先移轉最不具相依性的程式碼

為了闡明上述建議，我們以 PhotoLab 案例研究為例。 移轉 PhotoLab 範例應用程式時，明顯可行的方法可能是先移轉 MainPage，因為它在應用程式中是既重要又顯眼的元件。 但如果這麼做，馬上就會發現 MainPage 與 DetailPage 檢視有相依性；而 DetailPage 與 Photo 模型則有相依性。 如果要按照此路徑，可能會不斷發生自我中斷 (不斷在各個新發現的相依性之間切換處理)。 在我們將每個相依性都追查出來，並且一口氣移植整個專案之前，顯然不太可能會有清晰的架構。

另一方面，如果我們從沒有任何相依性的專案元件開始操作，並繼而往外擴展 (從最不相依擴展為最有相依性的元件)，我們就能一次專注處理一個元件。 我們也能在移轉每個元件後建構出清晰的架構，並因此確認移轉程序保持在正軌上。

因此在移轉自己的應用程式時，建議您優先移轉最不具相依性的程式碼。

複製檔案好呢，還是複製檔案內容好呢？

移轉的時候，當然還要複製整個資產檔案 (而非資產檔案內容)。 但是原始程式碼檔案呢？ 我們再次舉 PhotoLab 案例研究和 Photo Editor 案例研究的 MainPage 類別為例。

C#： 在 C# 版本 (PhotoLab)，MainPage 是以原始程式碼檔案 MainPage.xaml 和 MainPage.xaml.cs 組成。

C++/WinRT。 在 C++/WinRT 版本 (Photo Editor)，MainPage 則是以原始程式碼檔案 MainPage.xaml、MainPage.idl、MainPage.h 和 MainPage.cpp 組成。

因此您有兩種選項可選：

  • (建議選項) 您可以複製整個檔案本身 (透過檔案總管)，然後將複製檔新增到目標專案。 不過 App.xaml 和 App.xaml.cs 是這種建議作法的例外，因為這些檔案已經存在於目標專案，且內含 Windows 應用程式 SDK 專用的原始程式碼。 處理這類檔案，您必須合併已經存在的原始程式碼和來源專案的原始程式碼。
  • 您也可以使用 Visual Studio 在目標專案建立新的頁面檔案 (例如 MainPage.xaml 和 MainPage.xaml.cs)，然後從來源專案將整個原始程式碼檔案的內容複製到目標專案。 如果是 C++/WinRT 專案，這個選項還要加入更多步驟。

另請參閱 MainPage 和 MainWindow 一節。

資料夾和檔案名稱的差別 (C++/WinRT)

在 C++/WinRT UWP 專案，XAML 檢視的程式碼後置檔案是以 MainPage.h 和 MainPage.cpp 的格式命名。 但在 C++/WinRT Windows 應用程式 SDK，您必須將它們重新命名為 MainPage.xaml.h 和 MainPage.xaml.cpp。

在 C++/WinRT UWP 專案中以 MyPage.xaml.cpp 移轉名為 MyPage 的假定 XAML 檢視 (具有模型、檢視和檢視模型) 時，您必須在 #include "DetailPage.xaml.h" 後方立即加上 #include "MyPage.g.cpp"。 以 MyModel.cpp 移轉名為 MyModel 的假定模型時，則要在 #include "MyModel.h” 後方立即加上 #include "MyModel.g.cpp"。 請參閱移轉 DetailPage 原始程式碼的範例。

如果變更移轉專案的名稱

移轉時，您可能會選擇為目標專案命名為與來源專案不同的名稱。 這麼做會影響來源專案內的預設命名空間。 將來源專案的原始程式碼整個複製到目標專案時，您可能需要變更原始程式碼提及的命名空間名稱。

舉例而言，變更專案名稱 (並因而變更預設命名空間名稱) 是我們在案例研究 UWP PhotoLab 範例應用程式 (C#) 的 Windows 應用程式 SDK 移轉中會採取的動作。 在該案例研究中，我們並不從來源專案將整個檔案內容複製到目標專案，而是使用檔案總管複製整個檔案。 來源專案/命名空間名稱是 PhotoLab，而目標專案/命名空間名稱是 PhotoLabWinUI3。 所以我們要在已整個複製的任何原始程式碼檔案內容中搜尋 PhotoLab，然後將它變更為 PhotoLabWinUI3。

在該案例研究中，我們對 App.xaml、App.xaml.cs、MainPage.xaml、MainPage.xaml.cs、DetailPage.xaml、DetailPage.xaml.cs、ImageFileInfo.cs 和 LoadedImageBrush.cs 進行了變更。

安裝在來源專案中已安裝的相同 NuGet 套件

移轉程序中有一項作業是識別與來源專案相依的任何 NuGet 套件， 然後在目標專案安裝相同的 NuGet 套件。

舉例來說，在案例研究 UWP PhotoLab 範例應用程式 (C#) 的 Windows 應用程式 SDK 移轉，來源專案包含 Microsoft.Graphics.Win2D NuGet 套件的參照。 因此，在該案例研究中，我們要將相同 NuGet 套件的參照加到目標專案。