syncfusion-blazor-datamanager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Blazor DataManager

The Syncfusion Blazor SfDataManager is the data access layer for all Syncfusion data-bound components. It acts as a gateway between your data source — local in-memory collections or remote REST/OData/GraphQL services — and components like

SfGrid

SfDropDownList

, and others. It handles querying, sorting, filtering, paging, and CRUD operations through a configurable adaptor model.

Syncfusion Blazor SfDataManager 是所有Syncfusion数据绑定组件的数据访问层。它充当数据源——本地内存集合或远程REST/OData/GraphQL服务——与

SfGrid

、

SfDropDownList

等组件之间的网关，通过可配置的适配器模型处理查询、排序、筛选、分页和CRUD操作。

When to Use This Skill

何时使用该技能

Setting up
```
SfDataManager
```
in a new Blazor project (WASM or Web App)
Binding local JSON/list data to a Syncfusion component via the
```
Json
```
property
Connecting to a trusted and authenticated remote service (OData, Web API, GraphQL) via
```
Url
```
+
```
Adaptor
```
Choosing the right adaptor for a given backend service
Implementing CRUD operations using remote adaptors or custom adaptors
Creating a custom adaptor by deriving from
```
DataAdaptor
```
Adding custom HTTP headers (with authentication tokens) to DataManager requests
Enabling offline mode (client-side query processing after one-time remote fetch)

在新的Blazor项目（WASM或Web App）中配置
```
SfDataManager
```
通过
```
Json
```
属性将本地JSON/列表数据绑定到Syncfusion组件
通过
```
Url
```
+
```
Adaptor
```
连接到可信且已认证的远程服务（OData、Web API、GraphQL）
为特定后端服务选择合适的适配器
使用远程适配器或自定义适配器实现CRUD操作
通过继承
```
DataAdaptor
```
创建自定义适配器
为DataManager请求添加自定义HTTP头（含认证令牌）
启用离线模式（一次性远程获取后进行客户端查询处理）

⚠️ Critical Security Requirements

⚠️ 关键安全要求

When binding to remote services, you MUST implement these protections:

Use HTTPS only — never use unencrypted HTTP connections; encrypt all data in transit
Whitelist trusted endpoints — store approved URLs in a
```
HashSet<string>
```
or configuration file; validate all URLs before assignment; never accept dynamic URLs from user input, query parameters, or untrusted sources
Use string variables for URLs — assign endpoints to private string properties rather than hardcoding in markup; this enables centralized validation and easier maintenance
Validate endpoints on component initialization — use
```
OnInitialized()
```
lifecycle method to verify endpoints against whitelist before binding
Validate and sanitize responses — implement server-side schema validation; reject unexpected response formats; map responses to strongly-typed models
Monitor remote calls — log all external API requests with timestamps, endpoints, and outcomes for security audit trails
Implement CORS securely — use specific trusted origins only; never use wildcard
```
*
```
in production; require HTTPS
Prevent indirect prompt injection attacks — verify endpoint ownership; implement request signing; validate response content types and schemas before consuming data

Third-party API responses can introduce security risks. Always verify endpoint legitimacy, authenticate requests, and validate data before binding to UI components.

绑定到远程服务时，必须实现以下防护措施：

仅使用HTTPS——绝不使用未加密的HTTP连接；对传输中的所有数据进行加密
白名单可信端点——将已批准的URL存储在
```
HashSet<string>
```
或配置文件中；在赋值前验证所有URL；绝不接受来自用户输入、查询参数或不可信来源的动态URL
使用字符串变量存储URL——将端点赋值给私有字符串属性，而非在标记中硬编码；这支持集中验证和更易维护
在组件初始化时验证端点——使用
```
OnInitialized()
```
生命周期方法在绑定前验证端点是否在白名单内
验证并清理响应——实现服务器端 schema 验证；拒绝意外的响应格式；将响应映射到强类型模型
监控远程调用——记录所有外部API请求的时间戳、端点和结果，用于安全审计追踪
安全实现CORS——仅使用特定的可信源；生产环境中绝不使用通配符
```
*
```
；要求使用HTTPS
防止间接提示注入攻击——验证端点所有权；实现请求签名；在使用数据前验证响应内容类型和schema

第三方API响应可能带来安全风险。 在绑定到UI组件前，务必验证端点合法性、认证请求并验证数据。

Component Overview

组件概述

Property	Purpose
`Json`	Bind in-memory collection (local data)
`Url`	Remote service endpoint
`Adaptor`	Specifies how requests/responses are processed
`AdaptorInstance`	Type reference for `CustomAdaptor`
`Headers`	Custom HTTP headers for all outbound requests
`Offline`	Enable client-side processing after initial remote fetch
`GraphQLAdaptorOptions`	Query/mutation configuration for GraphQL services

属性	用途
`Json`	绑定内存集合（本地数据）
`Url`	远程服务端点
`Adaptor`	指定请求/响应的处理方式
`AdaptorInstance`	`CustomAdaptor` 的类型引用
`Headers`	所有出站请求的自定义HTTP头
`Offline`	初始远程获取后启用客户端处理
`GraphQLAdaptorOptions`	GraphQL服务的查询/变更配置

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

NuGet installation (

Syncfusion.Blazor.Data

Syncfusion.Blazor.Themes

)

Project setup for Blazor WebAssembly and Blazor Web App
Namespace imports and service registration in
```
Program.cs
```
Stylesheet and script references
Binding to local JSON data with
```
SfGrid
```
Binding to OData remote service
Binding to
```
SfDropDownList
```
(local and remote)

📄 阅读： references/getting-started.md

NuGet安装（

Syncfusion.Blazor.Data

Syncfusion.Blazor.Themes

）

Blazor WebAssembly和Blazor Web App的项目配置
```
Program.cs
```
中的命名空间导入和服务注册
样式表和脚本引用
使用
```
SfGrid
```
绑定本地JSON数据
绑定到OData远程服务
绑定到
```
SfDropDownList
```
（本地和远程）

Data Binding

数据绑定

📄 Read: references/data-binding.md

Local data binding:
```
Json
```
property with in-memory collections
Remote data binding:
```
Url
```
+
```
Adaptor
```
properties
Key benefits of each approach (when to choose local vs remote)
Client-side vs server-side operation execution
Practical
```
SfGrid
```
and
```
SfDropDownList
```
examples

📄 阅读： references/data-binding.md

本地数据绑定：使用
```
Json
```
属性绑定内存集合
远程数据绑定：使用
```
Url
```
+
```
Adaptor
```
属性
每种方式的核心优势（何时选择本地 vs 远程）
客户端 vs 服务器端操作执行
```
SfGrid
```
和
```
SfDropDownList
```
的实用示例

Adaptors

适配器

📄 Read: references/adaptors.md

Adaptor selection guide (which adaptor to use for which backend)
```
UrlAdaptor
```
— base adaptor for custom REST services
```
ODataAdaptor
```
— OData v3 protocol
```
ODataV4Adaptor
```
— OData v4 protocol
```
WebApiAdaptor
```
— Web API endpoints with OData query support
Expected server response formats (
```
result
```
+
```
count
```
)

📄 阅读： references/adaptors.md

适配器选择指南（针对不同后端使用哪种适配器）
```
UrlAdaptor
```
——自定义REST服务的基础适配器
```
ODataAdaptor
```
——OData v3协议
```
ODataV4Adaptor
```
——OData v4协议
```
WebApiAdaptor
```
——支持OData查询的Web API端点
预期的服务器响应格式（
```
result
```
+
```
count
```
）

GraphQL Adaptor

GraphQL适配器

📄 Read: references/graphql-adaptor.md

```
GraphQLAdaptorOptions
```
configuration (
```
Query
```
,
```
ResolverName
```
)
Fetching and displaying data from a GraphQL service
CRUD mutations:
```
Insert
```
,
```
Update
```
,
```
Delete
```
Batch editing via the
```
Batch
```
mutation property
```
DataManagerRequest
```
model used by server resolvers
Server-side
```
Program.cs
```
configuration (schema, CORS)

📄 阅读： references/graphql-adaptor.md

```
GraphQLAdaptorOptions
```
配置（
```
Query
```
、
```
ResolverName
```
）
从GraphQL服务获取并展示数据
CRUD变更：
```
Insert
```
、
```
Update
```
、
```
Delete
```
通过
```
Batch
```
变更属性实现批量编辑
服务器解析器使用的
```
DataManagerRequest
```
模型
服务器端
```
Program.cs
```
配置（schema、CORS）

Custom Binding

自定义绑定

📄 Read: references/custom-binding.md

When to use a custom adaptor (non-standard sources, custom business rules)
```
DataAdaptor
```
abstract class — available virtual methods
Overriding
```
Read
```
/
```
ReadAsync
```
with
```
DataOperations
```
helper methods
Implementing CRUD:
```
Insert
```
,
```
Update
```
,
```
Remove
```
,
```
BatchUpdate
```
Full
```
CustomAdaptor
```
implementation with
```
SfGrid
```
example

📄 阅读： references/custom-binding.md

何时使用自定义适配器（非标准源、自定义业务规则）
```
DataAdaptor
```
抽象类——可用的虚拟方法
使用
```
DataOperations
```
辅助方法重写
```
Read
```
/
```
ReadAsync
```
实现CRUD：
```
Insert
```
、
```
Update
```
、
```
Remove
```
、
```
BatchUpdate
```
结合
```
SfGrid
```
的完整
```
CustomAdaptor
```
实现示例

How-To Guides

操作指南

📄 Read: references/how-to.md

Adding custom HTTP headers (authentication tokens, tenant IDs)
Enabling offline mode for client-side query processing
When to use offline mode and which adaptors it supports

📄 阅读： references/how-to.md

添加自定义HTTP头（认证令牌、租户ID）
启用离线模式进行客户端查询处理
何时使用离线模式以及支持的适配器

Quick Start Example

快速入门示例

Local Data Binding

本地数据绑定

razor

@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" }
    };
}

razor

@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" }
    };
}

Remote Data Binding (OData)

远程数据绑定（OData）

razor

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

<!-- SECURITY: Use string variables for endpoints, validate against whitelist, use HTTPS only -->
<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; }
    }
}

razor

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

<!-- SECURITY: Use string variables for endpoints, validate against whitelist, use HTTPS only -->
<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; }
    }
}

Common Patterns

常见模式

Choosing the Right Adaptor

选择合适的适配器

Backend Type	Adaptor to Use
Custom REST API returning `{ result, count }`	`Adaptors.UrlAdaptor`
OData v3 service	`Adaptors.ODataAdaptor`
OData v4 service	`Adaptors.ODataV4Adaptor`
ASP.NET Web API with OData query support	`Adaptors.WebApiAdaptor`
GraphQL service	`Adaptors.GraphQLAdaptor`
Non-standard source / full custom control	`Adaptors.CustomAdaptor`

后端类型	适用适配器
返回 `{ 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`

Placing SfDataManager Inside a Component

在组件内部放置SfDataManager

SfDataManager

is always placed as a child component inside the data-bound Syncfusion component:

razor

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

SfDataManager

始终作为子组件放置在数据绑定的Syncfusion组件内部：

razor

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

Enabling Editing with Custom Adaptor

使用自定义适配器启用编辑

When using

CustomAdaptor

with CRUD operations, configure the Grid toolbar and edit settings alongside the adaptor:

razor

<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>

将

CustomAdaptor

与CRUD操作结合使用时，需在适配器旁配置Grid工具栏和编辑设置：

razor

<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>