syncfusion-aspnetcore-query-builder（Synfusion aspnetcore 查询生成器）

Implementing QueryBuilder in ASP.NET Core

The Syncfusion QueryBuilder is a UI component for creating and editing filter conditions visually. Users can define rules and groups, combine them with AND/OR connectors, and export them as JSON, SQL, or MongoDB queries — all using ASP.NET Core TagHelper syntax.

Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• NuGet package installation and TagHelper setup
• CDN stylesheet and script references
• Basic QueryBuilder with columns
• Render with initial Rule (JSON)
• EmployeeView model class example

Column Configuration

📄 Read: references/columns.md

• Auto-generating columns from DataSource
• Labels, field mapping, data types
• Operators table (all supported types)
• Number step and date/number format
• Validation (isRequired, min, max)
• Column-level custom input templates

Data Binding

📄 Read: references/data-binding.md

• Local data binding (JSON array, DataManager)
• Remote data (OData, ODataV4, WebAPI, UrlAdaptor)
• Using getPredicate to filter data
• Grid integration via ruleChange event

Import & Export

📄 Read: references/import-export.md

• Import from JSON (initial Rule / setRules)
• Import from SQL (Inline, Parameter, Named Parameter)
• Import from MongoDB (setMongoQuery)
• Export to JSON (getRules)
• Export to SQL variants and MongoDB

Filtering & Rule Management

📄 Read: references/filtering-and-rules.md

• ShowButtons configuration (ruleDelete, groupInsert, groupDelete, clone, lock)
• addRules / deleteRules / addGroups / deleteGroups methods
• cloneGroup / cloneRule methods
• lockGroup / lockRule methods
• EnableSeparateConnector between rules
• EnableNotCondition for NOT groups

Templates & Appearance

📄 Read: references/templates-and-appearance.md

• Header template customization
• Display mode (Horizontal / Vertical)
• Summary view (collapsed read-only display)
• Model binding (fieldModel, operatorModel, valueModel)
• CSS classes for styling customization

Configuration & How-To

📄 Read: references/configuration-and-how-to.md

• Drag and drop (AllowDragAndDrop, events)
• MaxGroupCount to restrict nested groups
• SortDirection for column field ordering
• EnablePersistence (state saved in localStorage)
• EnableRtl for right-to-left languages
• ReadOnly mode, Width/Height, CssClass
• AutoSelectField, AutoSelectOperator, MatchCase

Localization

📄 Read: references/localization.md

• Setting the Locale property
• Full locale key reference table
• Example: Arabic / RTL localization

API Reference

📄 Read: references/api.md

• Complete properties with types and defaults
• All events with descriptions
• QueryBuilderColumn sub-properties
• QueryBuilderShowButtons sub-properties
• TagHelper attribute naming conventions

Quick Start Example

@* _ViewImports.cshtml must have: @addTagHelper *, Syncfusion.EJ2 *@

<ejs-querybuilder id="querybuilder" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Title" label="Title" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Common Patterns

Render with Initial Rule

@using Syncfusion.EJ2.QueryBuilder
@{
    QueryBuilderRule rule = new QueryBuilderRule()
    {
        Condition = "and",
        Rules = new List<QueryBuilderRule>()
        {
            new QueryBuilderRule { Label = "First Name", Field = "FirstName", Type = "string", Operator = "startswith", Value = "Nancy" },
            new QueryBuilderRule { Label = "Country", Field = "Country", Type = "string", Operator = "equal", Value = "USA" }
        }
    };
    var dataSource = EmployeeView.GetAllRecords();
}
<ejs-querybuilder id="querybuilder" width="70%" rule="rule" dataSource="dataSource">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Export Rules to SQL

var queryBuilder = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);

// Get JSON rules
var jsonRules = queryBuilder.getRules();

// Get Inline SQL
var sql = queryBuilder.getSqlFromRules(jsonRules);

// Get Parameterized SQL
var paramSql = queryBuilder.getParameterizedSql(jsonRules);

Grid Integration with QueryBuilder

// In ruleChange event handler:
function ruleChanged(args) {
    var qryBldrObj = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);
    var gridObj = ej.base.getInstance(document.getElementById("Grid"), ejs.grids.Grid);
    gridObj.query = qryBldrObj.getDataManagerQuery(qryBldrObj.getRules());
    gridObj.refresh();
}

Drag and Drop Enabled

<ejs-querybuilder id="querybuilder" allowDragAndDrop="true" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Key Properties Quick Reference

Common Use Cases

• Data grid filter UI → QueryBuilder + Grid integration via ruleChange
• Save/restore conditions → getRules + setRules with localStorage or backend
• SQL WHERE clause builder → getSqlFromRules / getParameterizedSql
• MongoDB filter → getMongoQuery / setMongoQuery
• Read-only filter display → summaryView="true" + readonly="true"
• Mobile-friendly layout → displayMode="Vertical" + maxGroupCount="2"
• Localized UI → locale property + L10n translation object

Security & Trust Boundary

External Dependency: CDN-Based JavaScript Execution

The Syncfusion QueryBuilder requires runtime execution of external JavaScript from the official CDN endpoint (https://cdn.syncfusion.com/ej2/*/dist/ej2.min.js). This is a required trusted dependency with the following security considerations:

Risk Mitigation Strategies

1. Use HTTPS Only

- Always reference CDN resources via HTTPS to prevent man-in-the-middle attacks - Verify your layout template uses https:// scheme

1. Subresource Integrity (SRI) <script src="https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js" integrity="sha384-[HASH]" crossorigin="anonymous"></script>

- Include SRI hash attributes to validate script integrity:

1. Content Security Policy (CSP) script-src 'self' https://cdn.syncfusion.com; style-src 'self' https://cdn.syncfusion.com;

- Add Syncfusion CDN to your CSP whitelist:

1. Vendor Lock & Trust Assessment

- Trusted Vendor: Syncfusion is an established commercial component vendor with industry adoption - No Open-Source Alternatives: QueryBuilder functionality is specialized; evaluate internal development costs vs. vendor dependency - Consider Bundling: For enhanced control, bundle Syncfusion scripts locally instead of using CDN (download and host on your own domain)

1. Version Pinning ❌ https://cdn.syncfusion.com/ej2/latest/dist/ej2.min.js ✅ https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js

- Always pin the specific version instead of using wildcard versions:

1. Update Management

- Regularly update Syncfusion NuGet packages and verify corresponding CDN versions match - Subscribe to Syncfusion security announcements - Test updates in staging environment before production deployment

Acceptable Risk Assessment

• Severity: Medium (requires trust boundary evaluation at deployment)
• Mitigation: Implement SRI + CSP + version pinning
• Approval: Obtain security team sign-off for use in compliant applications

Start here: Read references/getting-started.md to set up your first QueryBuilder.