将多项目应用升级到多项目 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 应用更新为使用 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 指令。 使用此功能可以删除 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"。
注释
您可以使用 Xamarin.Forms快速更新您的 Microsoft.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 更改：
| 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 | Xamarin.Forms 属性在 .NET MAUI 中被替换为方法。 |
Xamarin.Forms.Color.Saturation |
Microsoft.Maui.Graphics.Color.GetSaturation | Xamarin.Forms 属性在 .NET MAUI 中被替换为方法。 |
Xamarin.Forms.Color.Luminosity |
Microsoft.Maui.Graphics.Color.GetLuminosity | Xamarin.Forms 属性在 .NET MAUI 中被替换为方法。 |
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 ，而是double，如Xamarin.Forms.Color中所用。
注释
与 Xamarin.Forms 不同，Microsoft.Maui.Graphics.Color 无法隐式转换为 System.Drawing.Color。
布局更改
下表列出了在从 Xamarin.Forms 转移到 .NET MAUI 时已删除的布局 API：
| Xamarin.Forms 应用程序接口 | .NET MAUI API | 注释 |
|---|---|---|
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add |
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 和关联的类型。 在 .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 中， xmlns 应为 Map 控件添加命名空间定义。 虽然这不是必需的，但它可以防止Polygon类型和Polyline类型在Microsoft.Maui.Controls.Maps和Microsoft.Maui.Controls.Shapes命名空间中发生冲突。 有关详细信息，请参阅 “显示地图”。
其他更改
在从 Xamarin.Forms 迁移到 .NET MAUI 的过程中，少量其他 API 已被合并。 下表显示了这些更改：
| Xamarin.Forms 应用程序接口 | .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。 |
此外，在应用进入后台后再回到前台时，会在 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>
重要
您必须将 <UseMaui>true</UseMaui> 添加到项目文件中才能启用 .NET MAUI 支持。 此外，请确保已在 WinUI 项目文件中添加了 <EnableDefaultMauiItems>false</EnableDefaultMauiItems>。 这将阻止您收到关于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 项目，App可以在MainPage.xaml.cs文件中找到引用builder.UseMauiApp<App>()。
如果需要将特定于平台的服务迁移到 .NET MAUI，请使用 AddTransient(IServiceCollection, Type) 方法将指定类型的瞬时服务添加到指定的 IServiceCollection 中。
注释
您可以使用 Xamarin.Forms快速更新您的 Microsoft.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 兼容，并检查它是否列出了下表中显示的兼容框架之一：
| 兼容的框架 | 不兼容的框架 |
|---|---|
| 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）中，为了确保弹出窗口正确显示，您应调用 DisplayAlert（在 .NET 10+ 中为 DisplayAlertAsync）、DisplayActionSheet（在 .NET 10+ 中为 DisplayActionSheetAsync），或从用于 DisplayPromptAsync 弹出窗口的 ContentPage 调用 Mopup。 |
| BoxView 未显示。 | 默认大小的BoxViewXamarin.Forms为 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 应用。 |
