Active Query Builder support area

Getting started with AQB 3 ASP.NET Edition in WebForms

Last modified:

Dashboard Quick Start


Lots of demo projects illustrating various aspects of the functionality and different usage scenarios are shipped within the trial installation package. They can also be downloaded from the Active Query Builder 3 ASP.NET Examples GitHub repositories.


Note: if you use the previous major version in your projects, read the Migration Guide first.


Follow the steps below to embed Active Query Builder ASP.NET Edition to your project. 



Add the ActiveQueryBuilder.Web.WebForms NuGet package to your project OR add references to the following assemblies:

  • \assemblies\ActiveQueryBuilder.Core.dll
  • \assemblies\ActiveQueryBuilder.Web.Server.dll
  • \assemblies\ActiveQueryBuilder.Web.WebForms.dll
  • \third-party\Newtonsoft.Json.dll

Active Query Builder requires Newtonsoft.Json assembly version 6.0 or higher. You can get it by installing the Newtonsoft.Json NuGet package or download it directly from the Newtonsoft JSON website.

You may also need to add one or more assemblies to get connected to your database(s) to retrieve metadata from it, e.g.:

  • \assemblies\ActiveQueryBuilder.OLEDBMetadataProvider.dll

The whole list of supported database connectivity packages and appropriate connectors can be found here.

Is it necessary to set the CopyLocal property of "ActiveQueryBuilder.*" assemblies to True.


Embedding Visual Query Builder

  1. Typical ASPX code can be taken from this article or found in the demo projects for your development environment.

    <%@ Register TagPrefix="AQB" Namespace="ActiveQueryBuilder.Web.WebForms" Assembly="ActiveQueryBuilder.Web.WebForms" %>
    <asp:Content ID="BodyContent" ContentPlaceHolderID="MainContent" runat="server">
    <AQB:QueryBuilderControl ID="QueryBuilderControl1" runat="server" />
    <div class="qb-ui-layout">
        <div class="qb-ui-layout__top">
            <div class="qb-ui-layout__left">
                <AQB:ObjectTreeView runat="server" ID="ObjectTreeView1" />
            <div class="qb-ui-layout__right">
                <AQB:SubQueryNavigationBar runat="server" ID="SubQueryNavigationBar1" />
                <AQB:Canvas runat="server" ID="Canvas1" />
                <AQB:StatusBar runat="server" ID="StatusBar1" />
                <AQB:Grid runat="server" ID="Grid1" />
        <div class="qb-ui-layout__bottom">
            <AQB:SqlEditor runat="server" ID="SqlEditor1" />


  2. Get or create an instance of the QueryBuilder object in the Page_Load event handler, assign it to user controls. While creating a new instance of it, initialize the MetadataProvider and SyntaxProvider properties with proper objects. Define a proper database connection object as a source for the MetadataProvider or load metadata from the XML file.

    using ActiveQueryBuilder.Web.Server.Infrastructure;
    using ActiveQueryBuilder.Core;
    using ActiveQueryBuilder.Web.Server;
    public partial class SimpleOLEDBDemo : Page
        // Professional version feature: if you want to let the user simultaneously 
        // build several queries, you must assign different instance ids to them.
        // In the Standard version, this parameter is ignored.
        private string instanceId = "SimpleClient";
        protected void Page_Load(object sender, EventArgs e)
            // Get an instance of the QueryBuilder object
            var qb = QueryBuilderStore.GetOrCreate(instanceId, InitializeQueryBuilder);
            QueryBuilderControl1.QueryBuilder = qb;
            ObjectTreeView1.QueryBuilder = qb;
            Canvas1.QueryBuilder = qb;
            Grid1.QueryBuilder = qb;
            SubQueryNavigationBar1.QueryBuilder = qb;
            SqlEditor1.QueryBuilder = qb;
            StatusBar1.QueryBuilder = qb;
        private void InitializeQueryBuilder(QueryBuilder queryBuilder)
            // Turn this property on to suppress parsing error messages when user types a non-SELECT statement.
            queryBuilder.BehaviorOptions.AllowSleepMode = false;
            // Assign an instance of the syntax provider which defines SQL syntax and metadata retrieval rules.
            queryBuilder.SyntaxProvider = new MSAccessSyntaxProvider();
            // ==== The 1st way: ==================================
            // Bind Active Query Builder to a live database connection.
            queryBuilder.MetadataProvider = new OLEDBMetadataProvider
                // Assign an instance of DBConnection object to the Connection property.
                // In this demo: create a new instance of OLEDBConnection for the "Northwind.mdb" MS Access database.
                Connection = new OleDbConnection(
                    "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\\Northwind.mdb;Persist Security Info=False;") 
            // ==== The 2nd way: ==================================
            // Load MetaData from the pre-generated XML file.
            // Denies metadata loading requests during the work session.
            queryBuilder.MetadataLoadingOptions.OfflineMode = true;
            // ====================================================
            // Assign the initial SQL query text the user sees on the _first_ page load
            queryBuilder.SQL = @"Select o.Order_ID, c.ID As a1, c.First_Name, s.ID
                    From Orders o Inner Join
                        Customers c On o.Customer_ID = c.ID Inner Join
                        Shippers s On s.ID = o.Shipper_ID
                    Where o.Ship_City = 'A'";


Embedding Criteria Builder in your data browsing UI

The QueryTransformer component and the accompanying CriteriaBuilder visual control let build a full-featured user interface to browse query result data. Note that Active Query Builder doesn't provide any means to display data as there are plenty of free and paid controls that can cope better with this task. Active Query Builder can be easily integrated with most of these controls providing the flexibility you need.

Please read the QueryTransformer and CriteriaBuilder guides for details.

  1. Add the CriteriaBuilder control to the page. You can place it on the same page with the QueryBuilder control or on a separate page.

    <AQB:CriteriaBuilder ID="CriteriaBuilder1" runat="server" />


  2. Add the following initialization code in the Page_Load method:

        protected void Page_Load(object sender, EventArgs e)
            // Get an instance of the QueryBuilder object
            var qb = QueryBuilderStore.Get(instanceId, InitializeQueryBuilder); // see the previous code sample for the implementation
            // Get an instance of the QueryTransformer object
            var qt = QueryTransformerStore.GetOrCreate(instanceId, q =>
                    q.QueryProvider = qb.SQLQuery;
                    q.AlwaysExpandColumnsInQuery = true;
            // assign an instance of the QueryTransformer to the same named CriteriaBuilder property
            criteriaBuilder1.QueryTransformer = qt;


  3. Handle CriteriaBuilder events to integrate it with your data grid:

            $(function () {
            function subscribeToChanges(cb) {
                createGrid(); // user proc to create or initialize grid
                cb.on(cb.Events.AfterSyncCriteriaBuilder, function () {
                      updateGridColumns(cb.columns); // user proc to update list of query columns
                      updateGridData(); // user proc to update grid data
                cb.loadColumns(); // trigger the initial query columns loading
                // request data from the server when the user changes the filter
                    function () {
                        onCriteriaBuilderChanged(cb, updateGridData); 
            function onCriteriaBuilderChanged(cb, callback) {
                // check if there aren't any incomplete conditions in the CriteriaBuilder
                if (cb.isValid()) {
                    // send the control state to the server to update the query
                    cb.transformSql(function () { 
                        callback(); // a callback to use (usually run) the transformed query


  4. The updateGridData procedure should perform the AJAX request to the server which will execute the query read from the QueryTransformer.SQL property and return data to the client. Make sure to properly handle SQL query execution errors.

  5. You can also let users change sorting, apply grouping and aggregations, calculate totals and paginate the resultset in your data browsing UI using the QueryTransformer API.

See the Query Results demo project for details (included in the installation package and available on GitHub).


What to read next?

Is this article helpful for you?