Getting started for ASP.NET 4 (MVC or WebForms)

NB: The fastest way to apply EasyQuery to your ASP.NET 4 project is to clone the whole EasyQuery samples Git repository, play with the demo project for MVC or WebForms from that repository and then copy necessary parts from that project to your own one.

Below you will find the steps you need to do if you are going to add EasyQuery to your ASP.NET application from the scratch. The instructions are applied both for MVC and WebForms projects (with few little differences). It might look odd (since these two frameworks are tootally different) but it stems from how our demo projects are built.

The main work on the client-side is done by our EasyQuery JavaScript library, so the view engine (Razor in MVC or .aspx in WebForms) is responsible only for the plain HTML rendering in this case and the sever-side part is covered by WebAPI library which is the same on both platforms.

So, let's start.

0. Choose the way you will work with your data model

Data model - is a user-friendly representation of your project's database which is used by different EasyQuery components to show available entities, their attributes, conditional operators and the lists of available values during the query building process. So, first of all, you will need to choose the way you create your data model and/or load it in your application. There are several different ways of doing this. For more information please read Working with data model in EasyQuery article first.

In this article, we assume that you create your data model with Data Model Editor, then save it to some JSON (or XML) file and add that file to your project in Apdd_Data folder.

1. Install EasyQuery packages

Obviously, first thing you will need to do - is to add EasyQuery NuGet packages to your project. You can use whatever way you prefer to do it: via NuGet Package Manager UI, using Package Manager Console or manually editing .csproj file and adding necessary <PackageReference ... nodes into it.

The only package which is absolutely required to apply EasyQuery to ASP.NET is:

In some cases you might also need to add the following packages:

Step 2: Setup WebAPI controller

EasyQuery's server-side part is implemented as a WebAPI controller. So, if you don't use WebAPI in your web-application yet - you will need to add some NuGet packages to your project:

  • Microsoft.AspNet.WebApi.Core
  • Microsoft.AspNet.WebApi.WebHost

To simplify the task we prepare a base class for such controller from which you can derive your own one. All necessary endpoints (actions) are already defined and properly handled in that basic class. So, all you need to do, is to set some options in the overridden virtual method ConfigureEasyQueryOptions.

You can find and example of such controller in the Git repository with EasyQuery samples. This is the controller for advanced search page and this is the controller for ad-hoc reporting scenario

2.1 Turn on "inherited" routing

One more thing. Since the routes for all controller actions are defined in the base class - you need to re-configure the WebAPI routing in your project to make it use the routing attributes from the base controller classes (because they are not taken into the account by default). You can do it in the App_start/WebApiConfig.cs file:

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Web API configuration and services

        // Web API routes
        config.MapHttpAttributeRoutes(new WebApiCustomDirectRouteProvider());
        
		.     .     .     .
    }
}

public class WebApiCustomDirectRouteProvider : DefaultDirectRouteProvider
{
	protected override IReadOnlyList<IDirectRouteFactory>
		GetActionRouteFactories(HttpActionDescriptor actionDescriptor)
	{
		// inherit route attributes decorated on base class controller's actions
		return actionDescriptor.GetCustomAttributes<IDirectRouteFactory>(inherit: true);
	}
}

NB1: The last solution with enabling the inheritance of the routing attributes works only with WebAPI version 2.2 or higher. So, if your project uses an older version of WebAPI packages - please upgrade them first.

NB2: If you have several views with EasyQuery widgets in your application - you can create as many such WebAPI controllers as you need.

3. Add a new view/page

The next step will be to add a page which introduces an advanced search or ad-hoc reporting functionality in your project. This is the part which differs for MVC or WebForms projects. In case of MVC project you will need to add and a new view and a corresponding controller's action. In WebForms - it will be an .aspx file with a code-behind .aspx.cs

We are going to cover both these cases below.

3.1 For MVC projects

The simplest way to do it - is to copy the page you need from our sample project. Here are the direct links:

Of course, you will need to add a corresponding controller action for the new view so it will be accessible by some URL. In our sample we add those actions to the Home controller but it can be any other controller in your own project of course.

3.2 For WebForms

As for MVC you can just take the page from our sample. Here is the code behind class for that page as well.

4. Add EasyQuery API controller

The last piece of the puzzle is an API controller which will handle AJAX requests from the JS widgets placed on the view. This task will be covered by a special WebAPI controller. While this is a usual thing for ASP.NET MVC / WebAPI applications, for a WebForms project it might look quite odd. But don't worry, it works well, we tried!

As in previous step, the most simplest way is to copy the necessary controller from one of our sample projects and then modify it according to your needs. Here are the controllers you can use:

To adjust the copied contoller to your project you just need to modify a few lines in ConfigureEasyQueryOptions procedure:

  1. First of all, change the ID of the data model in options.DefaultModelId = ... line
  2. Secondly, modify the name of your connection string parameter (if it's not `"DefaultConnection" as in example)
  3. Finally, you might want to change the type of the connection in options.UseDbConnection<..>() call if use other than SQL Server database (e.g. MySqlConnection or OracleConnection)

Build. Run. Enjoy!

That's it. If everything was done right on the previous steps - your application will be built and run sucessfully and you can open and you will be able to open new page by the path you specified on the step #2 (e.g. /advanced-search as in our samples).

If something goes wrong - feel free to contact us: you can create an issue on GitHub or submit a support request on our website.