Getting started for ASP.NET Core + Razor pages

Here we describe how to add EasyQuery to your ASP.NET Core application with MVC or Razor Pages views.

Prerequisites

  1. You have an ASP.NET Core version 2.1+ project with MVC views (or Razor pages)
  2. Your application uses Entity Framework Core to work with the database. (NB: it's possible to use EasyQuery without EF Core as well but for the sake of simplicity we will not consider other cases here).

Step 1: Add EasyQuery packages to your project

First, we are going to add EasyQuery to your ASP.NET Core backend project.

Since we have a standard ASP.NET Core project with EntityFramework Core - then we will need the following 3 EasyQuery packages be added to your .csproj file:

    <PackageReference Include="Korzh.EasyQuery.AspNetCore" Version="5.1.1" />
    <PackageReference Include="Korzh.EasyQuery.EntityFrameworkCore.Relational" Version="5.1.1" />
    <PackageReference Include="Korzh.EasyQuery.RazorUI" Version="5.1.1" />

The latest package is a Razor UI library which contains several ready-to-use page templates (partial views) that work with EasyQuery components.

Step 2: Add EasyQuery services and middleware

The next step will be to setup EasyQuery services and the middleware. Here are the parts your will need to add to your Startup class:

public void ConfigureServices(IServiceCollection services)
{
    .    .    .    .   .   .
    services.AddEasyQuery()
        .UseSqlManager();
}

Here we've added the service and set the default EasyQuery manager (the main "engine" which will process all request). Currently there two possible options: EasyQueryManagerSql and EasyQueryManagerLinq. In the code above we set the first one as default.

Then we need to setup the middleware which will handle HTTP requests from the client-side, pass them to manager, take the result and prepare it for sending back to the client. To avoid any conflicts with MVC we put EasyQuery middleware before it:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
       .   .   .   .   .   .
    app.UseEasyQuery(options => {
        options.Endpoint = "/api/easyquery";
        options.UseDbContext<AppDbContext>();
        options.UsePaging(25);
    });
    app.UseMvc();
}

The code above defines the following main settings:

  1. The endpoint is set to /api/easyquery. This means that all requests from EasyQuery widgets will be started with this path (like /api/easyquery/models/{modelId} to load the model). Please note that this is the default value so you can omit this setting in your app.
  2. We will use the DbContext class specified in UseDbContext call to get the model or to execute the generated queries. It's the fasteset way to specify the model load and the connection to your DB. Otherwise you will need to set them separately via UseModelLoader or UseDbConnection extension functions.
  3. The last UsePaging call turns on the paging and set the page size.

So, server-side setup is finished. Now we need to setup the client-side part.

Step 3: Add EasyQuery page

There are 3 possible options to define the view:

Option 1: Use one of the predefined pages from EasyQuery Razor UI library

So, to simplify the task of rendering an advanced search or data-filtering views EasyQuery includes a Razor UI library package (Korzh.EasyQuery.RazorUI) that contains several predefined views which you can use on your pages. In the simplest case you can just add Korzh.EasyQuery.RazorUI package to your project and run your project. If everything is set up with the defaults, then right out-of-the-box you get access to an "advanced search" page via /EasyQuery/AdvancedSearch.

Option 2: Use some partial view from the Razor UI library

Of course you may need to modify some view options or change the page styles. In this case you can use the partial view accessible via EasyQuery/_AdvancedSearch.
All you need to do for that:

  1. Reference Korzh.EasyQuery.RazorUI package in your project
  2. Create a new page where you plan to provide an advanced search or adhoc reporting functionality. Let's suppose this new page will be accessible as /CustomSearch
  3. Add the styles necessary to render EasyQuery components into Styles section:
@section Styles {
    <link rel="stylesheet" href="https://ajax.aspnetcdn.com/ajax/jquery.ui/1.12.1/themes/cupertino/jquery-ui.css">
    <link rel="stylesheet" href="https://cdn.korzh.com/eq/5.1.1/eq.core.min.css">
    <link rel="stylesheet" href="https://cdn.korzh.com/eq/5.1.1/eq.view.min.css">
}

(don't forget to add @RenderSection("Styles", false); command to your _Layout.cshtml if you don't have such section yet)

  1. Add the following tag which includes an _AdvancedSearch partial view somewhere to your new page:
<partial name="EasyQuery/_AdvancedSearch" />
  1. Add Scripts section to your page with all necessary libraries (jquery, jquery-ui and eq.all.min.js) and the code which will initalize the advanced search view (more about EasyQuery views) on your page:
@section Scripts {
   <!-- JQuery scripts (we still need them, unfortunately) -->
    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.3.1.min.js" type="text/javascript"></script>
    <script src="https://ajax.aspnetcdn.com/ajax/jquery.ui/1.12.1/jquery-ui.min.js" type="text/javascript"></script>
		
    <!-- EasyQuery script -->
    <script src="https://cdn.korzh.com/eq/5.1.1/eq.all.min.js"></script>

    <!-- EasyQuery view initialization -->
    <script>
        document.addEventListener('DOMContentLoaded', () => {
            //Options for AdvancedSearchViewJQuery
            let options = {
                broker: {
                    //the base URL where all requests are sent to 
		                endpoint: '/api/easyquery'
                },
                widgets: {
		                entitiesPanel: {
                        //EntityiesPanel options
				                showCheckboxes: true
		                },
		                columnsPanel: {
                        //ColumnsPanel options
		                },
		                queryPanel: {
                        //Querypanel options
		                },
                },
                result: {
                    //Don't show EasyChart
                    showChart: false,
                },
            };
						
            this.view = new easyquery.AdvancedSearchViewJQuery();
            view.init(options);
        });
    </script>
}

Option 3: Define your own page

  1. Add your own view or a Razor page (let's suppose it will be accessible by /CustomSearch path.

  2. Reserve several "slots" (empty div elements) for EasyQuery widgets. Each slot must have a special ID to allow EasyQuery to find it:

    • EntitiesPanel - to show the content of your data model
    • ColumnsPanel - to show the panel which allow to edit the list of query column
    • QueryPanel - for the widget which allows to add and modify query conditions
    • ResultPanel - the panel where the query results will be rendered
    • StatementPanel - add it if you want to show the generated SQL statetement for your users

Done!

Now if you run your project and open /CustomSearch page (or /EasyQuery/AdvancedSearch if used the first option) - you will see the default EasyQuery page for advanced database search (like this one)