透過 .NET 升級小幫手從 UWP 移轉到 Windows 應用程式 SDK

發行項
04/03/2024

.NET 升級小幫手 (請參閱 .NET 升級小幫手概覽) 是 Visual Studio 的擴充功能 (建議使用)，也是命令列工具，可協助移轉 C# 通用 Windows 平台 (UWP) 應用程式到使用 Windows 應用程式 SDK 的 Windows UI 程式庫 (WinUI) 3 應用程式。

我們對於 .NET 升級小幫手提供 UWP 支援的藍圖，包括繼續改良工具，以及支援新功能的移轉。如果您發現 .NET 升級小幫手的相關問題，請選取 [支援]>[傳送意見反應]>[回報問題]，藉此通報 Visual Studio 內的問題。

另請參閱升級小幫手 GitHub 存放庫。執行命令列工具的選項都收錄在該處。

安裝 .NET 升級小幫手

您可以將 .NET 升級小幫手安裝為 Visual Studio 擴充功能或 .NET 命令列工具。如需更多資訊，請參閱安裝 .NET 升級小幫手。

摘要

如果您要使用 .NET 升級小幫手來移轉 UWP 應用程式，以下為該工具在移轉程序中會執行的高階步驟和階段。

按需求選擇複製專案，然後移轉複本，原始專案則保留原樣。
按需求選擇原地 (使用相同資料夾和檔案，且不重新命名資料夾) 移轉專案，且不製作複本。
將 .NET Framework 專案格式的專案升級為最新的 .NET SDK 專案格式。
清除 NuGet 套件參照。除了應用程式參照的套件，packages.config 檔案也包含上述套件的相依性參照。舉例來說，套件 A 與套件 B 相依，如果對 A 新增參照，則 packages.config 檔案就會同時參照兩者。在新專案系統中，只需要對封裝 A 的參考。因此這個步驟會分析套件參照，然後移除不需要的參照。您的應用程式仍然會參考 .NET Framework 組件。有些組件可能會以 NuGet 套件的形式存在。因此這個步驟會分析這些組件，然後參照適用的 NuGet 套件。
將 .NET 6 和 Windows 應用程式 SDK 設為目標。
將 .NET Framework 的目標 Framework Moniker (TFM) (請參閱 SDK 式專案的目標 Framework) 變更為建議 SDK。例如： net6.0-windows 。
執行來源特定的程式碼變更，將 UWP 原始程式碼從 WinUI 2 移轉到 WinUI 3。
新增/更新任何範本、設定和程式碼檔案。例如新增必要的發布設定檔 App.xaml.cs、MainWindow.xaml.cs、MainWindow.xaml 等。
更新命名空間，並新增 MainPage 導覽。
嘗試偵測與修正 UWP 和 Windows 應用程式 SDK 之間不相同的 API，並使用工作清單的「待辦事項」來標記不再受支援的 API。

工具執行時的目標也包括以警告訊息的形式，在工具的輸出中提供移轉指引，以及以評論的形式，在專案的原始程式碼中提供工作清單的代辦事項 (例如 UWP 原始程式碼的完全自動移轉並不可行的情況)。標準的工作清單待辦事項包含了本移轉文件中的主題連結。身為開發人員，您當然可自己掌控移轉程序。

提示

若要查看工具產生的全部待辦事項，請檢視 Visual Studio 的工作清單。

注意

工具執行完畢後，您可以按照需求，選擇執行幾項後續步驟。您可以將程式碼從 App.xaml.old.cs 移轉到 App.xaml.cs；也可以從工具建立的備份中復原 AssemblyInfo.cs。

工具支援的功能

此版本的 .NET 升級小幫手仍在預覽中，且持續在接收頻繁的更新。此工具目前僅支援 C# 程式語言，不包含 C++。多數情況下，使用此版本時，您的專案需要您額外採取動作才能完成移轉。

工具的目標是移轉專案和程式碼，以便進行編譯。但有些功能需要您著手調查並加以修復 (透過工作清單的待辦事項)。如需詳細了解移轉前需要考量的事項，請參閱從 UWP 移植到 WinUI 3 時的支援功能。

由於 .NET 升級小幫手目前的版本有以下限制，您可以選擇先等候未來的版本再移轉應用程式：

不支援從 ApplicationView API 進行移轉。
不支援從 AppWindow 相關的 API 進行移轉。

可行情況下，工具會嘗試產生警告，目的是在您變更程式碼以前不讓它進行編譯。

不支援自訂檢視。舉例來說，自訂對話方塊如果會延伸 MessageDialog，並錯誤呼叫 API，您並不會收到警告或修正訊息。
不支援 Windows 執行階段元件。

多視窗應用程式可能無法正確移轉。
採取非標準檔案結構的專案 (例如並非位在根目錄資料夾的 App.xaml 和 App.xaml.cs) 可能無法正確移轉。

升級小幫手 GitHub 存放庫文件疑難排解提示和已知問題。如果您在使用工具時發現任何問題，請以 UWP 區域標籤標記，在同一個 GitHub 存放庫回報這些問題。感謝您的配合！

注意

如需移轉程序的相關指引，並了解 UWP 與 Windows 應用程式 SDK 功能和 API 之間的差異，請參閱從 UWP 移轉到 Windows 應用程式 SDK。

提示

您可以藉由發出指令 upgrade-assistant --version 來查看您使用的工具版本。

以 UWP PhotoLab 範本進行工具的測試驅動

我們來對 .NET 升級小幫手進行一次測試驅動吧。

我們要移轉的來源素材是 UWP PhotoLab 範本應用程式。 PhotoLab 是可用來檢視與編輯影像檔案的範本應用程式。它會展示 XAML 配置、資料繫結和 UI 自訂功能。

注意

您可以在 UWP PhotoLab 範本應用程式的 Windows 應用程式 SDK 移轉參閱 PhotoLab 的案例研究。

請從上方連結複製或下載 PhotoLab 範本原始程式碼。

提示

請注意，在我們使用工具自動進行應用程式移轉後，仍需要額外的手動作業才能完成移轉。

在 Visual Studio 開啟 PhotoLab。
安裝 .NET 升級小幫手擴充功能 (請參閱本主題上文的安裝 .NET 升級小幫手) 後，請在「解決方案總管」以右鍵按一下專案，然後按一下 [升級]。
選擇 [將專案升級為較新的 .NET 版本] 選項。
選擇 [原地升級專案] 選項。
選擇目標架構。
按一下 [升級所選項目]。
.NET 升級小幫手會開始執行，並在過程中透過 Visual Studio 輸出視窗列出資訊和狀態。

您可以監控程序列直到升級作業結束。

PhotoLab 範本應用程式的程式碼移轉作業包括：

變更「內容對話方塊」和「檔案儲存選擇器」API。
動畫套件的 XAML 更新。
顯示警告訊息，並以 DetailPage.xaml、DetailPage.xaml.cs 和 MainPage.xaml.cs 新增自訂返回按鈕的工作清單待辦事項。
實作返回按鈕功能，並對自訂 XAML 按鈕新增工作清單待辦事項。
系統會提供一份文件的連結，供您用於深入了解返回按鈕的實作。

產出的 .csproj 會有稍微不同的版本編號，但基本上會類似這樣 (為求簡潔而移除部分組件組態屬性群組)：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

您可以發現，專案至此已經參照 Windows 應用程式 SDK、WinUI 3 和 .NET 6。既然 PhotoLab 已經移轉，您就能善用 WinUI 3 應用程式具備的所有新功能，並透過平台擴充應用程式了。

此外，.NET 升級小幫手也會將分析工具加到專案，協助繼續執行升級程序。例如 Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers NuGet 套件。

後續手動移轉

到這個階段，您已可以開啟移轉後的 PhotoLab 解決方案或專案，並查看在原始程式碼中所作的變更。您還需要對專案執行幾項簡單操作，將整個程序完成，WinUI 3 版本才能如同 UWP 版本一樣組建、執行和運作。

請在 Visual Studio 查看「工作清單」 ([檢視]>[工作清單]) 了解您需要採取動作的待辦事項，以便完成移轉。

應用程式的 UWP (.NET Framework) 版本有可能包含您的專案實際不使用的程式庫參照。您必須分析每個參照，判斷是否必要。工具也可能將 NuGet 套件參照新增或升級到錯誤的版本。

升級小幫手不會編輯 Package.appxmanifest，但它其實需要編輯，才能讓應用程式發布：

在根目錄的 <Package> 元素新增以下命名空間：

xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

將 EntryPoint="appnamehere.App" 的 <Application> 元素編輯為 EntryPoint="$targetentrypoint$"
將任何指定的 Capability 替換為下者：

<rescap:Capability Name="runFullTrust" />

在 .csproj 檔案中，您可能需要編輯專案檔案來設定 <OutputType>WinExe</OutputType> 和 <UseMaui>False</UseMaui>。

為了使用多種 XAML 控制項，請確保您的 app.xaml 檔案包括 <XamlControlsResources>，例如以下範例：

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

疑難排解秘訣

使用 .NET 升級小幫手時，可能會發生數個已知問題。在某些情況下，這些問題來自於 .NET 升級小幫手內部使用的 try-convert 工具。

如需了解其他疑難排解提示和已知問題，請參閱升級小幫手 GitHub 存放庫。

Share via