syncfusion-aspnetcore-query-builder

ASP.NET Core での QueryBuilder の実装

Syncfusion QueryBuilder は、フィルター条件を視覚的に作成・編集するための UI コンポーネントです。ユーザーは、ルールとグループを定義し、AND/OR コネクターで組み合わせて、JSON、SQL、MongoDB のクエリとしてエクスポートできます。すべて ASP.NET Core の TagHelper 構文を使用して操作できます。

ナビゲーションガイド

はじめに

📄 読む: references/getting-started.md

• NuGet パッケージのインストールと TagHelper の設定
• CDN のスタイルシートとスクリプトの参照
• 列を含む基本的な QueryBuilder
• 初期 Rule（JSON）を指定してレンダリング
• EmployeeView モデルクラスの例

列の設定

📄 読む: references/columns.md

• DataSource からの列の自動生成
• ラベル、フィールドのマッピング、データ型
• 演算子の表（サポートされるすべての型）
• 数値のステップと日付／数値の形式
• 検証（isRequired、min、max）
• 列レベルのカスタム入力テンプレート

データバインディング

📄 読む: references/data-binding.md

• ローカルデータバインディング（JSON 配列、DataManager）
• リモートデータ（OData、ODataV4、WebAPI、UrlAdaptor）
• getPredicate を使用したデータのフィルタリング
• ruleChange イベントによる Grid との連携

インポートとエクスポート

📄 読む: references/import-export.md

• JSON からのインポート（初期 Rule／setRules）
• SQL からのインポート（Inline、Parameter、Named Parameter）
• MongoDB からのインポート（setMongoQuery）
• JSON へのエクスポート（getRules）
• 各種 SQL 形式および MongoDB へのエクスポート

フィルタリングとルール管理

📄 読む: references/filtering-and-rules.md

• ShowButtons の設定（ruleDelete、groupInsert、groupDelete、clone、lock）
• addRules／deleteRules／addGroups／deleteGroups メソッド
• cloneGroup／cloneRule メソッド
• lockGroup／lockRule メソッド
• ルール間での EnableSeparateConnector
• NOT グループの EnableNotCondition

テンプレートと外観

📄 読む: references/templates-and-appearance.md

• ヘッダーテンプレートのカスタマイズ
• 表示モード（Horizontal／Vertical）
• サマリービュー（折りたたまれた読み取り専用表示）
• モデルバインディング（fieldModel、operatorModel、valueModel）
• スタイル設定用の CSS クラス

設定と使い方

📄 読む: references/configuration-and-how-to.md

• ドラッグ＆ドロップ（AllowDragAndDrop、イベント）
• MaxGroupCount によるネストされたグループの制限
• 列フィールドの並べ替えに使用する SortDirection
• EnablePersistence（状態を localStorage に保存）
• 右から左に記述する言語向けの EnableRtl
• ReadOnly モード、Width／Height、CssClass
• AutoSelectField、AutoSelectOperator、MatchCase

ローカライズ

📄 読む: references/localization.md

• Locale プロパティの設定
• ロケールキーの完全な一覧表
• 例：アラビア語／RTL のローカライズ

API リファレンス

📄 読む: references/api.md

• 型とデフォルト値を含むすべてのプロパティ
• 説明付きのすべてのイベント
• QueryBuilderColumn のサブプロパティ
• QueryBuilderShowButtons のサブプロパティ
• TagHelper 属性の命名規則

クイックスタートの例

@* _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>

よく使われるパターン

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

ルールを 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);

QueryBuilder と Grid の連携

// 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();
}

ドラッグ＆ドロップを有効化

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

主要プロパティのクイックリファレンス

プロパティ	TagHelper 属性	目的
Columns	e-querybuilder-columns	フィルター可能なフィールドを定義します
Rule	rule="rule"	初期ルール — C# QueryBuilderRule オブジェクト
DataSource	dataSource	ローカル／リモートのデータをバインドします
AllowDragAndDrop	allowDragAndDrop	ルールの並べ替えを有効にします
AllowValidation	allowValidation	ルールの入力を検証します
EnableSeparateConnector	enableSeparateConnector	ルールごとに AND／OR コネクターを設定します
EnableNotCondition	enableNotCondition	NOT グループ演算子
MaxGroupCount	maxGroupCount	ネストできるグループの深さを制限します
SummaryView	summaryView	折りたたまれたルールの概要を表示します
DisplayMode	displayMode	水平または垂直のレイアウト
EnablePersistence	enablePersistence	状態を localStorage に保存します
EnableRtl	enableRtl	右から左へのレイアウト
SortDirection	sortDirection	列フィールドのリストを並べ替えます
Readonly	readonly	すべての操作を無効にします
Width / Height	width / height	コンポーネントの寸法

よくあるユースケース

• データグリッドのフィルター UI → ruleChange を介した QueryBuilder と Grid の連携
• 条件の保存／復元 → localStorage またはバックエンドと組み合わせた getRules + setRules
• SQL WHERE 句ビルダー → getSqlFromRules / getParameterizedSql
• MongoDB フィルター → getMongoQuery / setMongoQuery
• 読み取り専用のフィルター表示 → summaryView="true" + readonly="true"
• モバイル向けレイアウト → displayMode="Vertical" + maxGroupCount="2"
• ローカライズされた UI → locale プロパティ + L10n 翻訳オブジェクト

セキュリティと信頼境界

外部依存関係：CDN ベースの JavaScript 実行

Syncfusion QueryBuilder では、公式 CDN エンドポイント（https://cdn.syncfusion.com/ej2/*/dist/ej2.min.js）からの外部 JavaScript をランタイムに実行する必要があります。これは必須の信頼された依存関係であり、以下のセキュリティ上の考慮事項があります。

リスク軽減策

1. HTTPS のみを使用する

   • 中間者攻撃を防ぐため、CDN リソースは常に HTTPS 経由で参照してください
   • レイアウトテンプレートで https:// スキームが使用されていることを確認してください

2. サブリソース整合性（SRI）

   • スクリプトの整合性を検証するため、SRI ハッシュ属性を含めてください：

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

3. コンテンツセキュリティポリシー（CSP）

   • Syncfusion CDN を CSP の許可リストに追加してください：

   script-src 'self' https://cdn.syncfusion.com;
   style-src 'self' https://cdn.syncfusion.com;
   

4. ベンダーロックインと信頼性の評価

   • 信頼できるベンダー：Syncfusion は、業界で採用されている実績のある商用コンポーネントベンダーです
   • オープンソースの代替手段なし：QueryBuilder の機能は専門性が高いため、社内開発コストとベンダーへの依存を比較評価してください
   • バンドルを検討する：管理性を高めるには、CDN を使わずに Syncfusion スクリプトをローカルにバンドルしてください（ダウンロードして自社ドメインでホストします）

5. バージョンの固定

   • ワイルドカードバージョンではなく、必ず特定のバージョンを固定してください：

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

6. 更新管理

   • Syncfusion の NuGet パッケージを定期的に更新し、対応する CDN バージョンと一致していることを確認してください
   • Syncfusion のセキュリティに関するお知らせを購読してください
   • 本番環境にデプロイする前に、ステージング環境で更新をテストしてください

許容可能なリスク評価

• 深刻度：中（デプロイ時に信頼境界の評価が必要です）
• 軽減策：SRI + CSP + バージョン固定を実施します
• 承認：コンプライアンス要件のあるアプリケーションで使用する場合は、セキュリティチームの承認を得てください

---

まずはこちらから： 最初の QueryBuilder をセットアップするには、references/getting-started.md をお読みください。