syncfusion-maui-toolkit-migration

用途

该技能用于指导开发者将现有的 Syncfusion® .NET MAUI 项目迁移到 Syncfusion® Toolkit for .NET MAUI。Toolkit 是 Syncfusion® 面向 MAUI 应用的下一代组件集合，大部分 API 与功能保持一致，但组件被整合进单一工具包并更新了命名空间。本指南帮助以最小的代码改动完成迁移。

主要能力

迁移涉及三项主要变化：

1. 命名空间更新：组件命名空间重组到 Syncfusion.Maui.Toolkit.* 下。
2. 程序集合并：原本独立的组件程序集（如 Syncfusion.Maui.Buttons、Syncfusion.Maui.Calendar 等）合并为单一 Syncfusion.Maui.Toolkit。
3. 配置方法变更：ConfigureSyncfusionCore() 重命名为 ConfigureSyncfusionToolkit()。

技能提供的文档包括：

• 入门指南（references/getting-started.md）：迁移原因、前置条件与要求、受影响的组件、高层变更摘要。
• 命名空间更新（references/namespace-updates.md）：完整的 XAML 命名空间参考（20+ 控件）、完整的 C# 命名空间参考（20+ 控件）、程序集与包结构变化、真实迁移前后代码示例、命名空间相关构建错误的排查。
• 配置方法迁移（references/method-migration.md）：初始化更新步骤、新旧配置代码对比、完整的 MauiProgram.cs 示例、高级配置选项、初始化问题排查。
• 迁移检查清单（references/migration-checklist.md）：迁移前验证清单、分步迁移流程、迁移后验证清单、常见问题与解决方案、性能验证指南。

使用方式

迁移的核心是命名空间替换，组件用法本身不变。典型示例如下：

XAML 迁移前：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:button="clr-namespace:Syncfusion.Maui.Buttons;assembly=Syncfusion.Maui.Buttons"> <VerticalStackLayout> <button:SfButton Text="Click Me" Clicked="OnButtonClicked" /> </VerticalStackLayout> </ContentPage>

XAML 迁移后：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:button="clr-namespace:Syncfusion.Maui.Toolkit.Buttons;assembly=Syncfusion.Maui.Toolkit"> <VerticalStackLayout> <button:SfButton Text="Click Me" Clicked="OnButtonClicked" /> </VerticalStackLayout> </ContentPage>

MauiProgram.cs 迁移前：

using Syncfusion.Maui.Core.Hosting;

var builder = MauiApp.CreateBuilder(); builder .UseMauiApp<App>() .ConfigureFonts(fonts => fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular")) .ConfigureSyncfusionCore();

return builder.Build();

MauiProgram.cs 迁移后：

using Syncfusion.Maui.Toolkit.Hosting;

var builder = MauiApp.CreateBuilder(); builder .UseMauiApp<App>() .ConfigureFonts(fonts => fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular")) .ConfigureSyncfusionToolkit();

return builder.Build();

代码隐藏文件迁移前：

using Syncfusion.Maui.Buttons;

迁移后：

using Syncfusion.Maui.Toolkit.Buttons;

变更摘要：

• XAML 命名空间：Syncfusion.Maui.Buttons → Syncfusion.Maui.Toolkit.Buttons
• XAML 程序集：Syncfusion.Maui.Buttons → Syncfusion.Maui.Toolkit
• C# using：Syncfusion.Maui.Buttons → Syncfusion.Maui.Toolkit.Buttons
• 配置方法：ConfigureSyncfusionCore() → ConfigureSyncfusionToolkit()
• MauiProgram.cs using：Syncfusion.Maui.Core.Hosting → Syncfusion.Maui.Toolkit.Hosting
• 组件用法：无变化，SfButton 行为完全一致

常见迁移模式包括：

• 模式 1：单页面多组件——更新所有命名空间声明。例如将 button、calendar、cards 的命名空间分别改为 Syncfusion.Maui.Toolkit.Buttons、Syncfusion.Maui.Toolkit.Calendar、Syncfusion.Maui.Toolkit.Cards，程序集统一为 Syncfusion.Maui.Toolkit。
• 模式 2：代码隐藏多组件——更新所有 using 语句。
• 模式 3：条件组件使用或在视图模型中使用——同样更新所有命名空间声明。

关键迁移原则

1. 基于命名空间的迁移：所有变更围绕命名空间，组件 API、属性、事件签名几乎不变。
2. 单一程序集合并：不再安装独立组件包，改为安装单一 Syncfusion.Maui.Toolkit NuGet 包。
3. 最小代码改动：现有代码逻辑与实现模式无需修改，仅更新命名空间声明与程序集引用。
4. 一次性初始化更新：在应用启动时更新一次 MauiProgram.cs，所有组件自动使用新工具包。
5. 完全向后兼容：组件功能、属性、事件与行为完全保留，无需功能变更。

适用场景

适用于正在使用 Syncfusion® .NET MAUI 组件、并希望迁移到 Syncfusion® Toolkit for .NET MAUI 的项目。根据资料，多数开发者可在 30-60 分钟内完成迁移，具体取决于项目规模。

限制

资料未提供具体的 NuGet 包版本号、支持的 .NET 版本、各组件命名空间映射的完整清单细节，以及性能基准数据。迁移前建议先阅读入门指南确认前置条件，使用命名空间参考识别项目中的全部组件，按检查清单逐步迁移，并在迁移后充分测试应用。