使用 .NET 升级助手将 Xamarin.Forms 应用升级到 .NET MAUI 应用

  • 项目

.NET 升级助手通过转换解决方案的项目文件和执行常见代码更新，帮助你将 Xamarin.Forms 项目升级到.NET 多平台应用 UI (.NET MAUI)。 具体而言，该工具将：

  • 将 Xamarin.Forms 类库项目、Xamarin.iOS 项目和 Xamarin.Android 项目转换为 SDK 样式项目。
  • 根据需要将项目文件中的目标框架更新为 net8.0-android 和 net8.0-ios。
  • 设置项目文件中的 <UseMaui>true</UseMaui>。
  • 添加其他项目属性，并移除不需要的项目属性。
  • 添加和移除特定的 NuGet 包：
    • 移除 Xamarin.Forms 和 Xamarin.Essentials NuGet 包。
    • 将 Xamarin.CommunityToolkit NuGet 包替换为 .NET MAUI Community Toolkit NuGet 包。
    • 如果使用，请将 SkiaSharp NuGet 包的 Xamarin.Forms 兼容版本替换为.NET MAUI 兼容版本。
  • 移除对 Xamarin.Essentials 命名空间的引用，并将 Xamarin.Forms 命名空间替换为 Microsoft.Maui 和 Microsoft.Maui.Controls 命名空间。

在运行此工具后，需要其他操作才能完成迁移。

注意

.NET MAUI 的 .NET 升级助手不支持升级 UWP 项目、iOS 扩展项目或绑定项目。

有关 .NET 升级助手的详细信息，包括可以转换的其他应用类型，请参阅.NET 升级助手概述。

开始使用

.NET 升级助手作为 Windows 上的 Visual Studio 扩展和 Windows 和 Mac 的 CLI 工具提供。 若要使用它，Xamarin.Forms 项目必须使用 Xamarin.Forms 4.8 或更高版本。 但是，为了获得最佳成功，我们建议 Xamarin.Forms 项目使用 Xamarin.Forms 5.0 和 .NET Standard 2.0 或更高版本。

重要说明

.NET MAUI 的 .NET 升级助手仍在开发中。 请使用“area：Maui”标签“提交反馈”，以便我们可以继续改进此工具。

.NET 升级助手将提示你执行的升级类型：

  • 就地：此选项无需复制即可升级项目。
  • 并行承载：此选项复制项目并升级副本，保留原始项目。 目前，.NET MAUI 并行升级需要创建新项目以升级每个项目头。 尝试将项目头升级到现有项目可能会导致错误，目前不支持体验。

在将 Xamarin.Forms 应用升级到.NET MAUI 之前，应先将 Xamarin.Forms 应用更新为使用 Xamarin.Forms 5，并确保它仍然正常运行。 此外，还应更新应用用于最新版本的依赖项。

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

Visual Studio 中的快速操作

.NET 升级助手有一个快速操作，用于将 Xamarin.Forms 命名空间转换为相应的 .NET MAUI 命名空间，该命名空间显示为灯泡：

Screenshot of previewing the application of a light bulb suggestion.

快速操作将在整个文件中进行必要的替换。

注意

将文件从 Xamarin.Forms 项目迁移到 .NET MAUI 项目时，将显示快速操作灯泡。

安装

强烈建议使用 Visual Studio 2022 版本 17.6.0 或更高版本来运行升级助手。 安装升级助手扩展：

  1. 打开 Visual Studio 并选择“扩展” > “管理扩展”菜单项。
  2. 在“管理扩展”对话框中，搜索并下载 .NET 升级助手。
  3. 下载扩展后，关闭 Visual Studio。 然后，将安装该扩展。

当扩展在 Visual Studio Marketplace 上有新版本时，会自动进行更新。 有关详细信息，请参阅自动扩展升级。

运行升级助手

右键单击“解决方案资源管理器”中的项目，选择“升级”。

后续步骤

手动迁移