Migrate ASPxReportDesigner from Web Forms to ASP.NET Core
- 6 minutes to read
You can migrate customization applied to ASPxReportDesigner to your new .NET application. The component uses HTML/JavaScript and shares core functionality across different web frameworks - the client-side API is the same regardless of the platform, allowing you to migrate the customization code to a new app with minimal adjustments. The custom implementation of Document Designer’s services can lso be migrated to a new application because interface implementation is similar in all web frameworks.
Prerequisites
You may require additional packages to run our Reporting components on Linux or iOS: Use Reporting on Linux.
Important
In .NET 8, the System.Drawing.Common library is compatible with Windows only. An exception is thrown on other platforms. See the following topic for more information: Reporting .NET/.NET Core Limitations.
Create an ASP.NET Core Application
Create a new ASP.NET Core Project. Use Visual Studio or the .NET CLI to create a new project:
dotnet new mvc -o AspNetCoreReportDesigner
Manage Packages and Libraries
Install NuGet Packages
Reference the following package in your application:
For more information on how to install NuGet packages for DevExpress components, review the following help topic: Choose Between Offline and Online DevExpress NuGet Feeds.
Optional NuGet Packages
Install the following package to bundle and minify our static assets:
Install the following package to use Library Manager (LibMan):
Install npm Packages
Right-click the project in the Solution Explorer and select Add | New Item from the context menu. Add npm Configuration File from the Add New Item dialog.
Open the newly created package.json file, replace its content with the following code, and save the file:
{
"version": "1.0.0",
"name": "asp.net",
"private": true,
"dependencies": {
"bootstrap": "^5.3.3",
"devextreme-dist": "24.2-stable",
"@devexpress/analytics-core": "24.2-stable",
"devexpress-reporting": "24.2-stable"
}
}
Right-click package.json in the Solution Explorer and select Restore Packages. Alternatively, you can execute the following command in the folder that contains the package.json file:
npm install
Bundle Resources (bundleconfig.json)
Add a text file (bundleconfig.json) to the project. Open the newly created file, paste the following content, and save the file:
[
{
"outputFileName": "wwwroot/css/thirdparty.bundle.css",
"inputFiles": [
"node_modules/bootstrap/dist/css/bootstrap.min.css",
"node_modules/devextreme-dist/css/dx.light.css"
],
"minify": {
"enabled": false,
"adjustRelativePaths": false
}
},
{
"outputFileName": "wwwroot/css/ace/ace.bundle.css",
"inputFiles": [
"node_modules/ace-builds/css/ace.css",
"node_modules/ace-builds/css/theme/dreamweaver.css",
"node_modules/ace-builds/css/theme/ambiance.css"
],
"minify": {
"enabled": false,
"adjustRelativePaths": false
}
},
{
"outputFileName": "wwwroot/css/designer.part.bundle.css",
"inputFiles": [
"node_modules/@devexpress/analytics-core/dist/css/dx-analytics.common.css",
"node_modules/@devexpress/analytics-core/dist/css/dx-analytics.light.css",
"node_modules/devexpress-reporting/dist/css/dx-webdocumentviewer.css",
"node_modules/@devexpress/analytics-core/dist/css/dx-querybuilder.css",
"node_modules/devexpress-reporting/dist/css/dx-reportdesigner.css"
],
"minify": {
"enabled": false,
"adjustRelativePaths": false
}
},
{
"outputFileName": "wwwroot/js/thirdparty.bundle.js",
"inputFiles": [
"node_modules/jquery/dist/jquery.min.js",
"node_modules/knockout/build/output/knockout-latest.js",
"node_modules/bootstrap/dist/js/bootstrap.min.js",
"node_modules/ace-builds/src-min-noconflict/ace.js",
"node_modules/ace-builds/src-min-noconflict/ext-language_tools.js",
"node_modules/ace-builds/src-min-noconflict/theme-dreamweaver.js",
"node_modules/ace-builds/src-min-noconflict/theme-ambiance.js",
"node_modules/ace-builds/src-min-noconflict/snippets/text.js"
],
"minify": {
"enabled": false
},
"sourceMap": false
},
{
"outputFileName": "wwwroot/js/designer.part.bundle.js",
"inputFiles": [
"node_modules/devextreme-dist/js/dx.all.js",
"node_modules/@devexpress/analytics-core/dist/js/dx-analytics-core.min.js",
"node_modules/devexpress-reporting/dist/js/dx-webdocumentviewer.min.js",
"node_modules/@devexpress/analytics-core/dist/js/dx-querybuilder.min.js",
"node_modules/devexpress-reporting/dist/js/dx-reportdesigner.min.js"
],
"minify": {
"enabled": false
},
"sourceMap": false
}
]
Note
If your application already uses libraries listed above, remove duplicate library references to ensure they are registered only once.
Configure LibMan (libman.json)
Right-click the project in the Solution Explorer and select Manage Client-Side Libraries to open the libman.json file.
Paste the following content and save the file:
{
"version": "1.0",
"defaultProvider": "filesystem",
"libraries": [
{
"library": "node_modules/ace-builds/css/",
"destination": "wwwroot/css/ace",
"files": [ "*.png", "*.svg" ]
},
{
"library": "node_modules/devextreme-dist/css/icons/",
"destination": "wwwroot/css/icons",
"files": [
"dxicons.ttf",
"dxicons.woff2",
"dxicons.woff"
]
}
]
}
For more information on LibMan, review the following article: Use LibMan with ASP.NET Core in Visual Studio.
Implement Skeleton Loading (Optionally)
You can enhance the user experience by rendering the loading animation/placeholder until all JavaScript code is available on the client. Refer to the following topic: Enable the Skeleton Screen in ASP.NET Core Application.
Configure Services on Startup (Program.cs)
All Web Report Designer services that you register in DefaultReportDesignerContainer for ASP.NET Web Forms app can be registered in the built-in DI container in ASP.NET Core applications. You can parameterize and inject other services within the constructors of Document Designer-specific services (for example, IHttpContextAccessor). 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 ReportStorageWebExtension service:
- ASP.NET Web Forms
using DevExpress.XtraReports.Web.Extensions; void Application_Start(object sender, EventArgs e) { // ... DevExpress.XtraReports.Web.Extensions.ReportStorageWebExtension.RegisterExtensionGlobal(new CustomReportStorageWebExtension()); // ... }- ASP.NET Core
using DevExpress.XtraReports.Web.Extensions; // ... var builder = WebApplication.CreateBuilder(args); builder.Services.AddScoped<ReportStorageWebExtension, CustomReportStorageWebExtension>(); // ... var app = builder.Build();
Refer to the following help topic for the services list: Register Services in the Report Designer.
The following code snippet shows the minimum required services for DevExpress Reporting:
using DevExpress.AspNetCore;
//...
var builder = WebApplication.CreateBuilder(args);
//...
// Register reporting services in the application's dependency injection container.
builder.Services.AddDevExpressControls();
builder.Services.ConfigureReportingServices(configurator => {
if(builder.Environment.IsDevelopment()) {
configurator.UseDevelopmentMode();
}
configurator.ConfigureReportDesigner(designerConfigurator => {
});
configurator.ConfigureWebDocumentViewer(viewerConfigurator => {
viewerConfigurator.UseCachedReportSourceBuilder();
});
});
var app = builder.Build();
app.UseDevExpressControls();
// ...
app.Run();
Migrate Controller Logic
ASP.NET Web Forms applications can process designer requests by HTTP handlers registered in the “web.config” file. This option is no longer available. Create the ReportDesignerController controller for ASP.NET Core.
- ASP.NET Core Controller
using DevExpress.AspNetCore.Reporting.ReportDesigner; using DevExpress.AspNetCore.Reporting.ReportDesigner.Native.Services; // ... public class CustomReportDesignerController : ReportDesignerController { public CustomReportDesignerController(IReportDesignerMvcControllerService controllerService) : base(controllerService) { public override Task<IActionResult> Invoke() { return base.Invoke(); } } }
Add a Report
The .cs and .repx reports are cross-platform and can be reused in any platform reporting application. Refer to the following topic for information on how to prepare reports for migration: Migrate DevExpress Reports to .NET Applications.
Adjust Views
The following code sample that displays the Report Designer and loads the TestReport (the using directive is correct if the TestReport is created in the Reports folder):
- Web Forms Markup
<asp:Content ID="Content" ContentPlaceHolderID="MainContent" runat="server"> <dx:ASPxReportDesigner ID="ASPxReportDesigner1" runat="server" ReportSourceId="WebFormsExample.Reports.TestReport"> </dx:ASPxReportDesigner> </asp:Content>- ASP.NET Core View
@using DevExpress.AspNetCore @using AspNetCoreReportDesigner.Reports @(Html.DevExpress().ReportDesigner("reportDesigner") .Height("1000px") .Bind(new TestReport()))
You can also bind the Report Designer to the WebDocumentViewerModel instance, generated in the controller. Refer to the following topic for more information: Bind to a View Model .
Migrate Client-Side Customization
To handle Client-Side events use the ReportDesignerBuilder.ClientSideEvents method. Check the following documentation for more details on how to use Client-Side API in ASP.NET Core application: Report Designer Client-Side API.
- Web Forms Markup
<asp:Content ID="Content" ContentPlaceHolderID="MainContent" runat="server"> <dx:ASPxReportDesigner ID="ASPxReportDesigner1" runat="server" ReportSourceId="WebFormsExample.Reports.TestReport" > <ClientSideEvents BeforeRender="onbeforeRender"/> </dx:ASPxReportDesigner> </asp:Content>- ASP.NET Core View
@(Html.DevExpress().ReportDesigner("clientInstanceName") .Height("1000px") .ClientSideEvents(configure => { configure.BeforeRender("onBeforeRender"); }) .Bind(new TestReport()))
Use the ReportDesignerClientSideEventsBuilder object’s Preview method to handle client-side events for the Report Designer’s integrated Document Viewer:
@(Html.DevExpress().ReportDesigner("clientInstanceName")
.Height("1000px")
.ClientSideEvents(configure => {
configure.Preview(c => { c.CustomizeElements("previewCustomizeElements"); });
})
.Bind(new TestReport()))
Useful Resources
The “Reporting Best Practices” repository contains an example application to demonstrate best practices when you design a web reporting application in ASP.NET Core MVC or ASP.NET Core as a backend with an Angular application as a frontend.
Review the following help topic for more information: ASP.NET Core and Angular Reporting Best Practices.