You can initialize and set up the component via the configuration file as an alternative of doing this in code.

Note: The desktop visual tool to create and edit AQB configuration files is included in the installation package. You can find its executable in the "[AQB installation directory]\ConfigurationEditorUtility\ConfigurationEditorUtility.exe".

This is important for setting the component up in virtual containers, such as Docker, Kubernetes, etc.

There are two ways to load metadata in this mode:

1. From the pre-generated XML file or from a live database connection. The "xml" attribute of the "metadataSource" tag prescribes to load metadata from the file
2. From the live connection to a database using the "dbConnection" subtag to determine its parameters.

WebForms and MVC

Configuration file setup

In the WebForms and ASP.NET MVC environments, the standard way is to define global settings is the "Web.config" file.

First, register the custom configuration section by adding the following "section" element to the "configuration\configSections" node:

<configuration>
  <configSections>
    <!-- Registration of the Active Query Builder configuration section -->
    <section name="aspQueryBuilder" type="ActiveQueryBuilder.Web.Server.Configuration.AspQueryBuilderConfiguration, ActiveQueryBuilder.Web.Server"/>
  </configSections>

Next, add the "aspQueryBuilder" section into the "configuration" node:

  <!-- Active Query Builder configuration section -->
  <aspQueryBuilder>
    <!-- global properties -->
    <common persistentConnection="false" logHandlerStateOnExceptions="false" />
    <!-- initialization -->
    <syntaxProvider type="ActiveQueryBuilder.Core.MSSQLSyntaxProvider, ActiveQueryBuilder.Core" />
    <!-- first variant: loading metadata from live database connection -->
    <metadataProvider type="ActiveQueryBuilder.Core.MSSQLMetadataProvider, ActiveQueryBuilder.MSSQLMetadataProvider"/> 
    <metadataSource>
      <dbConnection type="System.Data.SqlClient.SqlConnection, System.Data" connectionString="data source=.\sqlexpress; integrated security=true" />
    </metadataSource>
    <!-- second variant: loading metadata from XML file -->
    <metadataSource xml="C:\...\Northwind.xml">
  </aspQueryBuilder>
</configuration>

ASP.NET project setup

1. Instruct the component to read the configuration from the "Web.config" file, preferably in the Application_Start handler in the "Global.asax" file:

void Application_Start(object sender, EventArgs e)
{
    QueryBuilderStore.UseWebConfig();
}

2. In the case of working with the live database connection, add used metadata provider and database client assemblies to the project (using NuGet packages or directly referring them).

ASP.NET Core

Configuration file setup

As the "web.config" file doesn't exist in ASP.NET Core, you are free to choose the location and format of the configuration file: JSON or XML.

JSON

{
    "aspQueryBuilder": {
        "common": {
            "httpCompression": "true",
            "persistentConnection": "false"
        },
        "syntaxProvider": {
            "type": "ActiveQueryBuilder.Core.DB2SyntaxProvider, ActiveQueryBuilder.Core"
        },
        "metadataProvider": {
            "type": "ActiveQueryBuilder.Core.MSSQLMetadataProvider, ActiveQueryBuilder.MSSQLMetadataProvider"
        },
        "metadataSource": {
            "xml": "db2_sample_with_alt_names.xml",
            "dbConnection": {
                "type": "System.Data.SqlClient.SqlConnection, System.Data",
                "connectionString": "data source=.\\sqlexpress; integrated security=true"
            }
        }
    }
}

XML

<configuration>
  <aspQueryBuilder>
    <common>
      <httpCompression>true</httpCompression>
      <persistentConnection>false</persistentConnection>
    </common>
    <syntaxProvider>
      <type>ActiveQueryBuilder.Core.DB2SyntaxProvider, ActiveQueryBuilder.Core</type>
    </syntaxProvider>
    <metadataProvider>
      <type>ActiveQueryBuilder.Core.MSSQLMetadataProvider, ActiveQueryBuilder.MSSQLMetadataProvider</type>
    </metadataProvider>
    <metadataSource>
      <xml>db2_sample_with_alt_names.xml</xml>
      <dbConnection>
        <type>System.Data.SqlClient.SqlConnection, System.Data</type>
        <connectionString>data source=.\sqlexpress; integrated security=true</connectionString>
      </dbConnection>
    </metadataSource>
  </aspQueryBuilder>
</configuration>

 

ASP.NET Core project setup

1. Register your configuration file in the Startup class constructor:

public Startup(IHostingEnvironment env)
{
    // choose one according to the format of your configuration file
    builder.AddJsonFile("ActiveQueryBuilderConfig.json");
    builder.AddXmlFile("ActiveQueryBuilderConfig.xml");
}

2. Apply settings from the configuration file in the ConfigureServices method of Startup class by calling the Configuration.GetSection method with the name of the configuration section as a parameter:

public void ConfigureServices(IServiceCollection services)
{
	// Active Query Builder requires support for Session HttpContext (unless you use the Corporate version). 
	services.AddSession();
	services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();

	// This service provides access to instances of QueryBuilder and QueryTranformer objects on the server.
	qbConfig = Configuration.GetSection("aspQueryBuilder"); 
	services.AddActiveQueryBuilder(qbConfig);

	services.AddMvc();
}

3. In the case of working with the live database connection, add used metadata provider and database client assemblies to the project (using NuGet packages or directly referring them).

Common settings

common

• httpCompression: bool; default: true; Turns data compression over HTTP on and off.
• persistentConnection: bool; default: false. Instructs to keep database connection alive for each session. By default, Active Query Builder opens a connection to the database as needed and closes it immediately when the requested data is fetched.
• logHandlerStateOnExceptions: bool; default: false; Prescribes to write the serialized component state and request body to the log in case of unhandled exceptions arose during the processing of this request.
• disableSessionKeeper: bool; default: false. Turns pinging of the server on and off. This feature lets keep the session alive. Even if this setting is set to false (pinging is enabled), ping stops after 15 minutes of user inactivity.
• allowCrossOrigin: bool; default: false. Being set to true, this setting allows cross-origin HTTP requests. It is needed in case the web server and Active Query Builder service work on different domains.
• enableResourceCaching: bool; default: true. Turns the caching of resources (styles, images, strings) on the client during the period of session activity.
• virtualDirectory: string. Explicitly defines the web server's virtual directory overriding the autodetected value.

Component initialization

syntaxProvider

• type: System.Type. Class name of the Syntax Provider. Must be a descendant of the BaseSyntaxProvider class from the ActiveQueryBuilder.Core assembly.

metadataProvider

• type: System.Type. Class name of the Metadata Provider. Must be a descendant of the BaseMetadataProvider class from the ActiveQueryBuilder.Core assembly.

metadataSource:

• xml: string. Absolute path to the metadata XML file.
• dbConnection:
  • type: System.Type. Database connection class name. Must implement the IDbConnection interface from the System.Data assembly.
  • connectionString: string. Database connection string.