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 创建自定义适配器
• 为 DataManager 请求添加自定义 HTTP 标头（包含身份验证令牌）
• 启用离线模式（一次性远程获取后在客户端处理查询）

⚠️ 关键安全要求

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

1. 仅使用 HTTPS — 切勿使用未加密的 HTTP 连接；加密所有传输中的数据
2. 将可信端点列入白名单 — 将获准的 URL 存储在 HashSet<string> 或配置文件中；在分配前验证所有 URL；切勿接受来自用户输入、查询参数或不可信来源的动态 URL
3. 使用字符串变量存储 URL — 将端点分配给私有字符串属性，而不是硬编码在标记中；这样便于集中验证和维护
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
• 完整的 CustomAdaptor 实现及 SfGrid 示例

操作指南

📄 阅读： 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>

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

使用 CustomAdaptor 执行 CRUD 操作时，请同时配置 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>