Migrate BI Dashboard from Web Forms to Blazor

• May 21, 2025
• 4 minutes to read

You can migrate ASP.NET Web Forms Dashboard customizations to a new .NET Blazor Server application. Dashboard Control API is the same regardless of the target platform, so you can migrate customization code to a new app with minimal adjustments. A custom implementation of ASP.NET Web Forms Dashboard services can also be used in a new application because interface implementation is similar in all web frameworks.

Install the NuGet Packages

Install the following NuGet packages in your project:

• DevExpress.AspNetCore.Dashboard
• DevExpress.Blazor.Dashboard

Configure Services on Startup (Program.cs)

All Web Dashboard services that you register using DashboardConfigurator for ASP.NET Web Forms app can be registered in the built-in DI container in ASP.NET Blazor applications. You do not require to update the signature and definition of services that exist in your legacy ASP.NET Web Forms app. You can copy the implementation of your custom services to your new application as-is. Note that you can use the dependency-injection concept for all migrated services.

The following code snippet registers the DashboardFileStorage service:

ASP.NET WebForms

C#

protected void Application_Start(object sender, EventArgs e) {
    DashboardConfigurator.Default.SetDashboardStorage(new DashboardFileStorage("~/App_Data/Dashboards"));
    // ...         
}

ASP.NET Blazor

C#

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<DashboardConfigurator>((IServiceProvider serviceProvider) => {
    DashboardConfigurator configurator = new DashboardConfigurator();
    configurator.SetDashboardStorage(new DashboardFileStorage(fileProvider.GetFileInfo("Data/Dashboards").PhysicalPath));
    return configurator;
});

var app = builder.Build();

The following code snippet references services required by DevExpress BI Dashboard:

Program.cs

using DevExpress.DashboardAspNetCore;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
IFileProvider fileProvider = builder.Environment.ContentRootFileProvider;
IConfiguration configuration = builder.Configuration;

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddIteractiveServerComponents();
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddScoped<DashboardConfigurator>((IServiceProvider serviceProvider) => {
    DashboardConfigurator configurator = new DashboardConfigurator();
    configurator.SetDashboardStorage(new DashboardFileStorage(fileProvider.GetFileInfo("Data/Dashboards").PhysicalPath));
    DataSourceInMemoryStorage dataSourceStorage = new DataSourceInMemoryStorage();
    configurator.SetDataSourceStorage(dataSourceStorage);
    return configurator;
});
app.UseHttpsRedirection();

app.UseStaticFiles();
app.UseRouting();
app.UseAntiforgery();
app.MapDashboardRoute("api/dashboard", "DefaultDashboard");

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

Migrate Controller Logic

ASP.NET Blazor apps uses the DashboardController class descendant. The dashboard controller handles incoming client requests and map them to actions on the server.

Note

Previously, ASP.NET Web Forms apps could handle control requests using HTTP handlers in the “web.config” file, but this is no longer supported. In ASP.NET Blazor, you need to explicitly register a dashboard controller instead.

DefaultDashboardController example:

DefaultDashboardController.cs

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

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

Adjust Views

In the Pages folder, add a new Dashboard Razor component (Dashboard.razor) to the app and add the code below to render the Web Dashboard. Set the Endpoint property to the same value as the MapDashboardRoute method (api/dashboard) to send data requests to the server.

Web Forms Markup

Default.aspx

<dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Width="100%" Height="100%" >
</dx:ASPxDashboard>

ASP.NET Blazor

Dashboard.razor

@page "/"

<DxDashboard Endpoint="api/dashboard" style="width: 100%; height: 100%;">
</DxDashboard>

Add Stylesheets

In the Pages folder, reference the following stylesheets in the Components/App.razor project file:

<head>
@* ... *@
    <link href="_content/DevExpress.Blazor.Dashboard/ace.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/ace-theme-dreamweaver.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/ace-theme-ambiance.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/dx.light.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/dx-analytics.common.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/dx-analytics.light.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/dx-querybuilder.css" rel="stylesheet" />
    <link href="_content/DevExpress.Blazor.Dashboard/dx-dashboard.light.min.css" rel="stylesheet" />
    @* ... *@
</head>

Migrate Client-Side Customization

Note

This tutorial is designed for applications that use the unified DashboardControl API, which simplifies sharing JavaScript code across platforms. Since the code is nearly identical on all supported platforms, we recommend updating your app to use this API before migrating to .NET. For details, see: Migrate from ASPxClientDashboard to DashboardControl API.

The Dashboard component for Blazor is a wrapper for the JavaScript DashboardControl. This makes the DashboardControl a single entry point for complex settings, such as custom items or custom properties. The DashboardControl configuration is common between all platforms and scripts become universal.

To customize a Dashboard component for Blazor with JavaScript, configure the underlying DashboardControl instance. For this, use properties of the DxJSCustomization class. Review the following help topic for more information: JavaScript Customization of Dashboard Component.

Use the DxResourceManager.RegisterScripts(Action<ResourcesConfigurator>) method to manage client resources and custom scripts. Note that custom scripts that use DashboardControl classes and properties, should be executed after scripts the DxDashboard component requires. For a list of DevExpress resources and their positions, refer to the following help topic: DevExpress Resources.

The following code snippet registers DashboardPanelExtension:

Web Forms Markup

Default.aspx

<script type="text/javascript">
  function onBeforeRender(sender) {
    var dashboardControl = sender.GetDashboardControl();
     dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));     
  }
</script>  
<dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Width="100%" Height="100%" >
<ClientSideEvents BeforeRender="onBeforeRender" />
</dx:ASPxDashboard>

Blazor Server

Dashboard.razor

@page "/"
@using DevExpress.Blazor

@DxResourceManager.RegisterScripts((config) => config.Register(new DxResource("/parameter-item.js", 900)))

<DxDashboard Endpoint="api/dashboard" style="width: 100%; height: 650px;">
    <DxJSCustomization Identifier="dashboardEvents"></DxJSCustomization>
</DxDashboard>

dashboard-events-scripts.js

window.dashboardEvents = {
    onBeforeRender: (args) => {
        // Registers the Parameter item and the Dashboard Panel.
        var dashboardControl = args.component;
        dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));
    },
    // ...
}

Useful Resources

Web Dashboard Technical Overview