Add a Report Storage

• Sep 28, 2020
• 7 minutes to read

Design Considerations

When you add the End-User Report Designer for Web to your project, it operates without a report storage. You should consider whether your application requires a custom report storage and think ahead about the implementation details. The table below lists the functions that will be unavailable to end users without a report storage registered in your application.

Commands/Functions	With Storage	Without Storage
Save
Save As
Open
New
New via Wizard
Manage Subreports

As you can see in the table above, you can edit a report, but cannot manipulate multiple stored report definitions. If these limitations are suitable for your application, you can work with reports without a custom storage.

Operation without a Report Storage

Initially the Report Designer operates without the New via Wizard, Open and Save As menu commands. This operation mode also doesn’t allow end users to manage Subreports - a double click on a subreport has no effect.

The client-side API methods that allows you to load and save a report do not work without a report storage.

If you specify a report URL in the Report Designer’s Bind method, the Report Designer attempts to use the report storage to retrieve a report. Without a report storage, an exception is thrown.

Operation with a Report Storage

To save and load reports, the DevExpress Web Report Designer requires access to a storage medium (a database, file system, cloud service, etc.). To add a server-side report storage medium to your web application, you must create and register a custom report storage class.

Create and Register a Report Storage

Follow the steps below to create a server-side storage for web reports.

Create a Report Storage Class

Create a class that inherits from the abstract ReportStorageWebExtension class. You can write a new class or use the DevExpress Project Wizard.

If you use the DevExpress Project Wizard, leave the Add Report Storage option checked. The wizard generates and registers a file system report storage. You can specify the class name in the Report Storage Name field:

DevExpress Project Templates always create and register a file-based report storage if you create a project from the console (CLI).

Important

The template generates a sample storage (a ReportStorageWebExtension descendant) for demonstration purposes only. Create your own implementation for use in production.

Override Class Methods

You need to implement the following methods:

Method	Description
IsValidUrl	Determines whether the URL passed to the current report storage is valid. Implement your own logic to prohibit URLs that contain spaces or other specific characters. Return true if no validation is required.
CanSetData	Determines whether a report with the specified URL can be saved. Add custom logic that returns false for reports that should be read-only. Return true if no valdation is required. This method is called only for valid URLs (if the IsValidUrl method returns true).
SetData	Saves the specified report to the report storage with the specified URL (i.e., it saves existing reports only).
SetNewData	Allows you to validate and correct the specified URL. This method also allows you to return the resulting URL and to save your report to a storage medium. The method is called only for new reports.
GetData	Uses a specified URL to return report layout data stored within a report storage medium. This method is called if the IsValidUrl method returns true. You can use the GetData method to process report parameters sent from the client if the parameters are included in the report URL’s query string.
GetUrls	Returns a dictionary that contains the report URLs and display names.

In the following table, select a column that describes the user action. Then, read the entries top to bottom to learn the order of method calls. The table also indicates the moments when the designer invokes Open Report and Save Report dialogs.

Method/Command	Save As	Save	Open
GetUrls
(Open Report dialog)
IsValidUrl
CanSetData
(Save Report dialog)
SetNewData
SetData
GetData
GetUrls

For more information on how the reports and documents are stored, review the following help topic: Store Report Layouts and Documents.

Register a Storage

Skip this step if you used a project template to generate your report storage class. If you declared a ReportStorageWebExtension descendant manually, register your web report storage medium as a service in the ConfigureServices method at application startup:

Startup.cs

using DevExpress.XtraReports.Web.Extensions;
//... 

    public class Startup {
        // ...

        public void ConfigureServices(IServiceCollection services) {
            // ...
            services.AddDevExpressControls();
            // Register the storage after the AddDevExpressControls method call.
            services.AddScoped<ReportStorageWebExtension, ReportStorageWebExtension1>(); 
            // ...  
        }
    // ...
    }    

Important

Register the ReportStorageWebExtension after the AddDevExpressControls method.

Report Storage Examples

• How to store reports in a file system:

  Note

  If you’d like to store reports in a file system, please refer to the following help topic for additional information/guidance: Create an ASP.NET Core Application with a Report Designer.

  Show code

  ReportStorageWebExtension1.cs

  using DevExpress.XtraReports.UI;
  using DXWebApplication9.PredefinedReports;
  using Microsoft.AspNetCore.Hosting;
  using System;
  using System.Collections.Generic;
  using System.IO;
  using System.Linq;
  
  namespace DXWebApplication1.Services
  {
      public class ReportStorageWebExtension1 : DevExpress.XtraReports.Web.Extensions.ReportStorageWebExtension
      {
          readonly string ReportDirectory;
          const string FileExtension = ".repx";
          public ReportStorageWebExtension1(IWebHostEnvironment env) {
              ReportDirectory = Path.Combine(env.ContentRootPath, "Reports");
              if (!Directory.Exists(ReportDirectory)) {
                  Directory.CreateDirectory(ReportDirectory);
              }
          }
  
          public override bool CanSetData(string url) {
              // Determines whether or not it is possible to store a report by a given URL. 
              // For instance, make the CanSetData method return false for reports that should be read-only in your storage. 
              // This method is called only for valid URLs (i.e., if the IsValidUrl method returned true) before the SetData method is called.
  
              return true;
          }
  
          public override bool IsValidUrl(string url) {
              // Determines whether or not the URL passed to the current Report Storage is valid. 
              // For instance, implement your own logic to prohibit URLs that contain white spaces or some other special characters. 
              // This method is called before the CanSetData and GetData methods.
  
              return true;
          }
  
          public override byte[] GetData(string url) {
              // Returns report layout data stored in a Report Storage using the specified URL. 
              // This method is called only for valid URLs after the IsValidUrl method is called.
              try {
                  if (Directory.EnumerateFiles(ReportDirectory).Select(Path.GetFileNameWithoutExtension).Contains(url))
                  {
                      return File.ReadAllBytes(Path.Combine(ReportDirectory, url + FileExtension));
                  }
                  if (ReportsFactory.Reports.ContainsKey(url))
                  {
                      using (MemoryStream ms = new MemoryStream()) {
                          ReportsFactory.Reports[url]().SaveLayoutToXml(ms);
                          return ms.ToArray();
                      }
                  }
                  throw new DevExpress.XtraReports.Web.ClientControls.FaultException(string.Format("Could not find report '{0}'.", url));
              } catch (Exception) {
                  throw new DevExpress.XtraReports.Web.ClientControls.FaultException(string.Format("Could not find report '{0}'.", url));
              }
          }
  
          public override Dictionary<string, string> GetUrls() {
              // Returns a dictionary of the existing report URLs and display names. 
              // This method is called when running the Report Designer, 
              // before the Open Report and Save Report dialogs are shown and after a new report is saved to a storage.
  
              return Directory.GetFiles(ReportDirectory, "*" + FileExtension)
                                       .Select(Path.GetFileNameWithoutExtension)
                                       .Concat(ReportsFactory.Reports.Select(x => x.Key))
                                       .ToDictionary<string, string>(x => x);
          }
  
          public override void SetData(XtraReport report, string url) {
              // Stores the specified report to a Report Storage using the specified URL. 
              // This method is called only after the IsValidUrl and CanSetData methods are called.
              report.SaveLayoutToXml(Path.Combine(ReportDirectory, url + FileExtension));
          }
  
          public override string SetNewData(XtraReport report, string defaultUrl) {
              // Stores the specified report using a new URL. 
              // The IsValidUrl and CanSetData methods are never called before this method. 
              // You can validate and correct the specified URL directly in the SetNewData method implementation 
              // and return the resulting URL used to save a report in your storage.
              SetData(report, defaultUrl);
              return defaultUrl;
          }
      }
  }
  

• How to store reports in Azure Cosmos DB:

  Review the ASP.NET Core Reporting - Store Reports within a Database Using Azure Cosmos DB blog post.