Integrate the Dashboard Control into a Project

• Feb 15, 2021
• 3 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 @402119 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.

.NET 5 and .NET Core 3.1

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

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

.NET Core 2.1

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

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

Note

The env parameter type is different:

• ASP.NET Core 2.1 - IHostingEnvironment
• ASP.NET Core 5.0 and ASP.NET Core 3.1 - IWebHostEnvironment

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.1+ uses endpoint routing.

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

For routing at the MVC level (UseMvc), 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 (UseEndpoints), 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>

Next Steps

• Prepare the dashboard storage.
• Specify a set of predefined data connections.
• Add 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.