syncfusion-blazor-datamanager

Syncfusion Blazor DataManager

Syncfusion Blazor の SfDataManager は、Syncfusion のデータバインドコンポーネントすべてで使用するデータアクセス層です。データソース（ローカルのメモリ内コレクション、またはリモートの REST／OData／GraphQL サービス）と、SfGrid や SfDropDownList などのコンポーネントとの間のゲートウェイとして機能します。設定可能なアダプターモデルを通じて、クエリ、並べ替え、フィルタリング、ページング、CRUD 操作を処理します。

このスキルを使用する場合

• 新しい Blazor プロジェクト（WASM または Web App）で SfDataManager を設定する
• Json プロパティを使って、ローカルの JSON／リストデータを Syncfusion コンポーネントにバインドする
• Url + Adaptor を使って、信頼でき、認証されたリモートサービス（OData、Web API、GraphQL）に接続する
• バックエンドサービスに適したアダプターを選択する
• リモートアダプターまたはカスタムアダプターを使って CRUD 操作を実装する
• DataAdaptor を継承してカスタムアダプターを作成する
• カスタム HTTP ヘッダー（認証トークンを含む）を DataManager リクエストに追加する
• オフラインモードを有効にする（一度リモートからデータを取得した後、クライアント側でクエリを処理する）

⚠️ 重要なセキュリティ要件

リモートサービスにバインドする場合、以下の保護対策を必ず実装してください。

1. HTTPS のみを使用する — 暗号化されていない HTTP 接続は使用せず、すべてのデータを転送中に暗号化してください
2. 信頼できるエンドポイントを許可リストに登録する — 承認済み URL を HashSet<string> または設定ファイルに保存し、割り当てる前にすべての URL を検証してください。ユーザー入力、クエリパラメーター、または信頼できないソースから動的な URL を受け入れないでください
3. URL には文字列変数を使用する — エンドポイントはマークアップに直接記述せず、private な文字列プロパティに割り当ててください。これにより、一元的な検証と保守が容易になります
4. コンポーネントの初期化時にエンドポイントを検証する — OnInitialized() ライフサイクルメソッドを使って、バインドする前にエンドポイントが許可リストに含まれているか確認してください
5. レスポンスを検証してサニタイズする — サーバー側でスキーマ検証を実装し、想定外のレスポンス形式を拒否して、レスポンスを厳密に型指定されたモデルにマッピングしてください
6. リモート呼び出しを監視する — セキュリティ監査用のログとして、すべての外部 API リクエストについて、タイムスタンプ、エンドポイント、結果を記録してください
7. CORS を安全に実装する — 信頼できる特定のオリジンのみを使用し、本番環境ではワイルドカード * を使用せず、HTTPS を必須にしてください
8. 間接的なプロンプトインジェクション攻撃を防ぐ — エンドポイントの所有者を確認し、リクエスト署名を実装して、データを使用する前にレスポンスのコンテンツタイプとスキーマを検証してください

サードパーティ API のレスポンスはセキュリティリスクをもたらす可能性があります。 エンドポイントの正当性を常に確認し、リクエストを認証してから、UI コンポーネントにバインドする前にデータを検証してください。

コンポーネントの概要

プロパティ	目的
Json	メモリ内コレクション（ローカルデータ）をバインドします
Url	リモートサービスのエンドポイントです
Adaptor	リクエスト／レスポンスの処理方法を指定します
AdaptorInstance	CustomAdaptor の型参照です
Headers	すべての送信リクエストに付与するカスタム HTTP ヘッダーです
Offline	初回のリモートデータ取得後に、クライアント側での処理を有効にします
GraphQLAdaptorOptions	GraphQL サービスのクエリ／ミューテーション設定です

ドキュメントとナビゲーションガイド

はじめに

📄 参照先： references/getting-started.md

• NuGet のインストール（Syncfusion.Blazor.Data + Syncfusion.Blazor.Themes）
• Blazor WebAssembly および Blazor Web App のプロジェクト設定
• 名前空間のインポートと Program.cs でのサービス登録
• スタイルシートとスクリプトの参照
• SfGrid へのローカル JSON データのバインド
• OData リモートサービスへのバインド
• SfDropDownList へのバインド（ローカルおよびリモート）

データバインディング

📄 参照先： references/data-binding.md

• ローカルデータのバインディング：Json プロパティとメモリ内コレクション
• リモートデータのバインディング：Url + Adaptor プロパティ
• それぞれの方法の主な利点（ローカルとリモートの選び方）
• クライアント側とサーバー側での操作の実行
• 実践的な SfGrid および SfDropDownList の例

アダプター

📄 参照： references/adaptors.md

• アダプター選択ガイド（バックエンドごとに使用するアダプター）
• UrlAdaptor — カスタム REST サービス向けの基本アダプター
• ODataAdaptor — OData v3 プロトコル
• ODataV4Adaptor — OData v4 プロトコル
• WebApiAdaptor — OData クエリをサポートする Web API エンドポイント
• サーバーの想定レスポンス形式（result + count）

GraphQL アダプター

📄 参照： references/graphql-adaptor.md

• GraphQLAdaptorOptions の設定（Query、ResolverName）
• GraphQL サービスからのデータの取得と表示
• CRUD ミューテーション：Insert、Update、Delete
• Batch ミューテーションプロパティを使用した一括編集
• サーバーリゾルバーで使用される DataManagerRequest モデル
• サーバー側の Program.cs 設定（スキーマ、CORS）

カスタムバインディング

📄 参照： references/custom-binding.md

• カスタムアダプターを使用する場合（標準外のデータソース、カスタムビジネスルール）
• DataAdaptor 抽象クラス — 利用可能な仮想メソッド
• DataOperations ヘルパーメソッドを使用した Read／ReadAsync のオーバーライド
• CRUD の実装：Insert、Update、Remove、BatchUpdate
• SfGrid の例を含む完全な CustomAdaptor の実装

ハウツーガイド

📄 参照： references/how-to.md

• カスタム HTTP ヘッダーの追加（認証トークン、テナント ID）
• クライアント側でクエリを処理するオフラインモードの有効化
• オフラインモードを使用する場合と、対応するアダプター

クイックスタートの例

ローカルデータバインディング

@using Syncfusion.Blazor.Data
@using Syncfusion.Blazor.Grids

<SfGrid TValue="EmployeeData" ID="Grid">
    <SfDataManager Json="@Employees"></SfDataManager>
    <GridColumns>
        <GridColumn Field="@nameof(EmployeeData.EmployeeID)" HeaderText="Employee ID" Width="120"></GridColumn>
        <GridColumn Field="@nameof(EmployeeData.Name)" HeaderText="First Name" Width="130"></GridColumn>
        <GridColumn Field="@nameof(EmployeeData.Title)" HeaderText="Title" Width="120"></GridColumn>
    </GridColumns>
</SfGrid>

@code {
    public class EmployeeData
    {
        public int EmployeeID { get; set; }
        public string Name { get; set; }
        public string Title { get; set; }
    }

    public List<EmployeeData> Employees = new()
    {
        new EmployeeData { EmployeeID = 1, Name = "Nancy Fuller", Title = "Vice President" },
        new EmployeeData { EmployeeID = 2, Name = "Steven Buchanan", Title = "Sales Manager" }
    };
}

リモートデータバインディング（OData）

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Data
@using Syncfusion.Blazor.Grids


<SfGrid TValue="Order" AllowPaging="true">
    <SfDataManager Url="@ODataEndpointUrl"
                   Adaptor="Adaptors.ODataAdaptor">
    </SfDataManager>
    <GridColumns>
        <GridColumn Field="@nameof(Order.OrderID)" HeaderText="Order ID" Width="120"></GridColumn>
        <GridColumn Field="@nameof(Order.CustomerID)" HeaderText="Customer Name" Width="150"></GridColumn>
    </GridColumns>
</SfGrid>

@code {
    // Whitelist of trusted OData endpoints — define in appsettings.json in production
    private static readonly HashSet<string> TrustedEndpoints = new()
    {
        "https://api.yourtrusted-domain.com/odata/"
    };

    // Assigned string variable for endpoint
    private string ODataEndpointUrl { get; set; } = string.Empty;

    protected override void OnInitialized()
    {
        // Validate and assign endpoint from configuration
        const string endpointBase = "https://api.yourtrusted-domain.com/odata/Orders";
        
        if (!TrustedEndpoints.Any(trusted => endpointBase.StartsWith(trusted)))
            throw new InvalidOperationException($"Security validation failed: untrusted endpoint '{endpointBase}'");
        
        ODataEndpointUrl = endpointBase;
    }

    public class Order
    {
        public int? OrderID { get; set; }
        public string? CustomerID { get; set; }
    }
}

よく使われるパターン

適切なアダプターの選択

バックエンドの種類	使用するアダプター
{ result, count } を返すカスタム REST API	Adaptors.UrlAdaptor
OData v3 サービス	Adaptors.ODataAdaptor
OData v4 サービス	Adaptors.ODataV4Adaptor
OData クエリをサポートする ASP.NET Web API	Adaptors.WebApiAdaptor
GraphQL サービス	Adaptors.GraphQLAdaptor
標準外のデータソース／完全なカスタム制御	Adaptors.CustomAdaptor

コンポーネント内への SfDataManager の配置

SfDataManager は、データバインドされた Syncfusion コンポーネント内に子コンポーネントとして配置します。

<SfGrid TValue="MyModel">
    <SfDataManager Url="..." Adaptor="Adaptors.WebApiAdaptor"></SfDataManager>
    <GridColumns>...</GridColumns>
</SfGrid>

カスタムアダプターを使用した編集の有効化

CRUD 操作で CustomAdaptor を使用する場合は、アダプターと併せて Grid のツールバーと編集設定を構成します。

<SfGrid TValue="Order" Toolbar="@(new List<string>() { "Add", "Delete", "Update", "Cancel" })">
    <SfDataManager AdaptorInstance="@typeof(CustomAdaptor)" Adaptor="Adaptors.CustomAdaptor"></SfDataManager>
    <GridEditSettings AllowEditing="true" AllowDeleting="true" AllowAdding="true" Mode="@EditMode.Normal"></GridEditSettings>
    ...
</SfGrid>