Active Query Builder support area

Getting started with AQB.NET 3 WinForms and WPF Editions

Last modified:

Dashboard Quick Start

There are two ways to embed the third version of Active Query Builder into your project.

  • The first way is suitable for most use cases and available in both the Standard and Professional subscriptions. This way is described below.

  • The second way gives large freedom in organizing the user interface the way you like. It is available in the Professional subscription only.
    It allows for re-organizing the controls inside the QueryBuilder object in a non-standard way. For example, to place the Design Area and the Query Column List on separate tabs, to place the Database Schema Tree on a different form, etc.
    You can learn about it here: Getting started with AQB.NET 3 in the Separated Controls UI or Non-visual mode.


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 .NET Examples GitHub repositories.


There are two or three components you need to use to get started with Active Query Builder: a syntax provider that suits your database server, a metadata provider that suits your DB connection and the QueryBuilder component that encapsulates all visual controls in a single visual control and has everything that user needs to build a query.

  • QueryBuilder is a main visual component. It unites all visual controls along with SQL query building logic controllers, SQL query object model, SQL parsing and generation functionality in a single object.

  • Metadata Provider is a non-visual object to get connected to the database and extract the needed information about database schema. There are special metadata providers for various .NET DB providers. This object is only needed if you work with the live database connection.

  • Syntax Provider is a non-visual object that determines syntax rules to build correct queries for different SQL dialects. There are lots of supported SQL syntaxes for most popular database servers today, as well as for generic ANSI-compatible SQL language. This object is necessary.

You can read more about Metadata and Syntax Providers here.

Follow the steps below to embed Active Query Builder to your application.

  1. Place the QueryBuilder component on the form.

    using ActiveQueryBuilder.Core;
    using ActiveQueryBuilder.View.WPF; // or ActiveQueryBuilder.View.WinForms for WinForms Edition
    // ...
    var queryBuilder1 = new QueryBuilder();
  2. Put the needed metadata and syntax provider components on the form or create them by code. Define a proper database connection object for the metadata provider.

    var connection = new OleDbConnection();
    connection.ConnectionString = "<your connection string here>";
    var metadataProvider = new OLEDBMetadataProvider();
    metadataProvider.Connection = connection;
    var syntaxProvider = new GenericSyntaxProvider();

    Connection string examples can be found here.

  3. Link the components above to the QueryBuilder by setting MetadataProvider and SyntaxProvider properties

    queryBuilder1.MetadataProvider = metadataProvider;
    queryBuilder1.SyntaxProvider = syntaxProvider;
  4. Add SQLTextEditor, TextBox, or any other text editing control to a form if you want to allow for direct SQL text editing by end-users.
  5. Establish a connection between the QueryBuilder and the TextBox components.

    Set the following code for the Validate event of TextBox control:

    private void textBox1_Validating(object sender, System.ComponentModel.CancelEventArgs e)
            // Update the query builder with manually edited query text:
            queryBuilder1.SQL = textBox1.Text;
        catch (SQLParsingException ex)
            e.Cancel = true;
            // Set caret to error position
            textBox1.SelectionStart = ex.ErrorPos.pos;
            // Report error
            MessageBox.Show(ex.Message, "Parsing error");

    Add the following handler for the QueryBuilder.SQLUpdated event:

    textBox1.Text = queryBuilder1.FormattedSQL;
  6. Call the following method to activate Active Query Builder's database schema tree:


That's all! Now you can run your application.


What to read next?


Is this article helpful for you?