AQB ASP.NET 3 - Server-side Objects Reference
Last modified:
Contents:
- Main objects
- Auxiliary server-side objects
Working with Active Query Builder on the server side you operate with a small set of objects designed to interchange with the client web interface which use the core Active Query Builder objects responsible for the SQL query context definition, internal query object model storage, SQL query parsing, text generation, etc. This documentation describes the Active Query Builder web-related objects.
The main object which represents the visual query builder on the server-side is ActiveQueryBuilder.Web.QueryBuilder. The ActiveQueryBuilder.Core.QueryTransformer object can be used in addition to the QueryBuilder object to perform SQL query post-processing to build a feature-rich data browsing UI.
It is accompanied by a set of auxiliary objects and interfaces to set up the environment: AqbHandler, CbHandler, ResourceHandler, QueryBuilderStore, QueryTransformerStore, IQueryBuilderProvider, IQueryTransformerProvider.
Main objects
QueryBuilder
Properties
Setup
SyntaxProvider
Reference to the object which determines the SQL syntax and metadata retrieval rules of the specific database server. It is necessary to assign this property before start working with the component.
MetadataProvider
Reference to the object which establishes a connection with the specific type of DB connection library.
Read this article for details: What are the Syntax and Metadata Providers for?
Language
Gets and sets the user interface language. Accepts ISO 639-1 language codes and national varieties (Ex.: "pt-BR").
The list of available localizations: Available localizations.
Log
Reference to object implementing the ILog interface. It can be defined to collect information about Active Query Builder activity for debugging purposes.
Read how to turn the logging on here: How to turn the logging on?
Integral parts
SQLContext
Provides access to the SQLContext object containing the necessary information about the SQL execution environment: Syntax and Metadata providers, Metadata Container and Structure, etc.
MetadataContainer
Gets the reference to the SQLContext.MetadataProvider object containing information about database schema retrieved from the database. This is a tree-like structure that gets loaded on demand. Read more: How database schema information stored in the Metadata Container?
MetadataStructure
Gets the reference to the SQLContext.MetadataStructure object that maps the content of the Metadata Container to the tree structure. Normally this object gets populated automatically according to the QueryBuilder.MetadataStructureOptions settings, but the programmer can customize the tree in various ways. Read about this in the article: Customizing the Database Schema Tree structure.
UserQueries
Gets the reference to the SQLContext.UserQueries object which holds the structure of folders of reusable queries. Read more: Reusable Queries.
Localizer
Allows to load custom languages as described in the article: Loading and selecting the language in run-time.
Work with the query
SQL
Gets and sets the unformatted SQL query text for execution against the database server formatted according to the QueryBuilder.SQLGenerationOptions settings.
LayoutSQL
Gets and sets the serialized query state and layout of objects on the Canvas.
SQLQuery
Gets the SQLQuery object holding and managing the internal query object model.
ActiveSubQuery
Gets the reference to the SubQuery object currently visible to the end-user.
ActiveUnionSubQuery
Gets the reference to the UnionSubQuery object (one in the list of SELECT statements of the current sub-query united with Set operators, if any) currently visible to the end-user.
FormattedSQL
Gets the SQL query text formatted according to the QueryBuilder.SQLFormattingOptions settings.
FormattedActiveSubQuerySQL
Gets the text of the currently visible sub-query formatted according to the QueryBuilder.SQLFormattingOptions settings.
FormattedActiveUnionSubQuerySQL
Gets the text of the currently visible SELECT statement (one in the list of SELECT statements of the current sub-query united with Set operators, if any) formatted according to the QueryBuilder.SQLFormattingOptions settings.
ExchangeData
Gets or sets custom data to exchange with the client.
QueryStatistics
Gets various information about the query: list of query output columns, lists of used database objects, and fields.
Component settings
BehaviorOptions
Settings to tune the way Active Query Builder parses and builds SQL queries. Members list.
DataSourceOptions
Settings to customize the view and functionality of 'Datasource objects' (objects on the Design pane representing the FROM clause items). Members list.
- EnableUserFields - enables working with user-defined fields on the client-side.
- ResizeMode - determines the way the user resizes datasources on the canvas. Default value: "se" (bottom-right corner). Possible values are listed here.
DatabaseSchemaViewOptions
Settings to tune the view and functionality of the Database Schema View control. Members list.
SQLFormattingOptions
Settings to define the formatting of SQL query text returned by the QueryBuilder.FormattedSQL property.
SQLGenerationOptions
Settings to customize the rules of SQL query text generation for pieces of SQL displayed in the user interface (SQL expressions, conditions, etc.)
SQLGenerationOptionsForServer
Settings to customize the rules of SQL query text generation for the QueryBuilder.SQL property.
MetadataLoadingOptions
Settings to define the visible parts of the database schema. Members list.
MetadataStructureOptions
Settings to customize the database schema tree structure (grouping by object types, namespaces, etc.) Members list.
Methods
Clear
Clears the query.
BeginUpdate
Signals the start of an update operation.
Call this method before performing any batch updates on the query object model. After completing all the changes, call EndUpdate to signal the end of the operation. Every call to BeginUpdate must be matched by a corresponding call to the EndUpdate method.
EndUpdate
Signals the end of an update operation.
ClearMetadata
Clears the loaded information about the database schema.
Dispose
Destroys the object and frees the occupied memory.
Events
DataSourceAdding
Invoked when DataSource is about to be added to the query by the user.
DataSourceAdded
Invoked when DataSource is added to the query by the user.
DataSourceRemoving
Invoked when DataSource is about to be deleted from the query by the user.
DataSourceFieldAdding
Invoked when Field is about to be added to the query by checking it at the DataSource field list.
DataSourceFieldAdded
Invoked when Field is added to the query by checking it at the DataSource field list.
DataSourceFieldRemoving
Invoked when Field is about to be removed from the query by unchecking it at the DataSource field list.
DataSourceFieldRemoved
Invoked when Field is removed from the query by unchecking it at the DataSource field list.
LinkAdding
Invoked when the join between datasources is about to be created by the user.
LinkCreated
Invoked when the join between datasources is created by the user.
LinkChanging
Invoked when the join properties are about to be changed by the user.
LinkChanged
Invoked when the join properties are changed by the user.
LinkRemoving
Invoked when the join between datasources is about to be deleted by the user.
QueryColumnListItemAdding
Invoked when a new Query Column List item is about to be added to the query by the user.
QueryColumnListItemChanging
Invoked when one of the Query Columns Grid Control cell values is about to be changed by the user.
QueryColumnListItemChanged
Invoked when one of the Query Columns Grid Control cell values is changed by the user.
QueryColumnListItemRemoving
Invoked when one of the Query Column List items is about to be deleted by the user.
EditorSQLUpdated
Fired when the updated SQL query text is received from the client.
UserDataReceived
Fired when extra data is received from the client.
QueryTransformer
The server-side object to perform post-processing of the query built with the QueryBuilder object.
QueryTransformer is needed for CriteriaBuilder client control. It also can be used to perform other operations to change or limit the resultset returned by the query. It can be used to handle various user actions while browsing the result query data, such as sorting and filtration. Read more about its API here: How to change sorting, add filters, limits, and aggregations to the query?
Auxiliary server-side objects
A little difference exists between the classic ASP.NET and ASP.NET Core APIs. In the classic ASP.NET implementation, we designed a set of static classes ("stores") to save user queries state on the server. ASP.NET Core prescribes to use the dependency injection software design pattern, so we use service interfaces ("services") for this purpose. Their members and purpose are the same.
Note: The *Store.Provider properties and *Provider objects are available only in the Corporate version of Active Query Builder.
QueryBuilderStore (ASP.NET) / QueryBuilderService (ASP.NET Core)
The global static class used to create and keep QueryBuilder objects during the work session. By default, objects are stored within the HTTP session. To specify another storage, assign custom implementation of IQueryBuilderProvider interface to the Provider property.
Properties
-
Provider: IQueryBuilderProvider.
Classic ASP.NET: Allows for redefining the storage of objects within the work session and between them.
ASP.NET Core: Read-only. Returns the used storage provider. One must redefine via dependency injection in the ConfigureServices method of the Startup class.
Methods
Create
Creates a new instance of the QueryBuilder object with the given string identifier.
Get
Gets an instance of the QueryBuilder object by the given string identifier.
Put
Saves the given instance of the QueryBuilder object. The identifier is passed through the Tag property.
Remove
Removes an instance of the QueryBuilder object with the given string identifier.
IQueryBuilderProvider
Allows overriding the default behavior of storing QueryBuilder objects on the server-side.
The internal query object model can be serialized and deserialized via the LayoutSQL property.
Re-creating a QueryBuilder object requires the initialization with appropriate Syntax and Metadata Providers, assigning a DBConnection in case of working with the live database or loading the content of MetadataProvider programmatically.
Properties
-
SaveState: bool; default: false.
Instructs the provider to explicitly save the state after the modification. This is not needed if the provider allows working with in-memory object instances as the default session storage provider does. If the storage saves the serialized component state, this property must be turned to true.
Methods
Get
Gets (usually - creates an instance and deserializes) the QueryBuilder object from the store by the given string identifier.
Put
Puts (usually - serializes) the QueryBuilder object to the store. The identifier is passed through the Tag property.
Delete
Removes (usually - deletes a serialized representation) the given QueryBuilder object from the store with the given string identifier.
QueryTransformerStore (ASP.NET) / QueryTransformerService (ASP.NET Core)
The global static class used to create and keep QueryTransformer objects during the work session. By default, objects are stored within the HTTP session. To specify another storage, assign custom implementation of IQueryTransformerProvider interface to the Provider property.
Properties
-
Provider: IQueryTransformerProvider.
Classic ASP.NET: Allows for redefining the storage of objects within the work session and between them.
ASP.NET Core: Read-only. Returns the used storage provider. One must redefine via dependency injection in the ConfigureServices method of the Startup class.
Methods
Create
Creates a new instance of the QueryTransformer object with the given string identifier.
Get
Gets an instance of the QueryTransformer object by the given string identifier.
Put
Saves the given instance of the QueryTransformer object. The identifier is passed through the Tag property.
Remove
Removes an instance of the QueryTransformer object with the given string identifier.
IQueryTransformerProvider
Allows overriding the default behavior of storing QueryTransformer objects on the server-side.
On re-creating a QueryTransformer object one should assign its QueryBuilder property to correctly initialized instance of the QueryBuilder object.
Properties
-
SaveState: bool; default: false.
Instructs the provider to explicitly save the state after the modification. This is not needed if the provider allows working with in-memory object instances as the default session storage provider does. If the storage saves the serialized component state, this property must be turned to true.
Methods
Get
Gets (usually - creates an instance and deserializes) the QueryTransformer object from the store by the given string identifier.
Put
Puts (usually - serializes) the QueryTransformer object to the store. The identifier is passed through the Tag property.
Delete
Removes (usually - deletes a serialized representation) the given QueryTransformer object from the store with the given string identifier.
BaseHandler
Base class for all HTTP handlers performing exchange between client controls and server-side objects.
Properties
-
AllowCrossOrigin: bool; default: false. Can be set only via the Web.config file.
Allows running the web server and Active Query Builder handlers on different domains. You may also need to specify the AQB.Web.host property to redirect requests to AQB handlers. See the Cross-domain demo project for details. -
HttpCompressionEnabled: bool; default: true. Can be set only via the Web.config file.
Allows compressing data over HTTP. -
Log: ActiveQueryBuilder.Core.ILog.
Determines the way to output the debug information about all requests from the client to the server.
It is internally passed to the QueryBuilder, SqlContext, SyntaxProvider, and MetadataProvider objects. By default, it is set to the instance of ActiveQueryBuilder.Web.Server.Infrastructure.TraceLog class which outputs all messages to the Visual Studio debug console. To override the default behavior, build your own implementation of the ILog interface. For example, you can use the famous log4net library. Read more: Setup logging in AQB ASP.NET. -
VirtualDirectory: string.
Allows specifying the web server virtual directory. By default, the component tries to detect the used virtual directory according to the web server settings. You can manually specify the directory in the case of autodetection failure. -
UseRelativePaths: bool; default: false.
Instructs to address scripts, styles, and the AQB handler using paths that are relative to the current web page URL. Literally, setting this property to true adds the "./" to URLs. This is useful when you don't know the virtual directory to which the page will be deployed.
Methods
DisableRegistration
Disables automatic route registration for the handler. After that one must define its own controller method to handle AQB requests as follows and define a custom path to it via the QueryBuilder UI control's HandersPath property.
public class HomeController : Controller
{
public void Sync()
{
var factory = new AspNetHandlerFactory();
var h = factory.CreateHandler(Request.Params);
h.ProcessRequest();
}
}
Events
- OnException - Fired on unhandled exception arose on the client-side. It allows overriding the message passed to the client.
AqbHandler
Inherited from the BaseHandler.
HTTP handler to handle requests of the QueryBuilder component.
Properties:
-
PersistentConnection: bool; default: false. It can be set only via the Web.config file.
Denies closing the database connection. By default, the connection is closed at the end of the request. -
DisableSessionKeeper: bool; default: false. It can be set only via the Web.config file.
Allows firing the ping request by the client which keeps the session alive for 15 minutes of the user inactivity.
CbHandler
Inherited from the BaseHandler.
HTTP handler to handle requests of the CriteriaBuilder component.
ResourceHandler
Inherited from the BaseHandler.
HTTP handler to provide various resources to clients (scripts, CSS files, localized strings, images).
Properties
-
EnableResourceCaching: bool; default: true; can be set only via the Web.config file.
Allows in-memory caching of requested resources.