用途
该技能用于把 Xamarin.Forms 应用迁移到 .NET MAUI,避免直接照搬已过时的模式。它主张把迁移当作一次审计加分阶段重建,在全新的 MAUI 项目上进行,除非用户明确只需要小范围、战术性的移植。
主要能力
- 迁移审计:识别 DependencyService、MessagingCenter、自定义渲染器/效果、权限以及平台能力等需要处理的部分。
- 迁移工具评估:在手动迁移前,先检查 .NET Upgrade Assistant 能否覆盖机械性工作,例如项目转换与命名空间/API 重写。
- 分阶段迁移工作流:从清点现有应用、创建新 MAUI 项目、迁移共享代码、更新命名空间与 API,到迁移启动流程、UI 与导航,再到渲染器替换规划与逐片验证。
- 常见 API 替换对照:给出 Xamarin.Forms 时代模式与 MAUI 方向的对应关系。
- DependencyService 转 DI:把跨平台契约放到共享代码,按平台实现,并在 MauiProgram.cs 中按生命周期注册。
- MessagingCenter 替换:按最小显式通信模式选择可观察属性与绑定、WeakReferenceMessenger、注入服务调用、导航服务或平台服务事件等方案。
- 渲染器到处理器的规划:按渲染器形态分类为映射器定制、自定义处理器、平台服务或 slim binding。
- 平台能力对齐:记录各目标平台的权限、清单、Essentials API 覆盖、原生 SDK 可用性、后台任务与 UI 差异等。
- 跨技能路由:指向 maui-current-apis、maui-custom-handlers、maui-platform-invoke、android-slim-bindings、ios-slim-bindings、maui-accessibility、maui-performance 等技能。
- 验证清单:确保迁移计划基于审计后的解决方案,新代码使用 MAUI 命名空间与当前 API,平台能力与权限已映射,渲染器/效果已分类,替换项生命周期明确,每个迁移切片至少在一个目标平台构建并运行。
使用方式
迁移工具方面,可先安装并运行 .NET Upgrade Assistant:
dotnet tool install -g upgrade-assistant upgrade-assistant upgrade <your-solution>.sln
Upgrade Assistant 可帮助完成项目转换和命名空间/API 重写。该技能用于工具无法安全自动化的决策:渲染器分类、DependencyService 生命周期、MessagingCenter 替换、平台能力对齐以及验证规划。
迁移工作流包括:清点当前应用(Xamarin.Forms 版本、目标平台、平台项目、NuGet 包、渲染器、效果、DependencyService、MessagingCenter、原生 SDK,以及应用启动、导航、资源字典、图片/字体、平台授权/权限);创建与目标应用形态匹配的新 .NET MAUI 项目或解决方案结构,优先于就地编辑 Xamarin.Forms 项目;先迁移共享代码(模型、服务、视图模型、转换器、资源、XAML),在共享代码可构建前不引入平台代码;使用 maui-current-apis 更新命名空间与 API,不引入新的 Xamarin.Forms 或 Xamarin.Essentials 引用;把应用启动迁移到 MauiProgram.cs、CreateMauiApp、DI 注册、字体、处理器、生命周期事件与平台服务;增量迁移 UI 与导航,保持 Shell 路由名、模态流程与深链行为明确;规划自定义渲染器/效果替换;对每个迁移切片用构建、平台启动以及针对变更 UI 的无障碍或性能检查进行验证。
DependencyService 转 DI 的做法:把跨平台契约放到共享代码,例如:
public interface IClipboardAuditService { Task TrackCopyAsync(string source, CancellationToken cancellationToken = default); }
在 Platforms/<Platform>/ 或目标特定文件中实现各平台版本;在 MauiProgram.cs 中按生命周期需要以 AddSingleton、AddScoped 或 AddTransient 注册;把服务注入视图模型或服务。除非应用已使用服务定位器模式且正在控制迁移风险,否则避免从页面调用服务定位器。
MessagingCenter 替换:按现有用途选择最小显式通信模式——视图模型更新绑定页面用可观察属性与绑定;跨功能领域事件用 WeakReferenceMessenger 或应用事件聚合器;一个服务请求另一个服务工作则注入目标服务并调用方法;导航触发用导航服务或 Shell 路由调用;平台回调用平台服务事件或通过 DI 暴露的 IObservable<T>。不要通过到处添加全局静态事件来迁移 MessagingCenter。替换前记录消息名、负载类型、发送者/接收者生命周期与线程。
渲染器到处理器的规划:审计每个渲染器并在写代码前分类——仅修改现有 MAUI 控件的一个原生属性,用限定到子类或命名映射的 Handler.Mapper.AppendToMapping;需要带可绑定属性的跨平台自定义控件,用带 PropertyMapper 和可选 CommandMapper 的自定义处理器;订阅原生事件,用 Handler 的 ConnectHandler/DisconnectHandler 并显式取消订阅清理;调用相机、健康、地图、支付或其他 SDK API,用平台服务或 slim binding,不要把 SDK 工作流藏在可视化处理器中;仅用于样式的 Xamarin.Forms 效果,优先用样式、视觉状态或处理器映射器。
平台能力对齐:对每个目标平台记录所需权限、授权、清单、Info.plist 键与应用能力;Essentials API 覆盖与行为差异;原生 SDK 可用性与版本要求;后台任务、推送/深链、安全存储、文件选择器与生物识别差异;UI 对齐风险,如安全区域、键盘/软输入、手势与桌面指针行为。
适用场景
适用于需要把 Xamarin.Forms 应用迁移到 .NET MAUI 的团队,尤其是希望先做审计、再分阶段重建,而不是盲目复制过时模式的情况。也适用于需要评估 Upgrade Assistant 能覆盖哪些机械性工作、哪些决策需要人工判断的场景。
限制
资料未提供该技能的具体收费、价格、平台支持范围或效果数据。迁移的具体结果取决于原应用的实际结构与目标平台,资料未给出保证性说明。