手动将 Xamarin.Forms 应用升级到单一项目的 .NET MAUI 应用

若要将 Xamarin.Forms 应用迁移到单个项目 .NET 多平台应用 UI（.NET MAUI）应用，必须：

为了简化升级过程，应创建与应用 Xamarin.Forms 同名的新 .NET MAUI 应用，然后在代码、配置和资源中复制。 这是下面概述的方法。

更新应用Xamarin.Forms

在将您的 Xamarin.Forms 应用升级到 .NET MAUI 之前，您应先将您的 Xamarin.Forms 应用升级以使用 Xamarin.Forms 5，并确保它仍然能够正常运行。 此外，你应该将你的应用程序使用的依赖项更新到最新版本。

这有助于简化迁移过程的其余部分，因为它将最大程度地减少 .NET MAUI 与 .NET MAUI 之间的 Xamarin.Forms API 差异，并确保使用与 .NET 兼容的依赖项版本（如果存在）。

创建 .NET MAUI 应用

在 Visual Studio 中，使用与应用 Xamarin.Forms 相同的名称创建新的 .NET MAUI 应用：

打开项目文件将确认你有一个 .NET SDK 样式的项目。

将代码复制到 .NET MAUI 应用

库项目 Xamarin.Forms 中的所有跨平台代码都应复制到 .NET MAUI 应用项目中，置于名称完全相同的文件夹和文件中。

自定义呈现器可以在 .NET MAUI 应用中重复使用，也可以迁移到 .NET MAUI 处理程序。 有关详细信息，请参阅 .NET MAUI 中的重用自定义呈现器 并将 自定义呈现器迁移到 Xamarin.Forms .NET MAUI 处理程序。

效果可以在 .NET MAUI 应用中重复使用。 有关详细信息，请参阅 重复使用效果。

特定于平台的代码

.NET MAUI 应用项目包含 一个 Platform 文件夹，每个子文件夹表示 .NET MAUI 可以面向的平台：

每个平台的文件夹包含特定于平台的资源，以及在每个平台上启动应用的代码：

应将您的Xamarin.Forms头项目中的代码及其包含的文件夹复制到以下文件夹：

• 应将 Xamarin.Forms Android 头项目中的代码复制到 .NET MAUI 应用项目的 Platform\Android 文件夹中。 此外，将任何自定义代码从你的 Xamarin.FormsMainActivity 和 MainApplication 类复制到 .NET MAUI 应用项目中的相同类。

• 应将 Xamarin.Forms iOS 头项目中的代码复制到 .NET MAUI 应用项目的 Platforms\iOS 文件夹中。 此外，将类中的任何自定义代码 Xamarin.FormsAppDelegate 复制到 .NET MAUI 应用项目中的同一类。

  注释

  有关适用于 iOS 的 .NET 中的中断性变更的列表，请参阅 适用于 iOS 的 .NET 中的中断性变更。

• 应将 Xamarin.Forms UWP 头项目中的代码复制到 .NET MAUI 应用项目的 Platforms\Windows 文件夹中。 此外，将类中的任何自定义代码 Xamarin.FormsApp 复制到 .NET MAUI 应用项目中的同一类。

在生成时，生成系统仅在为该特定平台生成时包含每个文件夹中的代码。 例如，在为 Android 生成时， Platforms\Android 文件夹中的文件将内置到应用包中，但其他 平台 文件夹中的文件不会。 此方法使用多目标从单个项目面向多个平台。 .NET MAUI 应用也可以基于自己的文件名和文件夹条件进行多目标化。 这样，便可以构建 .NET MAUI 应用项目，这样就不必将平台代码放入 Platform 文件夹的子文件夹中。 有关详细信息，请参阅配置多目标。

将配置复制到 .NET MAUI 应用

每个平台都使用自己的本机应用清单文件来指定应用标题、ID、版本等信息。 使用 .NET MAUI 单一项目可以在项目文件中的单个位置指定此常见应用数据。

若要指定项目的共享应用清单数据，请在 解决方案资源管理器中打开项目的快捷菜单，然后选择 “属性”。 然后，可以在 MAUI 共享 > 常规中指定应用标题、ID 和版本：

在生成时，共享应用清单数据与本机应用清单文件中特定于平台的数据合并，以生成应用包的清单文件。 有关详细信息，请参阅 .NET MAUI 中的项目配置 - MAUI 共享。

你 Xamarin.Forms 应用清单中的剩余数据应复制到 .NET MAUI 应用清单：

• 在 Android 上，将 Android 头项目中 AndroidManifest.xml 文件 Xamarin.Forms 的任何其他数据复制到 .NET MAUI 应用项目中 的平台\Android\AndroidManifest.xml 文件。
• 在 iOS 上，将 iOS 头项目中 Info.plist 文件 Xamarin.Forms 的任何其他数据复制到 .NET MAUI 应用项目中 的平台\iOS\Info.plist 文件。 此外，将 iOS 头项目中的 Entitlements.plist 文件 Xamarin.Forms 复制到 .NET MAUI 应用项目的 Platforms\iOS 文件夹中。
• 在 Windows 上，将其他数据从 UWP 头项目中的 Package.appxmanifest 文件 Xamarin.Forms 复制到 .NET MAUI 应用项目中 的平台\Windows\Package.appxmanifest 文件。

将资源复制到 .NET MAUI 应用

.NET MAUI 单一项目允许资源文件存储在单个位置，同时在每个平台上使用。 这包括字体、图像、应用图标、初始屏幕、原始资产和用于设置 .NET MAUI 应用的样式的 CSS 文件。

资源文件通常应放置在 .NET MAUI 应用项目的 Resources 文件夹中，或者 资源 文件夹的子文件夹，并且必须正确设置其生成作。 下表显示了每种资源文件类型的生成操作：

以下屏幕截图显示了一个典型的 Resources 文件夹，其中包含每种资源类型的子文件夹：

如果资源已添加到正确的 Resources 子文件夹，则会正确设置资源文件的生成操作。

应用图标

将 Xamarin.Forms 应用图标拖动到项目的 Resources\AppIcon 文件夹中，以将其添加到 .NET MAUI 应用项目中，并且其生成操作将在其中自动设置为 MauiIcon。 在生成时，应用图标的大小调整为目标平台和设备的正确大小。 应用图标的大小调整为多个分辨率，因为它们具有多个用途，包括用于表示设备上的应用和应用商店中的应用。

有关详细信息，请参阅 向 .NET MAUI 应用项目添加应用图标。

初始屏幕

Xamarin.Forms如果应用具有初始屏幕，则应将图像拖动到项目的 Resources\Splash 文件夹中，从而将它添加到 .NET MAUI 应用项目中。其生成操作将自动设置为 MauiSplashScreen。 在生成时，初始屏幕图像的大小调整为目标平台和设备的正确大小。

有关详细信息，请参阅 向 .NET MAUI 应用项目添加初始屏幕。

映像

设备具有一系列屏幕大小和密度，每个平台都具有显示依赖于密度的图像的功能。 在 Xamarin.Forms 中，依赖于密度的图像通常放置在头项目中，并采用特定于平台的命名约定。 可通过两种方法将这些映像迁移到 .NET MAUI。

建议的方法是将 Xamarin.Forms 解决方案中每个图像的最高分辨率版本复制到 .NET MAUI 应用项目：将其拖动到项目的 Resources\Images 文件夹中，生成操作会自动设置为 MauiImage。 还需要为每个位图图像设置 BaseSize 属性，以确保可以调整大小。 这样就无需在每个平台上拥有多个版本的每个图像。 在构建时，任何图像都将调整为多个基于密度的图像，以满足平台要求。 有关详细信息，请参阅 将图像添加到 .NET MAUI 应用项目。

或者，您可以将密度相关的图像从Xamarin.Forms 解决方案复制到 .NET MAUI 应用项目的 Platforms\{Platform} 文件夹中的同名文件夹，并将它们的生成操作设置为在 Xamarin.Forms 解决方案中使用的生成操作。 下表列出了解决方案的示例图像位置 Xamarin.Forms 及其在 .NET MAUI 应用项目中的等效位置：

如果您采用了与Xamarin.Forms解决方案中相同的图像命名约定，则会根据设备的功能在运行时选择适当的图像。 此方法的缺点是，每个平台上仍有多个版本的每个映像。

字体

您可以将Xamarin.Forms解决方案中的任何字体拖到 .NET MAUI 应用项目的 Resources\Fonts 文件夹中，这样这些字体就会自动添加到您的 .NET MAUI 解决方案中，其生成操作将自动设置为 MauiFont。

有关详细信息，请参阅 字体。

CSS 文件

可以通过将解决方案中的任何 CSS 文件Xamarin.Forms拖到同名文件夹中，并在"属性"窗口中将其生成操作设置为MauiCss，将其添加到 .NET MAUI 解决方案中。

有关在 .NET MAUI 应用中使用 CSS 文件的详细信息，请参阅 使用级联样式表的样式应用。

原始资产

任何原始资产文件（如 HTML、JSON 和视频）都应从 Xamarin.Forms 解决方案复制到 .NET MAUI 应用项目，方法是将它们拖到项目的 Resources\Raw 文件夹中，其中生成作将自动设置为 MauiAsset。

本地化资源

在 .NET MAUI 应用中，字符串使用与 Xamarin.Forms 应用相同的方法进行本地化。 因此，应将 .NET 资源文件（.resx）从 Xamarin.Forms 解决方案复制到 .NET MAUI 解决方案中同名的文件夹。 然后，必须指定 .NET MAUI 应用的中性语言。 有关详细信息，请参阅 指定应用的中性语言。

在 .NET MAUI 应用程序中，图像是通过与 Xamarin.Forms 应用中相同的方法进行本地化的。 因此，应将本地化图像及其所在的文件夹从 Xamarin.Forms 解决方案复制到 .NET MAUI 应用项目：

• 在 Android 上，本地化图像的 .NET MAUI 应用项目中的根文件夹是 Platforms\Android\Resources。
• 在 iOS 上，本地化映像的 .NET MAUI 应用项目中的根文件夹是 Platforms\iOS\Resources。
• 在 Windows 上，本地化映像的 .NET MAUI 应用项目中的根文件夹是 Platforms\Windows\Assets\Images。

本地化映像应将其生成操作设置为解决方案中使用的 Xamarin.Forms 生成操作。 有关详细信息，请参阅 本地化映像。

在 .NET MAUI 应用中，应用名称使用与 Xamarin.Forms 应用中相同的方法进行本地化：

• 在 Android 上，本地化的应用名称可以使用基于文件夹的命名约定存储在 Platforms\Android\Resources 文件夹中。 应用名称本地化文件夹和文件应从 Xamarin.Forms 解决方案复制到此文件夹。
• 在 iOS 上，本地化的应用名称使用基于文件夹的命名约定存储在 Platforms\iOS\Resources 文件夹中。 应用名称本地化文件夹和文件应从 Xamarin.Forms 解决方案复制到此文件夹。
• 在 Windows 上，本地化的应用名称存储在应用包清单中。

有关详细信息，请参阅 本地化应用名称。 有关 .NET MAUI 应用本地化的详细信息，请参阅 本地化。

命名空间更改

命名空间在从 Xamarin.Forms 转移到 .NET MAUI 时已更改，并且 Xamarin.Essentials 功能现在属于 .NET MAUI。 若要进行命名空间更新，请为以下命名空间执行查找和替换：

.NET MAUI 项目使用隐式 global using 指令。 使用此功能可以删除 using 命名空间的 Xamarin.Essentials 指令，而无需将它们替换为等效的 .NET MAUI 命名空间。

此外，默认 XAML 命名空间已从 .NET MAUI 中的 http://xamarin.com/schemas/2014/forms 变更为 http://schemas.microsoft.com/dotnet/2021/maui。 因此，应将所有出现的地方 xmlns="http://xamarin.com/schemas/2014/forms" 替换为 xmlns="http://schemas.microsoft.com/dotnet/2021/maui"。

API 更改

一些 API 在从 Xamarin.Forms 迁移到 .NET MAUI 的过程中发生了更改。 这是多种原因，包括删除由成为 .NET MAUI 一部分而 Xamarin.Essentials 引起的重复功能，并确保 API 遵循 .NET 命名准则。 以下部分将讨论这些更改。

颜色变化

在Xamarin.Forms中，Xamarin.Forms.Color结构允许使用double值构造Color对象，并提供命名颜色，例如Xamarin.Forms.Color.AliceBlue。 在 .NET MAUI 中，此功能已分为 Microsoft.Maui.Graphics.Color 类和 Microsoft.Maui.Graphics.Colors 类。

在Microsoft.Maui.Graphics.Color命名空间中的Microsoft.Maui.Graphics类允许您使用float值、byte值和int值来构造Color对象。 该 Microsoft.Maui.Graphics.Colors 类也位于命名空间中 Microsoft.Maui.Graphics ，主要提供相同的命名颜色。 例如，使用 Colors.AliceBlue 来指定 AliceBlue 颜色。

下表显示了结构与Microsoft.Maui.Graphics.Color类之间的 Xamarin.Forms.Color API 更改：

此外，Microsoft.Maui.Graphics.Color 中的所有数值不是double ，而是float，如Xamarin.Forms.Color中所用。

布局更改

下表列出了在从 Xamarin.Forms 转移到 .NET MAUI 时已删除的布局 API：

此外，可以通过将子级添加到布局的 Children 集合中来将子级添加到代码中的 Xamarin.Forms 布局。

Grid grid = new Grid();
grid.Children.Add(new Label { Text = "Hello world" });

在 .NET MAUI 中，集合Children供 .NET MAUI 内部使用，不应直接修改。 代码中应直接将子元素添加到布局中。

Grid grid = new Grid();
grid.Add(new Label { Text = "Hello world" });

在运行升级后的 .NET MAUI 应用时，你可能会注意到布局行为不同。 有关详细信息，请参阅布局行为更改。Xamarin.Forms

自定义布局更改

创建自定义布局 Xamarin.Forms 的过程包括创建一个继承自 Layout<View> 的类，同时重写 VisualElement.OnMeasure 和 Layout.LayoutChildren 方法。 有关详细信息，请参阅Xamarin.Forms中的自定义布局。

在 .NET MAUI 中，布局类派生自抽象 Layout 类。 此类将跨平台的布局和测量任务委托给布局管理类。 每个布局管理器类实现 ILayoutManager 接口，该接口规定必须提供 Measure 和 ArrangeChildren 的实现：

• 实现 Measure 调用 IView.Measure 布局中的每个视图，并返回给定约束的布局的总大小。
• 实现 ArrangeChildren 确定每个视图应放置在布局边界内的位置，并调用 Arrange 每个视图及其相应的边界。 返回值是布局的实际大小。

有关详细信息，请参阅 自定义布局。

设备更改

Xamarin.Forms 具有一个 Xamarin.Forms.Device 类，可帮助你与运行应用的设备和平台进行交互。 .NET MAUI Microsoft.Maui.Controls.Device中的等效类已弃用，其功能被多个类型替换。

下表显示了类中 Xamarin.Forms.Device 功能的 .NET MAUI 替换项：

地图更改

在 Xamarin.Forms.Maps 命名空间中，控件 Map 和关联的类型。 在 .NET MAUI 中，此功能已移至 Microsoft.Maui.Controls.Maps 和 Microsoft.Maui.Maps 命名空间。 某些属性已重命名，某些类型已替换为等效类型。Xamarin.Essentials

下表显示了命名空间中 Xamarin.Forms.Maps 功能的 .NET MAUI 替换项：

.NET MAUI 有两 Map 种类型 - Microsoft.Maui.Controls.Maps.Map 和 Microsoft.Maui.ApplicationModel.Map。 Microsoft.Maui.ApplicationModel命名空间是 .NET MAUI 的一项指令，因此在代码中使用global using控件时，您必须完全限定Map的使用方式或使用别名。

在 XAML 中， xmlns 应为 Map 控件添加命名空间定义。 虽然这不是必需的，但它可以防止存在于命名空间中的Microsoft.Maui.Controls.Maps类型Polyline与Microsoft.Maui.Controls.Shapes类型之间的Polygon冲突。 有关详细信息，请参阅 “显示地图”。

其他更改

在从 Xamarin.Forms 迁移到 .NET MAUI 的过程中，少量其他 API 已被合并。 下表显示了这些更改：

此外，在应用进入后台后再回到前台时，会在 Android 上调用Xamarin.Forms中的Page.OnAppearing重写方法。 但是，在同一场景中，iOS 和 Windows 上不会调用此替代方案。 在 .NET MAUI 中，当应用背景化，然后带到前台时， OnAppearing() 不会在任何平台上调用重写。 相反，应该侦听生命周期事件 Window ，以便在应用返回到前台时收到通知。 有关详细信息，请参阅 .NET MAUI 窗口。

原生格式更改

本机表单Xamarin.Forms已成为 .NET MAUI 中的本机嵌入，并使用不同的初始化方法和不同的扩展方法将跨平台控件转换为其本机类型。 有关详细信息，请参阅本机嵌入。

AssemblyInfo 更改

通常在 AssemblyInfo.cs 文件中设置的属性现在可在 SDK 样式项目中使用。 建议将它们从 AssemblyInfo.cs 迁移到每个项目中的项目文件，并删除 AssemblyInfo.cs 文件。

（可选）可以保留AssemblyInfo.cs文件并将项目文件中的属性设置为GenerateAssemblyInfofalse：

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

有关属性 GenerateAssemblyInfo 的详细信息，请参阅 GenerateAssemblyInfo。

更新应用依赖项

通常，Xamarin.Forms NuGet 包与 .NET 8 不兼容，除非它们是使用 .NET 目标框架标识符（TFM）重新编译的。 但是，Android 应用可以使用面向monoandroid和monoandroidXX.X框架的NuGet包。

可以通过查看 NuGet 上的“框架”选项卡来确认包是否与 .NET 8 兼容，并检查它是否列出了下表中显示的兼容框架之一：

如果 NuGet 上的包表示与上述任何兼容框架的兼容性，而不考虑还包括不兼容的框架，则包是兼容的。 可以使用 Visual Studio 中的 NuGet 包管理器将兼容的 NuGet 包添加到 .NET MAUI 库项目。

如果找不到与 .NET 8 兼容的 NuGet 包版本，则应：

• 如果拥有代码，请使用 .NETTFM 重新编译包。
• 查找 .NET 8 版本的包的预览版本。
• 将依赖项替换为 .NET 8 兼容的替代项。

编译和故障排除

解决依赖项后，您应构建您的项目。 任何错误都会引导你完成后续步骤。

下表提供有关克服常见生成或运行时问题的指南：