syncfusion-blazor-datamanager

Syncfusion Blazor SfDataManager 是 Syncfusion 所有数据绑定组件的数据访问层，充当数据源（本地内存集合或远程 REST/OData/GraphQL 服务）与 SfGrid、SfDropDownList 等组件之间的网关。它通过可配置的适配器模型处理查询、排序、筛选、分页和 CRUD 操作。

用途

SfDataManager 用于在 Blazor 项目中统一管理数据访问与绑定。典型使用场景包括：在新建 Blazor 项目（WASM 或 Web App）中设置 SfDataManager；通过 Json 属性将本地 JSON/列表数据绑定到 Syncfusion 组件；通过 Url + Adaptor 连接可信且经过身份验证的远程服务（OData、Web API、GraphQL）；为给定后端服务选择合适的适配器；使用远程适配器或自定义适配器实现 CRUD 操作；通过派生自 DataAdaptor 创建自定义适配器；为 DataManager 请求添加自定义 HTTP 头（含身份验证令牌）；启用离线模式（一次性远程获取后在客户端处理查询）。

主要能力

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

适配器选择指南：自定义 REST API 返回 { result, count } 使用 Adaptors.UrlAdaptor；OData v3 服务使用 Adaptors.ODataAdaptor；OData v4 服务使用 Adaptors.ODataV4Adaptor；支持 OData 查询的 ASP.NET Web API 使用 Adaptors.WebApiAdaptor；GraphQL 服务使用 Adaptors.GraphQLAdaptor；非标准数据源或需要完全自定义控制时使用 Adaptors.CustomAdaptor。

使用方式

SfDataManager 始终作为数据绑定 Syncfusion 组件的子组件放置。本地数据绑定示例：

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

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

}

使用自定义适配器启用编辑时，需同时配置 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>

文档导航涵盖：入门（NuGet 安装 Syncfusion.Blazor.Data + Syncfusion.Blazor.Themes、项目设置、命名空间导入与 Program.cs 服务注册、样式表与脚本引用、本地 JSON 与 OData 绑定、SfDropDownList 绑定）；数据绑定（本地与远程、客户端与服务端操作执行）；适配器（选择指南、UrlAdaptor、ODataAdaptor、ODataV4Adaptor、WebApiAdaptor、预期服务器响应格式 result + count）；GraphQL 适配器（GraphQLAdaptorOptions 配置 Query/ResolverName、CRUD 变更、批量编辑、DataManagerRequest 模型、服务端 Program.cs 配置）；自定义绑定（DataAdaptor 抽象类、重写 Read/ReadAsync、实现 CRUD、完整 CustomAdaptor 示例）；操作指南（添加自定义 HTTP 头、启用离线模式）。

适用场景

适用于 Blazor Server、WebAssembly 和 Web App 中需要将本地或远程数据绑定到 Syncfusion 数据组件（如 SfGrid、SfDropDownList）的场景，尤其是需要统一处理查询、排序、筛选、分页和 CRUD 操作，或需要对接 OData、Web API、GraphQL 等后端服务时。

限制与安全要求

资料强调远程绑定的关键安全要求：仅使用 HTTPS，绝不使用未加密的 HTTP 连接；白名单可信端点，将批准的 URL 存储在 HashSet<string> 或配置文件中，赋值前验证所有 URL，绝不接受来自用户输入、查询参数或不可信来源的动态 URL；使用字符串变量存储 URL，将端点分配给私有字符串属性而非在标记中硬编码；在组件初始化时通过 OnInitialized() 生命周期方法对照白名单验证端点；验证并清理响应，实施服务端架构验证，拒绝意外响应格式，将响应映射到强类型模型；监控远程调用，记录所有外部 API 请求的时间戳、端点和结果以用于安全审计；安全实施 CORS，仅使用特定的可信来源，生产环境绝不使用通配符 *，要求 HTTPS；防止间接提示注入攻击，验证端点所有权，实施请求签名，在消费数据前验证响应内容类型和架构。第三方 API 响应可能引入安全风险，务必在绑定到 UI 组件前验证端点合法性、对请求进行身份验证并验证数据。

技能介绍