Integrate the Dashboard Control into an ASP.NET Core Project

• Mar 06, 2024
• 3 minutes to read

This topic describes how to integrate the Web Dashboard into an existing ASP.NET Core web application. The guide applies to the .NET 6 framework.

You can also review the example:

View Example

Add the NuGet Package

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

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

Add the Namespaces

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

...
@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, 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 Required Client Libraries for ASP.NET Core for the detailed instruction.

Add a Dashboard Controller

Add a new empty DefaultDashboard controller and inherit the DashboardController class:

using DevExpress.DashboardAspNetCore;
using DevExpress.DashboardWeb;
using Microsoft.AspNetCore.DataProtection;

namespace WebDashboardAspNetCore.Controllers {
    public class DefaultDashboardController : DashboardController {
        public DefaultDashboardController(DashboardConfigurator configurator, IDataProtectionProvider? dataProtectionProvider = null)
            : base(configurator, dataProtectionProvider) {
        }
    }
}

You can also derive a custom dashboard controller from RestrictedDashboardController to prevent inadvertent or unauthorized dashboard modifications and protect dashboards stored on a server.

Register the Dashboard Configurator

The configurator allows you to define dashboard storage, data source storage, and connection strings provider.

Register the DashboardConfigurator as a service based on your requirements. The AddSingleton method registers the DashboardConfigurator service with the same service lifetime as AddDefaultDashboardController. However, we recommend that you use the AddScoped method as it can be used in more cases (for example, security-based scenarios like multi-tenancy dashboards).

The code snippet below shows how to register the DashboardConfigurator as a scoped service at application startup.

using DevExpress.AspNetCore;
using DevExpress.DashboardAspNetCore;
using DevExpress.DashboardWeb;
using Microsoft.Extensions.FileProviders;
// ...
IFileProvider? fileProvider = builder.Environment.ContentRootFileProvider;
IConfiguration? configuration = builder.Configuration;
// ...
builder.Services.AddScoped<DashboardConfigurator>((IServiceProvider serviceProvider) => {
    DashboardConfigurator configurator = new DashboardConfigurator();
    configurator.SetDashboardStorage(new DashboardFileStorage(fileProvider.GetFileInfo("Data/Dashboards").PhysicalPath));
    configurator.SetConnectionStringsProvider(new DashboardConnectionStringsProvider(configuration));
    return configurator;
});

Add Third-Party and DevExtreme Middleware

Call the MvcServiceCollectionExtensions.AddDevExpressControls method to register the DevExpress middleware that is assembled into an application pipeline to handle requests and responses:

using DevExpress.AspNetCore;
// ...
builder.Services.AddDevExpressControls();

Register DevExpress Middleware

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

using DevExpress.AspNetCore;
// ...
app.UseDevExpressControls();

Configure Routing

Call the RouteBuilderExtension.MapDashboardRoute method. Pass the dashboard route prefix (for example, api/dashboard) and the name of the dashboard controller (without Controller postfix) as parameters.

using DevExpress.AspNetCore;
// ...
app.MapDashboardRoute("api/dashboard", "DefaultDashboard");

Add Web Control Code

To add the Web Dashboard to a View, call the BuilderFactoryExtension.Dashboard extension method. This method contains a parameter that returns the dashboard settings you can use to customize the control. The ControllerName property value should be the name of the custom dashboard controller (without Controller postfix).

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("clientDashboardControl1")
        .ControllerName("DefaultDashboard")
        .WorkingMode(WorkingMode.Designer)
        .Width("100%")
        .Height("100%")
    )
</div>

Next Steps

• Prepare the dashboard storage.
• Specify a set of predefined data connections.
• Configure data sources to be available in the Web Dashboard’s UI.
• Specify whether Web Dashboard acts as the Designer or Viewer.

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