Migrate ASPxWebDocumentViewer from Web Forms to ASP.NET Core

• Dec 30, 2024
• 6 minutes to read

You can migrate customization applied to ASPxWebDocumentViewer 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 Viewer’s services can lso be migrated to a new application because interface implementation is similar in all web frameworks.

Prerequisites

• .NET 8.0 or later SDK
• Visual Studio 2022 v17.3+

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 AspNetCoreDocumentViewer

Manage Packages and Libraries

Install NuGet Packages

Reference the following package in your application:

• DevExpress.AspNetCore.Reporting

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:

• BuildBundlerMinifier

Install the following package to use Library Manager (LibMan):

• Microsoft.Web.LibraryManager.Build

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:

package.json

{
    "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)

Create a new JSON file, name it bundleconfig.json, and add it to the project. Open the newly created file, paste the following content, and save the file:

bundleconfig.json

[
    {
    "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/viewer.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"
    ],
    "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/devextreme-dist/js/dx.all.js",
        ],
    "minify": {
        "enabled": false
    },
    "sourceMap": false
    },
    {
    "outputFileName": "wwwroot/js/viewer.part.bundle.js",
    "inputFiles": [
        "node_modules/@devexpress/analytics-core/dist/js/dx-analytics-core.min.js",
        "node_modules/devexpress-reporting/dist/js/dx-webdocumentviewer.min.js"
        ],
    "minify": {
        "enabled": false
    },
    "sourceMap": false
    }
]

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 to add fonts and icons to your application:

libman.json

{
    "version": "1.0",
    "defaultProvider": "filesystem",
    "libraries": [

    {
        "library": "node_modules/devextreme-dist/css/icons/",
        "destination": "wwwroot/css/icons",
        "files": [
        "dxicons.ttf",
        "dxicons.woff2",
        "dxicons.woff"
        ]
    }
    ]
}

Note

If your application already uses the libraries listed above, remove duplicate library references to ensure they are registered only once.

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 Document Viewer services that you register in DefaultWebDocumentViewerContainer 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 Viewer-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

C#

using DevExpress.XtraReports.Web.Extensions;
// ...
void Application_Start(object sender, EventArgs e) {

    ReportStorageWebExtension.RegisterExtensionGlobal(new CustomReportStorageWebExtension());
}

ASP.NET Core

C#

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 Document Viewer in ASP.NET Core Application.

The following code snippet shows the minimum required services for DevExpress Reporting:

Program.cs

using DevExpress.AspNetCore;
using DevExpress.AspNetCore.Reporting;

var builder = WebApplication.CreateBuilder(args);

// Add services
builder.Services.AddControllersWithViews();
builder.Services.AddDevExpressControls();

builder.Services.ConfigureReportingServices(configurator => {
    configurator.ConfigureWebDocumentViewer(viewerConfigurator => {
        viewerConfigurator.UseCachedReportSourceBuilder();
    });
});

var app = builder.Build();

app.UseDevExpressControls();
System.Net.ServicePointManager.SecurityProtocol |= System.Net.SecurityProtocolType.Tls12;

app.Run();

Migrate Controller Logic

Some ASP.NET Web Forms applications can process viewer requests by HTTP handlers registered in the “web.config” file. This option is no longer available. Create the WebDocumentViewerController controller for ASP.NET Core.

ReportingControllers.cs

using DevExpress.AspNetCore.Reporting.WebDocumentViewer;
using DevExpress.AspNetCore.Reporting.WebDocumentViewer.Native.Services;
// ...
public class CustomWebDocumentViewerController : WebDocumentViewerController {
    public CustomWebDocumentViewerController(IWebDocumentViewerMvcControllerService 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 displays the Document Viewer and loads the TestReport (the using directive is correct if the TestReport is created in the Reports folder):

Web Forms Markup

Default.aspx

<asp:Content ID="Content" ContentPlaceHolderID="MainContent" runat="server">
    <dx:ASPxWebDocumentViewer ID="ASPxWebDocumentViewer1" runat="server" ReportSourceId="WebFormsExample.Reports.TestReport" >
    </dx:ASPxWebDocumentViewer>
</asp:Content>

ASP.NET Core View

DocumentViewer.cshtml

@using DevExpress.AspNetCore.Reports

@Html.DevExpress().WebDocumentViewer("DocumentViewer")
    .Height("1000px")
        .Bind(new TestReport())

You can also bind the Document Viewer 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 WebDocumentViewerBuilder.ClientSideEvents() method. Check the following documentation for more details on how to use Client-Side API in ASP.NET Core application: Document Viewer Client-Side API.

Web Forms Markup

Default.aspx

<asp:Content ID="Content" ContentPlaceHolderID="MainContent" runat="server">
    <dx:ASPxWebDocumentViewer ID="ASPxWebDocumentViewer1" runat="server" ReportSourceId="WebFormsExample.Reports.TestReport" >
       <ClientSideEvents BeforeRender="onbeforeRender"/>
    </dx:ASPxWebDocumentViewer>
</asp:Content>

ASP.NET Core View

DocumentViewer.cshtml

@Html.DevExpress().WebDocumentViewer(settings => {
    settings.Name = "clientInstanceName";
    settings.Height = Unit.Pixel(1000);
    settings.ClientSideEvents.BeforeRender = "onBeforeRender";
}).Bind(new TestReport()).GetHtml()

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.