Microsoft Azure Reporting
- 8 minutes to read
This document describes the specifics of running reporting applications in the Microsoft Azure environment.
Report Generation Specifics
PDF Fonts
The PDF export engine used in DevExpress Reporting relies on system GDI calls, some of which are not supported on Azure.
The export engine detects whether it is allowed to embed PDF fonts. To disable automatic detection and switch to using non-embedded fonts, set the AzureCompatibility.Enable property to true.
void Application_Start(object sender, EventArgs e) {
DevExpress.Utils.AzureCompatibility.Enable = true;
}
When a web app is hosted under the Free or Shared plan, right-to-left languages do not render correctly.
With these hosting plans (or when the AzureCompatibility.Enable property is set to true), only non-embedded fonts are supported.
Image Rendering
The XRPictureBox report control allows you to use vector images in SVG format.
The following graphical report controls are not supported by Azure, because they are rendered to the Windows Metafile format by default:
To enable rendering these controls on Azure, do one of the following:
Set the AzureCompatibility.Enable property to true at the application startup. This changes their rendering format to Bitmap internally.
Manually change the image rendering format for these controls.
Control Setting XRGauge Set the XRGauge.ImageType property to GaugeImageType.Bitmap. WinControlContainer Set the WinControlContainer.ImageType property to WinControlImageType.Bitmap.
Note
Currently, 3D charts are not supported in the Azure environment.
Hosting Specifics
The following table illustrates the support for different Azure hosting options by the HTML5 Web Document Viewer and Web Report Designer controls:
| Hosting Option | Web Document Viewer | Web Report Designer |
|---|---|---|
| A single instance of a web app or cloud service. | Yes. | Yes. |
| Multiple instances of web apps or cloud services with the Session affinity enabled. | Yes. | Yes. |
| Multiple instances of web apps or cloud services with the Session affinity disabled. | Yes. | No. |
Hosting on a Single Cloud Service Instance or Web Apps (or on multiple instances with the Session affinity enabled)
Before running web reporting controls on Azure, do the following:
Install the required packages using one of the following ways:
Install the DevExpress.Web.Reporting.Azure NuGet package that provides services specifically designed to work with web reporting applications in the Microsoft Azure environment.
Install the WindowsAzure.Storage version 6.1.0+ NuGet package required to communicate with the Azure Storage service in your project. Then, manually add the DevExpress.XtraReports.v18.2.Web.Azure.dll assembly to your project’s reference files.
Call the AzureWebDocumentViewerContainer.UseAzureEnvironment method with the specified connection to Azure Storage at the application startup.
using DevExpress.XtraReports.Web.Azure.WebDocumentViewer; // ... protected void Application_Start(object sender, System.EventArgs e) { AzureWebDocumentViewerContainer.UseAzureEnvironment(cloudStorageConnectionString); }Calling this method switches some Web Document Viewer’s internal services to services specifically designed for the decentralized environment of Azure. This also affects the Web Report Designer, which uses the Web Document Viewer internally to display a document preview.
The Web Report Designer encrypts all information about data connections, which pass to the client by default. To store this information in an Azure Table storage instead, call the AzureReportDesignerContainer.UseAzureEnvironment method with the specified connection to Azure Storage at the application startup.
using DevExpress.XtraReports.Web.Azure.ReportDesigner;
// ...
protected void Application_Start(object sender, System.EventArgs e) {
AzureReportDesignerContainer.UseAzureEnvironment(cloudStorageConnectionString);
}
Hosting on Multiple Cloud Service Instances with the Session affinity disabled
The HTML5 Web Document Viewer can be hosted on multiple cloud service instances with the Session affinity disabled.
Note
The Web Report Designer does not currently support this feature.
An Azure storage account is required to persist report definitions and documents in Azure storage (that is, to enable the Document Viewer to preserve its state after restarting an app).
An Azure storage account replication (LRS, ZRS, GRS, RA-GRS) should be selected based on how your application or cloud service deploys. Zone Redundant Storage (ZRS) is not suitable because it only works with blob containers while both tables and blobs are required for Web Document Viewer hosting.
To scale a web application among multiple instances, you can either set up the Viewer for a Service Bus or enable synchronous document creation.
Using a Service Bus
A Service Bus tier should be Standard or Premium (because both Sessions and Topics are required).
To add a Service Bus to your project, add a reference to the WindowsAzure.ServiceBus 2.7.0+ NuGet package. Note that this package is automatically installed together with the DevExpress.Web.Reporting.Azure NuGet package.
To use a service bus, call the static AzureWebDocumentViewerContainer.UseAzureEnvironment method with a parameter specifying a connection string to access the service bus. Next, call the ASPxWebDocumentViewer.StaticInitialize method that registers the corresponding request handler.
using DevExpress.XtraReports.Web; using DevExpress.XtraReports.Web.Azure.WebDocumentViewer; // ... protected void Application_Start(object sender, System.EventArgs e) { AzureWebDocumentViewerContainer.UseAzureEnvironment(cloudStorageConnectionString, serviceBusConnectionString); ASPxWebDocumentViewer.StaticInitialize(); }Using Synchronous Document Creation
When you do not have a Service Bus, you need to enable synchronous report creation for the Web Document Viewer. Create a custom WebDocumentViewerOperationLogger implementation and manually call the XtraReport.CreateDocument method in the WebDocumentViewerOperationLogger.BuildStarting method.
using DevExpress.XtraReports.UI; using DevExpress.XtraReports.Web.ReportDesigner; using DevExpress.XtraReports.Web.WebDocumentViewer; public class CustomLogger : WebDocumentViewerOperationLogger { public override Action BuildStarting(string reportId, string reportUrl, XtraReport report, ReportBuildProperties buildProperties) { report.CreateDocument(); return null; } // ... }At the application startup, call the AzureReportDesignerContainer.UseAzureEnvironment method with the specified connection to Azure Storage, register your custom WebDocumentViewerOperationLogger implementation and call the ASPxWebDocumentViewer.StaticInitialize method to register the corresponding request handler.
using DevExpress.XtraReports.Web; using DevExpress.XtraReports.Web.Azure.WebDocumentViewer; // ... protected void Application_Start(object sender, System.EventArgs e) { AzureWebDocumentViewerContainer.UseAzureEnvironment(cloudStorageConnectionString); DefaultWebDocumentViewerContainer.RegisterSingleton<WebDocumentViewerOperationLogger, CustomLogger>(); ASPxWebDocumentViewer.StaticInitialize(); }If you want to use the report’s parameters or interactive capabilities (such as drill-down or interactive sorting), open this report in the Web Document Viewer by URL instead of passing the report instance to the Viewer. The report instance is not available on other machines that can handle the corresponding HTTP requests. To load reports by URLs, either register a report storage or use a custom IWebDocumentViewerReportResolver implementation.
Report Serialization
When the UseAzureEnvironment setting is enabled, the report definition is serialized to XML (that is, REPX files are stored in a Blob Storage).
The report instance is needed to process a request (such as submitting report parameter values or restoring a drill-drown/drill-through/interactive sorting state) in the following cases:
- When a viewer’s request comes to another server instance (that is, when using multiple server instances at once).
- When a viewer’s request comes to a single server instance, but the app pool has been turned off by timeout, and the report must be restored once again.
In these cases, the report instance is restored from an XML file. For this reason, on passing a report instance to a viewer, only settings serialized to XML are restored (the rest of the report settings are lost).
To customize a report restored from XML, you can use a custom WebDocumentViewerOperationLogger implementation.
Implementing Custom Storages
Microsoft Azure is a distributed system, and virtual machines are shared between different clients. The information stored on a virtual machine can be lost when a Load Balancer turns this machine off and switches to a new machine.
To avoid such a loss of information, the Web Document Viewer uses Table Storage to keep service information and Blob Storage to save document files. If required, you can replace these storages with custom ones.
To customize tables and blob storages, you need to replace the corresponding service interfaces in the container:
Note
A Web Document Viewer creates and uses tables named “dxxrreports“ and “dxxrdocuments“, along with a blob container named “dxxrcommonstorage“ by default.
Caching Options
Azure Caching Settings
The CacheCleanerSettings class provides a cache for storing documents and reports to optimize memory usage. It determines how long cached documents and reports should be stored. The default caching settings are as follows:
- Report: 2 minutes.
- Document: 1 minute.
To customize the default settings, register a new instance of this class with the necessary time settings.
using DevExpress.XtraReports.Web.WebDocumentViewer;
// ...
protected void Application_Start(object sender, System.EventArgs e) {
DefaultWebDocumentViewerContainer.RegisterSingleton<CacheCleanerSettings>(new CacheCleanerSettings(dueTime, period, reportTimeToLive, documentTimeToLive));
}
Document Caching
No document caching is required when using the newer ASPxWebDocumentViewer control that utilizes the HTML5/JS technology and provides asynchronous document building out of the box.
If you are using the older ASPxDocumentViewer control in your Azure application, bear in mind that document generation is triggered every time a user navigates between pages of the displayed document, which may result in a suboptimal frequency of calls to an Azure-hosted database. To use the database access optimally, implement document caching on the side of your web application by handling the following events:
ASP.NET Web Forms
APS.NET MVC