Integrate the Dashboard Control into a Project

• Feb 27, 2020
• 4 minutes to read

This topic describes how to integrate the Web Dashboard into an existing ASP.NET Core web application.

Add the NuGet Package

The ASP.NET Core Dashboard control requires the DevExpress.AspNetCore.Dashboard package.

You can also refer to Install DevExpress Controls Using NuGet Packages for information about how to use NuGet packages to install DevExpress controls.

Add the Namespaces

Add the following namespaces to the view imports file (ViewImports.cshtml):

Razor

...
@using DevExpress.AspNetCore
@using DevExpress.DashboardAspNetCore
@using DevExpress.DashboardWeb

Attach the Scripts and Style Sheets

The Web Dashboard requires the following JavaScript scripts:

• The third-party scripts (jQuery, jQuery UI, Ace, knockout).
• The specific Dashboard JavaScript files.

A complete list is available in the Required Client Libraries topic.

You can bundle the resources before add them to the View page. See the Manual Integration section for the detailed instruction.

Register the Default Controller

Call the MvcBuilderExtension.AddDefaultDashboardController method to register a default controller and add a default dashboard configurator. The configurator allows you to define dashboard storage and connection strings provider.

The code snippet below shows how to add the code to the Startup.cs file.

using DevExpress.DashboardAspNetCore;
using DevExpress.AspNetCore;
using DevExpress.DashboardWeb;

...
public void ConfigureServices(IServiceCollection services) {
    services
        .AddMvc()
        .AddDefaultDashboardController(configurator => { });
    // ...
}

Add Third-Party and DevExtreme Middleware

In the Startup.cs file, call the MvcServiceCollectionExtensions.AddDevExpressControls method to register the DevExpress middleware components when you configure the application’s services.

using DevExpress.DashboardAspNetCore;
using DevExpress.AspNetCore;
using DevExpress.DashboardWeb;

...

public void ConfigureServices(IServiceCollection services) {
    // ...
    services.AddDevExpressControls();
}

Register DevExpress Middleware

Call the ApplicationBuilderExtensions.UseDevExpressControls method to add the DevExpress middleware components to the request pipeline.

using DevExpress.DashboardAspNetCore;
using DevExpress.AspNetCore;
using DevExpress.DashboardWeb;

...
public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
    // ...
    app.UseStaticFiles();
    app.UseDevExpressControls();
    // ...
}

Note that for ASP.NET Core 3.0, the env parameter type is changed from IHostingEnvironment to IWebHostEnvironment:

using DevExpress.DashboardAspNetCore;
using DevExpress.AspNetCore;
using DevExpress.DashboardWeb;
using Microsoft.Extensions.Hosting;

...
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    // ...
    app.UseStaticFiles();
    app.UseDevExpressControls();
    // ...
}

Configure Routing

Starting from ASP.NET Core 2.2, the .NET Core application supports two routing types: routing at the MVC level and endpoint routing.

• ASP.NET Core 2.2 uses routing at the MVC level.
• ASP.NET Core 3.0 uses endpoint routing.

The Web Dashboard allows you to use either routing type for both frameworks.

For routing at the MVC level, call the RouteBuilderExtension.MapDashboardRoute method to map the Dashboard’s route:

using DevExpress.DashboardAspNetCore;
using DevExpress.AspNetCore;
using DevExpress.DashboardWeb;

...
public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
    // ...
    app.UseMvc(routes => {
        // Maps a dashboard route.
        routes.MapDashboardRoute("api/dashboard");
        routes.MapRoute(
            name: "default",
            template: "{controller=Home}/{action=Index}/{id?}");
    });
}

For endpoint routing, call the EndpointRouteBuilderExtension.MapDashboardRoute method:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    if(env.IsDevelopment()) {
        app.UseDeveloperExceptionPage();
    } else {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }
    app.UseHttpsRedirection();
    app.UseStaticFiles();
    // Registers the DevExpress middleware.
    app.UseDevExpressControls();
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints => {
        // Maps the dashboard route.
        EndpointRouteBuilderExtension.MapDashboardRoute(endpoints, "api/dashboards");
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Add Web Control Code

To add the Web Dashboard to a View, call the BuilderFactoryExtension.Dashboard extension method. This method provides a parameter that returns the dashboard settings you can use to customize the control.

The code snippet below shows how to define a control in the Index.cshtml file.

<div style="position: absolute; left:0;top:0;right:0;bottom:0;">
    @(Html.DevExpress().Dashboard("clientDashboardDesigner1")
        .Width("100%")
        .Height("100%")
        .WorkingMode(WorkingMode.Designer)
    )
</div>

Docker Support

Refer to the Visual Studio Tools for Docker with ASP.NET Core tutorial for instructions on how to dockerize (add to a Docker container) your ASP.NET Core Web Dashboard application.

Make the following changes to the Dockerfile when you add the application to a Linux container:

 ...
 FROM microsoft/aspnetcore:2.1 AS base
 RUN apt-get update
 RUN apt-get install -y libgdiplus libc6-dev
 RUN apt-get install -y libicu-dev libharfbuzz0b libfontconfig1 libfreetype6
 ...

Next Steps

• Prepare the dashboard storage.
• Provide a set of predefined data connections.
• Provide a set of default data sources available for end users.
• Specify whether Web Dashboard acts as the Designer or Viewer.

You can also create the ASP.NET Core Dashboard application from scratch.