WIP: Embedding Active Query Builder in a Single-Page Application - Basics

Here are the basic steps and things you should take care of embedding Active Query Builder in your SPA app. Some of them might not be needed for you.

1. Preparing a boilerplate

Visual Studio 2019 contains the necessary boilerplates for some client frameworks like Angular and React.js. In this case, you only need to select a project template while creating a new project. Others like Vue.js require manual preparation, so you should start with an empty project.

Read details: Preparing a boilerplate for Vue.js.

2. Adding Active Query Builder to your project

To begin with, add the following references to your .NET Core project:

• ActiveQueryBuilder.Core.NETCore.dll
• ActiveQueryBuilder.Web.Server.NETCore.dll
• ActiveQueryBuilder.Web.Core.NETCore.dll

Other references might be needed to get connected to different .NET DB providers. 

Get the component's server-side connected to your app via the Startup.cs file.

- Add these lines to the ConfigureServices method:

    services.AddSession();
    services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
    services.AddActiveQueryBuilder();

- Add these lines to the Configure method:

    app.UseSession();
    app.UseActiveQueryBuilder();

These lines register the component's modules in the DI container and include the component into the HTTP request handling pipeline.

3. Adding a controller to create and get server-side instances of the component

    public class QueryBuilderController : Controller
    {
        private readonly IQueryBuilderService _aqbs;

        // Use IQueryBuilderService to get access to the server-side instances of Active Query Builder objects. 
        // See the registration of this service in the Startup.cs.
        public QueryBuilderController(IQueryBuilderService aqbs)
        {
            _aqbs = aqbs;
        }

        public ActionResult CreateQueryBuilder(string name)
        {
            // Get an instance of the QueryBuilder object
            var qb = _aqbs.Get(name);

            if (qb != null)
                return StatusCode(200);

            try
            {
                // Create an instance of the QueryBuilder object
                qb = _aqbs.Create(name);
                qb.MetadataLoadingOptions.OfflineMode = true;
                qb.SyntaxProvider = new GenericSyntaxProvider();

                // Initialize metadata
                ////

                qb.MetadataStructure.Refresh();

                return StatusCode(200);
            }
            catch (QueryBuilderException e)
            {
                return StatusCode(400, e.Message);
            }
        }
    }

4. Setting up the client-side

Follow the steps described in an article for your client framework to set up the component client-side.

- Angular

- React.js

- Vue.js

5. Proxying client queries to the server listening on a different port

This part is not necessary but recommended if you want to use the WebPack development server for easy debugging. After completing this section, all queries from the server will be proxied to the backend server letting you avoid problems with CORS.

Setting it up is specific for each of the aforementioned client frameworks, so it is described in the respective articles above.

6. Additional: setting up token-based query builder instantiation

Regularly, Active Query Builder stores the client state using the ASP.NET Session mechanism. But relying on sessions may be undesirable in the case of building projects with complex architecture. Having the Enterprise edition of Active Query Builder, you can redefine the client state storage mechanism to save the state wherever you want, including saving it on the client making your server stateless. 

- Creating a token-based stage storage provider.

- Building a stateless server for Active Query Builder ASP.NET Edition.

Further reading:

Getting and setting SQL query text

Switching connections and loading saved queries

Packing Active Query Builder in a Docker container