Xamarin.Forms UWP 專案移轉

發行項
05/14/2024

若要將 Xamarin.Forms UWP 專案更新為 WinUI 3 專案，您應該：

將您的專案檔更新為 SDK 樣式。
更新命名空間
解決任何 API 變更
以 .NET 8 版本更新或取代不相容的相依性。
編譯及測試您的應用程式。

更新為 SDK 樣式的專案檔

您現有的 Xamarin.Forms UWP 專案可以更新為 SDK 樣式的 WinUI 3 專案。 .NET MAUI WinUI 3 應用程式的 SDK 樣式專案類似于下列範例：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

重要

目標 Framework Moniker （TFM）是表示專案使用 .NET 的專案，在此案例中為 .NET 8。如需 SDK 樣式專案中目標架構的相關資訊，請參閱 SDK 樣式專案中的目標架構。

您必須將新增 <UseMaui>true</UseMaui> 至專案檔，才能啟用 .NET MAUI 支援。此外，請確定您已將新增 <EnableDefaultMauiItems>false</EnableDefaultMauiItems> 至專案檔。這將會停止您收到已定義方法的 InitializeComponent 建置錯誤。

MSBuild 屬性的變更

升級專案時，建議您從專案檔中移除下列 UWP MSBuild 屬性：

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

您也必須確定目標專案中的平臺架構是以下列 .NET 執行時間識別碼指定：

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

如需執行時間識別碼的詳細資訊，請參閱 .NET RID 目錄。

命名空間變更

UWP 與 WinUI 3 之間的命名空間名稱有差異。在許多情況下，變更命名空間名稱一樣簡單，然後您的程式碼就會進行編譯。例如，您必須將 Windows.UI.Xaml 命名空間取代為 Microsoft.UI.Xaml 命名空間。同樣地，您必須將命名空間取代 Windows.UI.Xaml.Controls 為 Microsoft.UI.Xaml.Controls 命名空間。

其他時候，對應需要多一點工作，而且在極少數的情況下，需要變更方法。如需詳細資訊，請參閱將 UWP API 和程式庫對應至Windows 應用程式 SDK 。

API 變更

您必須解決可能會影響應用程式的任何 API 變更。例如，某些類型、方法和屬性可能已重新命名、已被取代或移除。如需將 UWP 專案升級至 WinUI 3 時所支援專案的資訊，請參閱從 UWP 移轉至 WinUI 3 時支援的專案。如需將 UWP 功能和 API 對應至 WinUI 3 的相關資訊，請參閱將 UWP 功能對應至Windows 應用程式 SDK ，以及將 UWP API 和程式庫對應至Windows 應用程式 SDK 。

您可以在專案檔中設定 $(SupportedOSPlatformVersion) 屬性，讓專案與舊版 OS 相容：

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

屬性 $(SupportedOSPlatformVersion) 表示執行應用程式或程式庫所需的最低 OS 版本。如果您未在專案中明確指定此最低執行時間 OS 版本，它會預設為目標 Framework Moniker （TFM）的平臺版本。

如果您的專案只以 Windows 為目標，就足以省略平臺檢查條件，並直接設定 $(SupportedOSPlatformVersion) 屬性：

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

如需屬性的詳細資訊 $(SupportedOSPlatformVersion) ，請參閱支援舊版作業系統。

若要讓應用程式在舊版 OS 上正確執行，它無法呼叫該作業系統版本上不存在的 API。不過，您可以新增對較新 API 呼叫的防護，因此只有在支援這些 API 的 OS 版本上執行時，才會呼叫它們。這可以使用方法達成 IsWindowsVersionAtLeast ：

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

移除檔案

下列檔案存在於 Xamarin.Forms UWP 專案中，不存在於 WinUI 3 專案中：

MainPage.xaml 和 MainPage.xaml.cs
AssemblyInfo.cs
Default.rd.xml

因此，如果您的 WinUI 3 專案中有這些檔案，您應該移除這些檔案。這些檔案中包含的任何必要商務邏輯都應該移至其他地方。

Package.appxmanifest 的變更

您必須對已移轉專案的 Package.appxmanifest 檔案進行下列變更：

將應用程式進入點設定為 $targetentrypoint$ 。如需詳細資訊，請參閱目標進入點。
runFullTrust新增功能。如需詳細資訊，請參閱執行完全信任功能。
Windows.Universal新增和 Windows.Desktop 目標裝置系列。如需詳細資訊，請參閱通用目標裝置系列和桌面目標裝置系列。

進行這些變更會修正 Windows 上應用程式的常見部署錯誤。

如需相容 Package.appxmanifest 檔案的範例，請參閱 Package.appxmanifest 。

執行時間行為

在不同平臺上，.NET 5+ 中的方法有行為變更 String.IndexOf() 。如需詳細資訊，請參閱 .NET 全球化和 ICU 。

下一步

啟動您的應用程式

共用方式為