手动将 Xamarin.Forms 应用升级到多项目 .NET MAUI 应用

将多项目应用升级到多项目 Xamarin.Forms .NET 多平台应用 UI （.NET MAUI） 应用遵循与 Xamarin.Android 和 Xamarin.iOS 项目相同的步骤，并执行其他步骤来利用 .NET MAUI 中的更改。

本文介绍如何手动将 Xamarin.Forms 库项目迁移到 .NET MAUI 库项目。 执行此操作之前，必须将 Xamarin.Forms 平台项目更新为 SDK 风格的项目。 SDK 样式项目是所有 .NET 工作负载使用的相同项目格式，与许多 Xamarin 项目相比，其详细程度要小得多。 有关更新应用项目的信息，请参阅 将 Xamarin.Android、Xamarin.iOS 和 Xamarin.Mac 项目升级到 .NET、 Xamarin.Android 项目迁移、 Xamarin Apple 项目迁移和 Xamarin.Forms UWP 项目迁移。

若要将 Xamarin.Forms 库项目迁移到 .NET MAUI 库项目，必须：

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

更新您的Xamarin.Forms应用

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

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

创建新项目

在 Visual Studio 中，创建与库项目同名 Xamarin.Forms 的新 .NET MAUI 类库项目。 此项目将托管来自您的库文件项目的代码 Xamarin.Forms 。 打开项目文件将确认你有一个 .NET SDK 样式的项目：

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net8.0;net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
        <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>
        <!-- Uncomment to also build the tizen app. You will need to install tizen by following this: https://github.com/Samsung/Tizen.NET -->
        <!-- <TargetFrameworks>$(TargetFrameworks);net8.0-tizen</TargetFrameworks> -->
        <UseMaui>true</UseMaui>
        <SingleProject>true</SingleProject>
        <ImplicitUsings>enable</ImplicitUsings>

        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">11.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">13.1</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</TargetPlatformMinVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'tizen'">6.5</SupportedOSPlatformVersion>
    </PropertyGroup>

</Project>

在平台项目中，添加对此新库项目的引用。 然后将库文件复制到 Xamarin.Forms .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 变更为 Xamarin.Forms。 因此，应将所有出现的地方 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结构允许使用Color值构造double对象，并提供命名颜色，例如Xamarin.Forms.Color.AliceBlue。 在 .NET MAUI 中，此功能已分为 Microsoft.Maui.Graphics.Color 类和 Microsoft.Maui.Graphics.Colors 类。

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

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

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

布局更改

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

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

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 命名空间中，控件 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控件时，您必须完全限定Microsoft.Maui.Controls.Maps.Map的使用方式或使用Map。

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

其他更改

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

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

原生格式更改

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

初始化已迁移的应用程序

将应用手动更新 Xamarin.Forms 到 .NET MAUI 时，需要在每个平台项目中启用 .NET MAUI 支持，更新每个平台项目的入口点类，然后配置 .NET MAUI 应用的引导。

在平台项目中启用 .NET MAUI

在更新每个平台项目的入口点类之前，必须先启用 .NET MAUI 支持。 可以通过在每个平台项目中将生成属性设置为$(UseMaui)true来实现此目的：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <UseMaui>true</UseMaui>
  </PropertyGroup>
</Project>

添加包引用

在 .NET 8 中，.NET MAUI 作为 .NET 工作负载和多个 NuGet 包提供。 这种方法的优势在于，它使你能够轻松地将项目固定到特定版本，同时使你能够轻松预览未发布的版本或实验性版本。

应将以下显式包引用添加到 <ItemGroup> 每个项目文件中：

<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />

变量 $(MauiVersion) 是从已安装的 .NET MAUI 版本引用的。 可以通过将 $(MauiVersion) 生成属性添加到每个项目文件来替代此属性：

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <UseMaui>True</UseMaui>
        <MauiVersion>8.0.3</MauiVersion>
    </PropertyGroup>
</Project>

Android 项目配置

在 .NET MAUI Android 项目中，更新 MainApplication 类以匹配以下代码：

using System;
using Android.App;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Application]
    public class MainApplication : MauiApplication
    {
        public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
        {
        }

        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

此外，请更新 MainActivity 类以继承自 MauiAppCompatActivity:

using System;
using Microsoft.Maui;
using Android.App;
using Android.Content.PM;
using Android.Runtime;
using Android.OS;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Activity(Label = "MyTitle", Icon = "@mipmap/icon", Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)]
    public class MainActivity : MauiAppCompatActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
        }
    }
}

然后，更新清单文件以指定 minSdKVersion 为 21，这是 .NET MAUI 所需的最低 Android SDK 版本。 可以通过修改 <uses-sdk /> 节点（节点的 <manifest> 子级）来实现此目的：

<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="32" />

iOS 项目配置

在 .NET MAUI iOS 项目中，更新 AppDelegate 类以继承自 MauiUIApplicationDelegate：

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Maui;
using Foundation;
using UIKit;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.iOS
{
    [Register("AppDelegate")]
    public partial class AppDelegate : MauiUIApplicationDelegate
    {
        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

然后，更新 Info.plist ， MinimumOSVersion 使其为 11.0，这是 .NET MAUI 所需的最低 iOS 版本。

UWP 项目配置

在 .NET MAUI WinUI 3 项目中，更新 App.xaml 以匹配以下代码：

<?xml version="1.0" encoding="utf-8"?>
<maui:MauiWinUIApplication
    x:Class="YOUR_NAMESPACE_HERE.WinUI.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:maui="using:Microsoft.Maui"
    xmlns:local="using:YOUR_NAMESPACE_HERE.WinUI">
    <maui:MauiWinUIApplication.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <!-- Other merged dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Other app resources here -->
        </ResourceDictionary>
    </maui:MauiWinUIApplication.Resources>
</maui:MauiWinUIApplication>

此外，请更新 App.xaml.cs 以匹配以下代码：

using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.WinUI;

public partial class App : MauiWinUIApplication
{
    public App()
    {
        InitializeComponent();
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

然后将 launchSettings.json 文件添加到项目的 “属性” 文件夹中，并将以下 JSON 添加到该文件：

{
  "profiles": {
    "Windows Machine": {
      "commandName": "MsixPackage",
      "nativeDebugging": true
    }
  }
}

应用入口点

.NET MAUI 应用具有单个跨平台应用入口点。 每个平台入口点在静态MauiProgram类上调用一个CreateMauiApp方法，并返回一个 MauiApp。

因此，添加一个名为 MauiProgram 包含以下代码的新类：

namespace YOUR_NAMESPACE_HERE;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

        return builder.Build();
    }
}

如果需要将特定于平台的服务迁移到 .NET MAUI，请使用 AddTransient(IServiceCollection, Type) 方法将指定类型的瞬时服务添加到指定的 IServiceCollection 中。

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 兼容的替代项。

编译和故障排除

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

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

另请参阅

• 从 .NET Framework 移植到 .NET
• .NET 升级助手