手动将 Xamarin.Forms 应用升级到多项目 .NET MAUI 应用
将多项目 Xamarin.Forms 应用升级到多项目 .NET Multi-platform App 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 应用以使用 Xamarin.Forms 5。
- 将应用的依赖项更新为最新版本。
- 确保应用仍然有效。
- 将项目文件更新为 SDK 样式。
- 更新命名空间。
- 解决任何 API 更改。
- 配置 .NET MAUI。
- 使用 .NET 8 版本升级或替换不兼容的依赖项。
- 编译并测试应用。
为了简化升级过程，应创建与 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 指令。 使用此功能可以删除 Xamarin.Essentials 命名空间的 using 指令，而无需将其替换为等效的 .NET MAUI 命名空间。
此外，默认 XAML 命名空间已从 Xamarin.Forms 中的 http://xamarin.com/schemas/2014/forms 更改为 .NET MAUI 中的 http://schemas.microsoft.com/dotnet/2021/maui。 因此，应将所有 xmlns="http://xamarin.com/schemas/2014/forms" 情况替换为 xmlns="http://schemas.microsoft.com/dotnet/2021/maui"。
注意
可使用 Visual Studio 中的快速操作将 Xamarin.Forms 命名空间快速更新为 Microsoft.Maui，前提是已安装升级助手。
API 更改
一些 API 在从 Xamarin.Forms 迁移到 .NET MAUI 时已更改。 这是多种原因，包括移除由 Xamarin.Essentials 成为 .NET MAUI 一部分而引起的重复功能，以及确保 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 命名空间中的 Microsoft.Maui.Graphics.Color 类让你可以使用 float 值、byte 值和 int 值来构造 Color 对象。 Microsoft.Maui.Graphics.Colors 类也位于 Microsoft.Maui.Graphics 命名空间中，主要提供相同的命名颜色。 例如，使用 Colors.AliceBlue 指定 AliceBlue 颜色。
下表显示了 Xamarin.Forms.Color 结构与 Microsoft.Maui.Graphics.Color 类之间的 API 更改：
| Xamarin.Forms API | .NET MAUI API | 注释 |
|---|---|---|
Xamarin.Forms.Color.R |
Microsoft.Maui.Graphics.Color.Red | |
Xamarin.Forms.Color.G |
Microsoft.Maui.Graphics.Color.Green | |
Xamarin.Forms.Color.B |
Microsoft.Maui.Graphics.Color.Blue | |
Xamarin.Forms.Color.A |
Microsoft.Maui.Graphics.Color.Alpha | |
Xamarin.Forms.Color.Hue |
Microsoft.Maui.Graphics.Color.GetHue | 用.NET MAUI 中的方法替换了 Xamarin.Forms 属性。 |
Xamarin.Forms.Color.Saturation |
Microsoft.Maui.Graphics.Color.GetSaturation | 用.NET MAUI 中的方法替换了 Xamarin.Forms 属性。 |
Xamarin.Forms.Color.Luminosity |
Microsoft.Maui.Graphics.Color.GetLuminosity | 用.NET MAUI 中的方法替换了 Xamarin.Forms 属性。 |
Xamarin.Forms.Color.Default |
无 .NET MAUI 等效项。 相反， Microsoft.Maui.Graphics.Color 对象默认为 null。 |
|
Xamarin.Forms.Color.Accent |
无 .NET MAUI 等效项。 | |
Xamarin.Forms.Color.FromHex |
Microsoft.Maui.Graphics.Color.FromArgb | Microsoft.Maui.Graphics.Color.FromHex 已过时，未来版本中会将其删除。 |
此外，Microsoft.Maui.Graphics.Color 中的所有数值都是 float，而不是 Xamarin.Forms.Color 中使用的 double。
注意
与 Xamarin.Forms 不同，Microsoft.Maui.Graphics.Color 不具备向 System.Drawing.Color 的隐式转换功能。
布局更改
下表列出了在从 Xamarin.Forms .NET MAUI 移动到 .NET MAUI 时已删除的布局 API：
| Xamarin.Forms API | .NET MAUI API | 评论 |
|---|---|---|
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add |
接受 3 个参数的 Add 重载在 .NET MAUI 中不存在。 |
|
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal |
无 .NET MAUI 等效项。 | |
Xamarin.Forms.Grid.IGridList<T>.AddVertical |
无 .NET MAUI 等效项。 | |
Xamarin.Forms.RelativeLayout |
Microsoft.Maui.Controls.Compatibility.RelativeLayout | 在 .NET MAUI 中，RelativeLayout 仅作为用于从 Xamarin.Forms 迁移的用户的兼容性控件存在。 请改为使用 Grid，或为兼容性命名空间添加 xmlns。 |
此外，将子级添加到 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" });
重要说明
任何 Add 布局扩展方法(例如 GridExtensions.Add) 在布局上调用，而不是布局 Children 集合。
在运行升级后的 .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 控件和相关类型位于 Xamarin.Forms.Maps 命名空间中。 在 .NET MAUI 中，此功能已移至 Microsoft.Maui.Controls.Maps 和 Microsoft.Maui.Maps 命名空间。 某些属性已重命名，某些类型已替换为来自 Xamarin.Essentials 的等效类型。
下表显示了 Xamarin.Forms.Maps 命名空间中的功能的 .NET MAUI 替换项：
| Xamarin.Forms API | .NET MAUI API | 注释 |
|---|---|---|
Xamarin.Forms.Maps.Map.HasScrollEnabled |
Microsoft.Maui.Controls.Maps.Map.IsScrollEnabled | |
Xamarin.Forms.Maps.Map.HasZoomEnabled |
Microsoft.Maui.Controls.Maps.Map.IsZoomEnabled | |
Xamarin.Forms.Maps.Map.TrafficEnabled |
Microsoft.Maui.Controls.Maps.Map.IsTrafficEnabled | |
Xamarin.Forms.Maps.Map.MoveToLastRegionOnLayoutChange |
无 .NET MAUI 等效项。 | |
Xamarin.Forms.Maps.Pin.Id |
Microsoft.Maui.Controls.Maps.Pin.MarkerId | |
Xamarin.Forms.Maps.Pin.Position |
Microsoft.Maui.Controls.Maps.Pin.Location | |
Xamarin.Forms.Maps.MapClickedEventArgs.Position |
Microsoft.Maui.Controls.Maps.MapClickedEventArgs.Location | |
Xamarin.Forms.Maps.Position |
Microsoft.Maui.Devices.Sensors.Location | Xamarin.Forms.Maps.Position 类型成员已更改为 Microsoft.Maui.Devices.Sensors.Location 类型。 |
Xamarin.Forms.Maps.Geocoder |
Microsoft.Maui.Devices.Sensors.Geocoding | Xamarin.Forms.Maps.Geocoder 类型成员已更改为 Microsoft.Maui.Devices.Sensors.Geocoding 类型。 |
.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 中，应为 Map 控件添加 xmlns 命名空间定义。 虽然这不是必需的，但它可以防止存在于 Microsoft.Maui.Controls.Maps 和 Microsoft.Maui.Controls.Shapes 命名空间中的 Polygon 和 Polyline 类型之间的冲突。 有关详细信息，请参阅显示映射。
其他更改
在从 Xamarin.Forms 迁移到 .NET MAUI 时，已合并了少量其他 API。 下方表格显示了这些更改：
| Xamarin.Forms API | .NET MAUI API | 评论 |
|---|---|---|
Xamarin.Forms.Application.Properties |
Microsoft.Maui.Storage.Preferences | |
Xamarin.Forms.Button.Image |
Microsoft.Maui.Controls.Button.ImageSource | |
Xamarin.Forms.Frame.OutlineColor |
Microsoft.Maui.Controls.Frame.BorderColor | |
Xamarin.Forms.IQueryAttributable.ApplyQueryAttributes |
Microsoft.Maui.Controls.IQueryAttributable.ApplyQueryAttributes | 在 Xamarin.Forms 中，ApplyQueryAttributes 方法接受 IDictionary<string, string> 参数。 在 .NET MAUI 中，ApplyQueryAttributes 方法接受 IDictionary<string, object> 参数。 |
Xamarin.Forms.MenuItem.Icon |
Microsoft.Maui.Controls.MenuItem.IconImageSource | Xamarin.Forms.MenuItem.Icon 是 Xamarin.Forms.ToolbarItem 的基类，因此 ToolbarItem.Icon 变为 ToolbarItem.IconImageSource。 |
Xamarin.Forms.OrientationStateTrigger.Orientation |
Microsoft.Maui.Controls.OrientationStateTrigger.Orientation | 在 Xamarin.Forms 中，OrientationStateTrigger.Orientation 属性的类型为 Xamarin.Forms.Internals.DeviceOrientation。 在 .NET MAUI 中，OrientationStateTrigger.Orientation 属性的类型为 DisplayOrientation。 |
Xamarin.Forms.OSAppTheme |
Microsoft.Maui.ApplicationModel.AppTheme | |
Xamarin.Forms.Span.ForegroundColor |
Microsoft.Maui.Controls.Span.TextColor | |
Xamarin.Forms.ToolbarItem.Name |
Microsoft.Maui.Controls.MenuItem.Text | Microsoft.Maui.Controls.MenuItem.Text 是 Microsoft.Maui.Controls.ToolbarItem 的基类，因此 ToolbarItem.Name 变为 ToolbarItem.Text。 |
此外，在 Xamarin.Forms 中，如果应用位于后台，然后进入前台，Android 上会调用 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>
重要
必须将 <UseMaui>true</UseMaui> 添加到项目文件才能启用 .NET MAUI 支持。 此外，请确保已将 <EnableDefaultMauiItems>false</EnableDefaultMauiItems> 添加到 WinUI 项目文件。 这样你将不会收到有关已定义 InitializeComponent 方法的生成错误。
添加包引用
在 .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 中的资源，则应将这些资源迁移到该文件的新版本。
此外，请更新 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();
}
注意
如果项目包含 App.xaml.cs 中的业务逻辑，则应将该逻辑迁移到该文件的新版本。
然后将 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();
}
}
注意
对于 Xamarin.Forms UWP 项目，可以在 MainPage.xaml.cs 文件中找到 builder.UseMauiApp<App>() 中的 App 引用。
如果存在需要迁移到 .NET MAUI 的特定于平台的服务，请使用 AddTransient(IServiceCollection, Type) 方法将指定类型的临时服务添加到指定的 IServiceCollection。
注意
可使用 Visual Studio 中的快速操作将 Xamarin.Forms 命名空间快速更新为 Microsoft.Maui，前提是已安装升级助手。
AssemblyInfo 更改
通常在 AssemblyInfo.cs 文件中设置的属性现在可在 SDK 样式项目中使用。 建议将它们从 AssemblyInfo.cs 迁移到每个项目中的项目文件，并移除 AssemblyInfo.cs 文件。
也可以保留 AssemblyInfo.cs 文件并将项目文件中的 GenerateAssemblyInfo 属性设置为 false：
<PropertyGroup>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>
有关属性 GenerateAssemblyInfo 的详细信息，请参阅 GenerateAssemblyInfo。
更新应用依赖项
通常，Xamarin.Forms NuGet 包与 .NET 8 不兼容，除非已使用 .NET 目标框架名字对象 (TFM) 重新编译。 但是，Android 应用可以使用面向 monoandroid 和 monoandroidXX.X 框架的 NuGet 包。
对于你正在使用的包，可以通过查看 NuGet 上的“框架”选项卡，以及检查其中是否列出了下表所示兼容框架之一，确认包与 .NET 8 兼容：
| 兼容的框架 | 不兼容的框架 |
|---|---|
| net8.0-android, monoandroid, monoandroidXX.X | |
| net8.0-ios | monotouch、xamarinios、xamarinios10 |
| net8.0-macos | monomac、xamarinmac、xamarinmac20 |
| net8.0-tvos | xamarintvos |
| xamarinwatchos |
注意
不依赖于上面所列不兼容框架的 .NET Standard 库仍与 .NET 8 兼容。
如果 NuGet 上的包指示与上述任何兼容框架的兼容性，而不考虑还包括不兼容的框架，则包是兼容的。 可以使用 Visual Studio 中的 NuGet 包管理器将兼容的 NuGet 包添加到 .NET MAUI 库项目。
如果找不到与 .NET 8 兼容的 NuGet 包版本，则应：
- 如果拥有代码，请使用 .NETTFM 重新编译包。
- 查找 .NET 8 版本包的预览版本。
- 将依赖项替换为与 .NET 8 兼容的替代项。
编译和故障排除
解决依赖项后，应生成项目。 任何错误都会引导你完成后续步骤。
提示
- 在 Visual Studio 中打开和生成项目之前，请从所有项目中删除所有 bin 和 obj 文件夹，尤其是在更改 .NET 版本时。
- 从 Android 项目中删除 Resource.designer.cs 生成的文件。
下表提供有关克服常见生成或运行时问题的指南：
| 问题 | 提示 |
|---|---|
Xamarin.* 命名空间不存在。 |
将命名空间更新为其 .NET MAUI 等效项。 有关详细信息，请参阅命名空间变更。 |
| API 不存在。 | 将 API 使用情况更新为其 .NET MAUI 等效项。 有关详细信息，请参阅 API 更改。 |
| 应用不将部署。 | 确保所需的平台项目设置为在 Visual Studio 的 Configuration Manager 中部署。 |
| 应用不将启动。 | 更新每个平台项目的入口点类和应用入口点。 有关详细信息，请参阅启动已迁移的应用。 |
| CollectionView 不滚动。 | 检查容器布局和 CollectionView 的度量值大小。 默认情况下，控件将占用容器允许的尽可能多的空间。 Grid 以自己的大小约束子级。 然而，StackLayout 允许子级占用超出其边界的空间。 |
| 弹出窗口显示在 iOS 页面的下方。 | 在 Xamarin.Forms 中，iOS 上的所有弹出窗口都是 UIWindow 实例。但在 .NET MAUI 中，是通过定位当前呈现的 ViewController 来显示弹出窗口，并且在显示弹出窗口时使用了 PresentViewControllerAsync。 在 Mopups 等插件中，为了确保正确显示弹出窗口，应从 Mopup 弹出窗口中使用的 ContentPage 调用 DisplayAlert、DisplayActionSheet 或 DisplayPromptAsync。 |
| BoxView 不显示。 | Xamarin.Forms 中 BoxView 的默认大小为 40x40。 .NET MAUI 中 BoxView 的默认大小为 0x0。 将 WidthRequest 和 HeightRequest 设置为 40。 |
| 布局缺少填充、边距或间距。 | 根据 .NET MAUI 样式资源向项目添加默认值。 有关详细信息，请参阅 Xamarin.Forms 中的默认值更改。 |
| 自定义布局不起作用。 | 自定义布局代码需要更新才能在 .NET MAUI 中工作。 有关详细信息，请参阅自定义布局更改。 |
| 自定义呈现器不起作用。 | 呈现器代码需要更新才能在 .NET MAUI 中工作。 有关详细信息，请参阅在 .NET MAUI 中使用自定义呈现器。 |
| 效果不起作用。 | 效果代码需要更新才能在 .NET MAUI 中工作。 有关详细信息，请参阅在 .NET MAUI 中使用效果。 |
| SkiaSharp 代码不起作用。 | SkiaSharp 代码需进行次要更新才能在 .NET MAUI 中使用。 有关详细信息，请参阅在 .NET MAUI 中重用 SkiaSharp 代码。 |
| 无法访问以前创建的应用属性数据。 | 将应用属性数据迁移到 .NET MAUI 首选项。 有关详细信息，请参阅将数据从 Xamarin.Forms 应用属性字典迁移到 .NET MAUI 首选项。 |
| 无法访问以前创建的安全存储数据。 | 将安全存储数据迁移到 .NET MAUI。 有关详细信息，请参阅从 Xamarin.Essentials 安全存储迁移到 .NET MAUI 安全存储。 |
| 无法访问以前创建的版本跟踪数据。 | 将版本跟踪数据迁移到 .NET MAUI。 有关详细信息，请参阅将版本跟踪数据从 Xamarin.Forms 应用迁移到 .NET MAUI 应用。 |
