<!-- default badges list -->

<!-- default badges end -->

ASP.NET Core Reporting - Best Practices

Introduction

This README file describes best practices to follow when you develop a web application with DevExpress reporting controls.

This repository also contains an example application that demonstrates the described techniques. This application is split into three projects:

• AspNetCore.Reporting.MVC - An ASP.NET Core MVC application.
• AspNetCore.Reporting.Angular - An application with ASP.NET Core backend and Angular frontend.
• AspNetCore.Reporting.Common - Implements services and business logic for the MVC and Angular projects.

You can use the example code in your web application and modify it for different scenarios.

Table of Contents:

• How to Run the Example Application
  • Configure NuGet
  • Install NPM Dependencies
  • Start the Application
• Switch to Asynchronous Mode
• Optimize Memory Consumption
• Manage Database Connections
• Application Security
  • Prevent Cross-Site Request Forgery
  • Token-based Authentication
  • Token-based Authentication in Angular
  • Implement User Authorization
• Handle Exceptions
  • Log Errors that Occurred in the Code of DevExpress Reporting Components
  • Use Custom Exception Handlers
• Prepare Skeleton Screen
• Localize Client UI

How to Run the Example Application

Follow the steps below to run the example application in Microsoft Visual Studio.

Configure NuGet

To run the example application, you need to install packages from the DevExpress NuGet feed. Use the following steps to configure NuGet:

1. Obtain Your NuGet Feed URL
2. Register the NuGet feed as a package sources

Install NPM Dependencies

• For the ASP.NET Core MVC project, run npm install in the project's root folder.
• For the Angular project, navigate to the AspNetCore.Reporting.Angular.Client directory and run npm install.

Note: If you change the version of DevExpress NuGet packages used in the example application, make sure you also specify the matching minor versions for DevExpress client libraries in the package.json file.

Start the Application

Press the Run button or F5 to run the example application.

Switch to Asynchronous Mode

Call the UseAsyncEngine method at application startup to use asynchronous counterparts of Reporting API interfaces and methods.

ServiceRegistrator.cs

services.ConfigureReportingServices(configurator => {
    // ...
    configurator.UseAsyncEngine();
});

If a reporting control binds to a report model (the WebDocumentViewerModel instance), the reporting engine uses asynchronous API calls. You should generate a report model in the controller and pass the model to the Document Viewer.

If a reporting control is bound to a report instance or a string (report name), reporting engine does not use asynchronous methods and interfaces.

Optimize Memory Consumption

This section describes how to optimize a reporting application's memory consumption, and prevent memory leaks and cluttering on the server.

Refer to the Document Viewer Lifecycle for information oh how the Document Viewer stores report data on different lifecycle stages.

To optimize memory consumption, use the following techniques:

• Configure the Document Viewer to store server data on disk instead of memory. This reduces the memory consumption at the cost of performance.

  ServiceRegistrator.cs

  configurator.ConfigureWebDocumentViewer(viewerConfigurator => {
      // StorageSynchronizationMode.InterThread - it is a default value, use InterProcess if you use multiple application instances without ARR Affinity
      viewerConfigurator.UseFileDocumentStorage(Path.Combine(contentRootPath, "ViewerStorages\\Documents"), StorageSynchronizationMode.InterThread);
      viewerConfigurator.UseFileExportedDocumentStorage(Path.Combine(contentRootPath, "ViewerStorages\\ExportedDocuments"), StorageSynchronizationMode.InterThread);
      viewerConfigurator.UseFileReportStorage(Path.Combine(contentRootPath, "ViewerStorages\\Reports"), StorageSynchronizationMode.InterThread);
      viewerConfigurator.UseCachedReportSourceBuilder();
  });
  

• To allow users to close a page or a UI region (for example, a pop-up window) that displays the Document Viewer, you should first call the Document Viewer's client-side Close method to close the viewed report and release the server resources (the Storage space and Cache):

  DisplayReport.cshtml

  function WebDocumentViewer_BeforeRender(s, e) {
      $(window).on('beforeunload', function(e) {
          s.Close();
      });
  }
  

• Configure Storage and Cache cleaners on application startup. This allows you to specify how long you want to reserve resources to store document data on the server. Note that after a document's data is removed for the Storage and Cache, you cannot navigate or print this document.

  ServiceRegistrator.cs

  var cacheCleanerSettings = new CacheCleanerSettings(TimeSpan.FromMinutes(1), TimeSpan.FromSeconds(30), TimeSpan.FromMinutes(2), TimeSpan.FromMinutes(2));
  services.AddSingleton<CacheCleanerSettings>(cacheCleanerSettings);
  
  var storageCleanerSettings = new StorageCleanerSettings(TimeSpan.FromMinutes(5), TimeSpan.FromMinutes(30), TimeSpan.FromHours(12), TimeSpan.FromHours(12), TimeSpan.FromHours(12));
  services.AddSingleton<StorageCleanerSettings>(storageCleanerSettings);
  

Keep in mind that .NET is a managed environment, so data saved to the disk storage and removed from cache remains in memory until .NET runs garbage collection. Refer to the Fundamentals of garbage collection article for more information.

Manage Database Connections

DevExpress reporting components are configured to retrieve database connections from the application configuration file. This mechanism is secure: a serialized report contains only the connection name. If you implement a custom connection provider to customize this mechanism (for example, to filter the list of connections), ensure you serialize only the data connection's name and do not pass connection parameters to the client.

Reporting services obtain an IConnectionProviderFactory and IDataSourceWizardConnectionStringsProvider interfaces through Dependency Injection. For instructions on how to implement these services, refer to the following example project's files:

• Services/Reporting/CustomSqlDataConnectionProviderFactory.cs
• Services/Reporting/CustomSqlDataSourceWizardConnectionStringsProvider.cs

To ensure that encrypted connection parameters for SqlDataSource instances are not passed to the client, return null from the IDataSourceWizardConnectionStringsProvider.GetDataConnectionParameters method's implementation:

[CustomSqlDataSourceWizardConnectionStringsProvider.cs](AspNetCore.Reporting.Common/Services/Reporting/CustomSqlDataSourceWizardConnectionStringsProvider.cs#