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>

重要

目标框架名字对象 (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) 属性，使项目与早期操作系统版本兼容：

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

$(SupportedOSPlatformVersion) 属性指示运行应用或库所需的最低 OS 版本。如果未在项目中显式指定此最低运行时 OS 版本，则默认为目标框架名字对象（TFM）中的平台版本。

如果项目仅面向 Windows，则省略平台检查条件并直接设置$(SupportedOSPlatformVersion)属性：

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

有关该 $(SupportedOSPlatformVersion) 属性的详细信息，请参阅支持较旧的 OS 版本。

若要使应用在较旧的 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。

后续步骤

启动应用

通过