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 への移行では、主に次の 3 点が変更されます。

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：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. 初期化の更新は 1 回のみ

アプリケーションの起動時に MauiProgram.cs を 1 回更新します。その後は、すべてのコンポーネントで新しいツールキットが自動的に使用されます。

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. MauiProgram.cs の更新については、references/method-migration.md を参照してください
5. 移行後、アプリケーションを十分にテストしてください

移行がうまくいくことを願っています！手順は簡単で、プロジェクトの規模にもよりますが、ほとんどの開発者は 30～60 分で完了します。