syncfusion-maui-toolkit-migration

迁移指南：从 Syncfusion® .NET MAUI 迁移到 Syncfusion® Toolkit for .NET MAUI

Syncfusion® Toolkit for .NET MAUI 代表了面向 MAUI 应用的新一代 Syncfusion® 组件。虽然大多数 API 和功能保持不变，但组件已整合到一个工具包中，并更新了命名空间。本指南将帮助你以最少的代码修改，将现有的 Syncfusion® .NET MAUI 项目迁移到新工具包。

目录

• 概述
• 文档与导航指南
• 快速入门示例
• 常见迁移模式
• 关键迁移原则

概述

从 Syncfusion® .NET MAUI 迁移到 Syncfusion® Toolkit for .NET MAUI 涉及三项主要变更：

1. 命名空间更新 - 组件命名空间已重新整理到 Syncfusion.Maui.Toolkit.* 下
2. 程序集整合 - 各个组件程序集已整合到 Syncfusion.Maui.Toolkit
3. 配置方法 - ConfigureSyncfusionCore() 已重命名为 ConfigureSyncfusionToolkit()

好消息： 现有组件的实现方式几乎完全相同。主要工作是更新命名空间和初始化方法。

文档与导航指南

根据你目前的迁移进度选择迁移路径：

开始使用

📄 阅读： references/getting-started.md

如果你：

• 刚开始迁移
• 需要了解迁移范围和优势
• 想了解前置条件和变更概述
• 正在规划迁移时间表

请从这里开始。

内容包括：

• 迁移到工具包的原因
• 前置条件和要求
• 受影响的组件
• 高层次的变更摘要

命名空间更新

📄 阅读： references/namespace-updates.md

在需要以下操作时阅读：

• 更新 XAML 命名空间声明
• 修改 C# using 语句
• 查找特定组件对应的准确命名空间
• 了解 NuGet 包的程序集变更
• 获取适用于 IDE 的搜索与替换模式

内容包括：

• 完整的 XAML 命名空间参考（20 多个控件）
• 完整的 C# 命名空间参考（20 多个控件）
• 程序集变更和包结构
• 包含迁移前后代码的实际示例
• 排查与命名空间相关的生成错误

配置方法迁移

📄 阅读： references/method-migration.md

在需要以下操作时使用：

• 更新 MauiProgram.cs 初始化
• 将 ConfigureSyncfusionCore() 改为 ConfigureSyncfusionToolkit()
• 了解 AppHostBuilder 配置
• 查看代码隐藏文件的变更
• 检查方法签名变更

内容包括：

• 分步更新初始化设置
• 新旧配置代码对比
• 完整的 MauiProgram.cs 示例
• 高级配置选项
• 排查初始化问题

迁移检查清单

📄 阅读： references/migration-checklist.md

将其用作：

• 迁移前的核对清单
• 分步迁移流程指南
• 迁移后的验证清单
• 常见问题的故障排除参考
• 性能验证指南

内容包括：

• 迁移前的步骤和备份流程
• 组件清单准备
• 分步编号迁移流程
• 生成和测试验证
• 常见问题、解决方案及修复方法
• 迁移完成检查清单

快速入门示例

以下是典型的 XAML 迁移示例。组件本身的用法不变，只需更改命名空间：

迁移前（Syncfusion® .NET MAUI）

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>

C#（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();

C#（代码隐藏文件）：

using Syncfusion.Maui.Buttons;

namespace MigrationApp;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }

    private void OnButtonClicked(object sender, EventArgs e)
    {
        DisplayAlert("Success", "Button clicked!", "OK");
    }
}

之后（Syncfusion® Toolkit for .NET MAUI）

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>

C#（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();

C#（代码隐藏）：

using Syncfusion.Maui.Toolkit.Buttons;

namespace MigrationApp;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }

    private void OnButtonClicked(object sender, EventArgs e)
    {
        DisplayAlert("Success", "Button clicked!", "OK");
    }
}

变更摘要：

• ✅ 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：在一个页面中使用多个组件

如果页面使用了多个 Syncfusion® 组件，请更新所有命名空间声明：

之前：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:button="clr-namespace:Syncfusion.Maui.Buttons;assembly=Syncfusion.Maui.Buttons"
             xmlns:calendar="clr-namespace:Syncfusion.Maui.Calendar;assembly=Syncfusion.Maui.Calendar"
             xmlns:cards="clr-namespace:Syncfusion.Maui.Cards;assembly=Syncfusion.Maui.Cards">

之后：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:button="clr-namespace:Syncfusion.Maui.Toolkit.Buttons;assembly=Syncfusion.Maui.Toolkit"
             xmlns:calendar="clr-namespace:Syncfusion.Maui.Toolkit.Calendar;assembly=Syncfusion.Maui.Toolkit"
             xmlns:cards="clr-namespace:Syncfusion.Maui.Toolkit.Cards;assembly=Syncfusion.Maui.Toolkit">

模式 2：代码隐藏中使用多个组件

在代码隐藏中使用组件时，请更新所有 using 语句：

之前：

using Syncfusion.Maui.Buttons;
using Syncfusion.Maui.Calendar;
using Syncfusion.Maui.Cards;

namespace MyApp;

public partial class ComplexPage : ContentPage
{
    public ComplexPage()
    {
        InitializeComponent();
        var button = new SfButton { Text = "Dynamic" };
        var calendar = new SfCalendar();
    }
}

之后：

using Syncfusion.Maui.Toolkit.Buttons;
using Syncfusion.Maui.Toolkit.Calendar;
using Syncfusion.Maui.Toolkit.Cards;

namespace MyApp;

public partial class ComplexPage : ContentPage
{
    public ComplexPage()
    {
        InitializeComponent();
        var button = new SfButton { Text = "Dynamic" };
        var calendar = new SfCalendar();
    }
}

模式 3：有条件地使用组件

有条件地使用组件或在视图模型中使用组件时，请确保更新所有命名空间声明：

之前：

using Syncfusion.Maui.Buttons;

namespace MyApp.ViewModels;

public class ButtonViewModel
{
    public SfButton CreateButton()
    {
        return new SfButton 
        { 
            Text = "Action",
            BackgroundColor = Colors.Blue
        };
    }
}

之后：

using Syncfusion.Maui.Toolkit.Buttons;

namespace MyApp.ViewModels;

public class ButtonViewModel
{
    public SfButton CreateButton()
    {
        return new SfButton 
        { 
            Text = "Action",
            BackgroundColor = Colors.Blue
        };
    }
}

关键迁移原则

1. 基于命名空间的迁移

所有变更都围绕命名空间展开。组件 API、属性和事件签名几乎完全相同。

2. 整合为单一程序集

无需安装单独的组件包（Syncfusion.Maui.Buttons、Syncfusion.Maui.Calendar 等），只需安装单一的 Syncfusion.Maui.Toolkit NuGet 包。

3. 代码改动最少

现有代码逻辑和实现模式无需更改。只需更新命名空间声明和程序集引用。

4. 一次性更新初始化

在应用启动时更新一次 MauiProgram.cs。之后，所有组件都会自动使用新的 Toolkit。

5. 完全向后兼容

组件功能、属性、事件和行为均得到完整保留。无需更改任何功能。

获取帮助和资源

• 分步指南： 从 references/migration-checklist.md 开始，按照编号步骤操作
• 命名空间参考： 使用 references/namespace-updates.md 查找组件
• 故障排除： 查看 references/migration-checklist.md 了解常见问题
• 配置帮助： 查看 references/method-migration.md 了解初始化详情

后续步骤：

1. 阅读 references/getting-started.md 了解先决条件
2. 使用 references/namespace-updates.md 找出项目中的所有组件
3. 按照 references/migration-checklist.md 逐步完成迁移
4. 参考 references/method-migration.md 更新 MauiProgram.cs
5. 迁移后彻底测试应用程序

祝迁移顺利！整个过程很简单，大多数开发者会在 30-60 分钟内完成，具体时间取决于项目规模。