Add a Document Viewer to a DevExtreme ASP.NET Core Application

• Oct 01, 2024
• 6 minutes to read

Follow this step-by-step tutorial to add a Document Viewer to a DevExtreme ASP.NET Core application. The guide includes information about prerequisites, npm configuration, library management, application and services setup, sample report creation, troubleshooting, and limitations.

Prerequisites

• .NET 8.0 or later SDK
• Visual Studio 2022 (v17.0) or higher
• Node.js
• Unified Component Installer

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 a DevExtreme ASP.NET Core Application

Create a new DevExtreme ASP.NET Core Application from a template.

Set application type to Razor Pages and a layout to Bootstrap.

A detailed guide you can find in the following help topic: ASP.NET Core DevExtreme Getting Started .

Install NuGet Packages

Follow the steps below to install NuGet packages:

1. Right-click Dependencies in the Solution Explorer and select Manage NuGet Packages from the context menu.

   

2. Install the following packages:

   • BuildBundlerMinifier
   • 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.

Configure npm

1. Right-click the project in the Solution Explorer and select Add | New Item from the context menu. Select npm Configuration File in the invoked 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": {
       "@devexpress/analytics-core": "24.1-stable",
       "bootstrap": "^4.3.1",
       "devexpress-reporting": "24.1-stable"
       }
   }
   

2. 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
   

Manage Libraries

You must register JS and CSS resources once and in the correct order. Otherwise, client-side errors may occur, as described in the following help topic: Reporting Application Diagnostics.

To create resource bundles, add a new bundleconfig.json file with the following content (or modify the content of an existing bundleconfig.json file if needed):

bundleconfig.json

[
  {
    "outputFileName": "wwwroot/js/vendor.js",
    "inputFiles": [
      "node_modules/knockout/build/output/knockout-latest.js",
    ],
    "minify": {
      "enabled": false
    }
  },
  {
    "outputFileName": "wwwroot/css/reporting.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/reporting.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
  }
]

Note that third-party bundles are merged into vendor bundles. Libraries specific to the Document Viewer are included in the related bundles.

Configure Application and Services

1. Open the Program.cs file and modify the code as shown in the following code snippet:

   Program.cs

   var builder = WebApplication.CreateBuilder(args);
   //...
   builder.Services.AddDevExpressControls();
   // ...
   var app = builder.Build();
   //...
   app.UseDevExpressControls();
   //...
   app.Run();
   

2. Implement a controller to process the Document Viewer requests. In the Controllers folder, create the ReportingControllers.cs file with the following content:

   ReportingController.cs

   using DevExpress.AspNetCore.Reporting.WebDocumentViewer;
   using DevExpress.AspNetCore.Reporting.WebDocumentViewer.Native.Services;
   
   public class CustomWebDocumentViewerController : WebDocumentViewerController {
       public CustomWebDocumentViewerController(IWebDocumentViewerMvcControllerService controllerService)
           : base(controllerService) {    }
   }
   

Add a Sample Report

1. Right-click the project in the Solution Explorer and select Add | New Folder from the context menu. Rename the created folder to Reports.

2. Right-click the Reports folder and select Add | New Item from the context menu. In the invoked Add New Item dialog, click the Reporting tree node and select DevExpress v24.1 Report.

   

   Rename the new report to TestReport and click Add.

3. Select the Blank report type in the invoked Report Wizard. The Report Designer displays the newly created blank report.

4. Drop an XRLabel from the Toolbox to the Detail band and rename the label to Hello, world!. Save the report and close the designer.

See the following section for more information about creating reports in Visual Studio: Create a Report from A to Z.

Add the Document Viewer Component

1. Add the DevExpress.AspNetCore namespace directive to the _ViewImports.cshtml file. As an alternative, you can add this namespace to the view that contains the Document Viewer control.

   Pages/_ViewImports.cshtml

   @using DevExpress.AspNetCore
   

2. Add a new page (Viewer.cshtml) to the Page folder with the following code, which displays the Document Viewer and loads the TestReport:

   Note

   If you implement a custom report that inherits from XtraReport and want to open it in the End-User Report Designer, add a constructor without parameters to this report.

   Pages/Viewer.cshtml

   @page
   
   <link rel="stylesheet" href="~/css/reporting.viewer.part.bundle.css" />
   <script src="~/js/reporting.viewer.part.bundle.js"></script>
   
   @Html.DevExpress().WebDocumentViewer("DocumentViewer").Height("1000px").Bind(new Reports.TestReport())
   

   The page includes script and style bundles related to the Document Viewer. The bundles are defined in the bundleconfig.json file.

3. Open the _Layout.cshtml file (Pages/Shared folder). Include the vendor.js bundle that contains the Knockout library before the DevExtreme library. Add a link to the Viewer.cshtml page.

   Pages/Shared/_Layout.cshtml

   @*___*@
   <script src="~/js/vendor.js"></script>
   <script src="~/js/devextreme/jquery.js"></script>
   <script src="~/js/devextreme/bootstrap.js"></script>
   @*___*@
       <div id="navbar" class="collapse navbar-collapse">
           <ul class="navbar-nav mr-auto">
               <li class="active nav-item"><a href="#" class="nav-link">Home</a></li>
               <li class="nav-item"><a href="#about" class="nav-link">About</a></li>
               <li class="nav-item"><a href="#contact" class="nav-link">Contact</a></li>
               <li class="nav-item"><a href="/Viewer" class="nav-link">Document Viewer</a></li>
           </ul>
       </div>
   @*___*@
   

Run the Application

When you run the application, the page contains the Document Viewer with the TestReport:

Troubleshooting

If the page does not display the Document Viewer component, or it is displayed incorrectly, check the following:

• The script files should be registered in the correct order, as demonstrated in the bundleconfig.json code above. For more information, review the following help topic: Script Registration Order.
• There should be no duplicate registrations. Component bundles should be included in the pages that contain the component.
• The version of the DevExpress scripts (npm packages) should match the version of the server-side libraries (NuGet packages). You can enable Development Mode to check for library version mismatch on every request to the server. For more information, review the following help topic: Server-Side Libraries Version.

Review the following help topic for more information: Troubleshooting.

Limitations

Review the following help topic for details: Reporting .NET/.NET Core Limitations.

What’s Next

You have now completed a basic DevExtreme ASP.NET Core App with a Document Viewer control. Refer to the following articles for more information on Reporting features:

Create a Report from A to Z

View step-by-step tutorials that demonstrate how to create a simple table report.

Open a Report in Document Viewer

Explore ways to display a report in a Document Viewer Control.

Document Viewer Customization

Customize Document Viewer elements.

Mobile Mode in Document Viewer

Enable mobile mode in the Document Viewer.

Cloud Integration

Deploy and integrate DevExpress Reporting applications with cloud services.