Web Document Viewer Cache Management
- 9 minutes to read
This help topic explains the caching mechanism used in the DevExpress Web Document Viewer. It describes the two levels of caching: short-term (in memory) and long-term (storage), and the types of storage that you can use. The document contains tips to help you choose the type of caching for your application.
Overview
Document Generation
When the Web Viewer loads a report, the report creation process starts in the background thread. There are two scenarios depending on the source object used for document generation, as shown in the following table:
| Document Generation Source | Scenario |
|---|---|
| XtraReport instance | The document is always cached in memory. Later, when the document is ready, it is serialized and pushed to the Storage. |
| Call the UseCachedReportSourceBuilder (WebForms) or UseCachedReportSourceBuilder (ASP.NET Core) method. | The document is created page by page in the Storage. While the document is being generated, the cached report source loads pages into the Storage. Finally, the cached report source updates only the page data that changed after all the pages were created. |
The Importance of Caching
Web Document Viewer loads displayed data from the server on demand, page by page. For this reason, it is necessary to organize the temporary information storage between requests.
A report cache allows you to avoid excessive document generation operations. If you store the entire document in the server cache for a certain period of time, you can optimize application performance in the following cases:
- A user exports a report to different formats.
- A user navigates between pages.
- A user searches for text in a document.
Caching Levels
Caching Mechanism
When the web page refreshes, the Document Viewer creates a new instance of the report and the document, and places each instance in the related cache. The previous document is not cleared from the cache because the Viewer cannot determine that the previous session has expired. You can subscribe to the window.onbeforeunload event and call the client-side Close method to notify the server of this action:
function onBeforeRender(s, e) {
$(window).on('beforeunload', function(e) {
s.Close();
});
Memory is managed automatically by Garbage Collector, so there is no guarantee that memory is released once the user leaves the page.
If you implement a cache storage, additional memory is still needed to render the web page, but overall consumption could be much lower.
The Document Viewer uses two caching levels:
Short-Term Cache (In-Memory Cache)
The fastest cache, which ensures fast execution of frequent operations. This cache holds object models rather than serialized data. The cache stores report layouts and documents as objects in memory. These objects and their metadata are serialized in long-term storage (in the form of report layouts and documents) when they are used regularly.
Document or report objects are unloaded from memory in the following situations:
- The .NET application process terminates.
- The cache is expired. Use the CacheCleanerSettings to configure the expiration policy.
- The Close command is forwarded from the browser. The objects are disposed of and unloaded from memory. The Close command also clears the long-term cache.
For more information, review the following help section: Built-in Memory Cache.
Long-Term Cache (Storage)
The cache stores serialized data needed to retrieve objects in memory on demand. You can store report layouts and generated documents, and export data from these documents. You can use predefined storage, such as file or database storage, or use the ASP.NET Core distributed cache mechanism. If necessary, you can explicitly specify Time to Live parameters for each type of data stored in the long-term storage (reports/documents/exported documents).
Built-in Memory Cache
The generated documents are stored in the memory cache unless the developer explicitly specifies another cache type at application startup.
Cache memory is an unreliable storage that cannot store reporting documents for the application lifetime. When the process that creates cache memory terminates, the memory cache flushes, the document is deleted, and the Document Viewer can no longer display that document. The same scenario applies to the exported document and to the report document that the Report Designer generates in Preview.
Distributed Cache in ASP.NET Core Apps
The distributed caching mechanism implements a cache that runs as an external service that can be used by multiple application servers. Distributed caching can improve the performance and scalability of an application hosted on multiple servers or in the cloud.
The UseDistributedCache() method enables the reporting components to use the distributed caching mechanism that is implemented and configured in the ASP.NET Core application with the IDistributedCache interface. You can choose from various types of distributed cache implementations:
The implementation is simple and straightforward. If you decide to use the Distributed SQL Server Cache, configure the cache as described in the Distributed SQL Server Cache topic, and call the UseDistributedCache() method that enables the IDistributedCache in your reporting application.
Note
You must call the UseCachedReportSourceBuilder() method at the application startup if you use distributed cache.
Database Cache (XPO-based Storage)
If you run multiple instances of your application and want to avoid problems with losing cache data, you can use Database Cache Storage. To enable it, call the UseDbStorage method at the application startup:
| ASP.NET Core | ASP.NET Web Forms & MVC |
|---|---|
| UseDbStorage(String) | UseDbStorage(String) |
You should pass a connection string to an existing database into the method. You can create an empty database and use the IStorageDbInitializer interface to initialize tables and schema.
The Database Cache Storage is based on the XPO library - the DevExpress Object-Relational Mapping (ORM) tool that supports multiple relational database management systems. For more information on supported databases, review the following help topic: Database Systems Supported by XPO.
The Database Cache Storage supports all web platforms, including ASP.NET Web Forms and ASP.NET MVC.
File Cache
You can implement Cache Storage with the file system. Configure the Document Viewer to store server data on disk instead of in memory. This reduces the memory consumption at the cost of performance.
Call the following methods at the application startup:
Azure Caching
If you run reporting applications in the Microsoft Azure environment, review the following help sections for information on caching:
Cache Expiration
Our caching mechanism uses sliding expiration. It is explained in more detail below.
Every access to the cached entity (document or report) updates the last access time of the entity (document or report). It extends the lifetime of cache objects because the storage cleanup procedure adds the Time To Live value to the last access time to determine if the object expires.
The distributed cache uses a different algorithm. The built-in ASP.NET Core service cleans the cache automatically, and the DevExpress Reporting engine does not affect this process.
The reporting engine cannot guarantee that the distributed cache uses a sliding expiration. Instead, an absolute expiration is the default option. This means that the expiration time is written in a record. Our engine uses numerous records to store the document, and it cannot update all the records associated with the document, as this can dramatically reduce efficiency.
You can set the amount of time that the cached report layouts and documents are stored in the cache. The CacheCleanerSettings and StorageCleanerSettings services are available for this purpose.
When the user closes a browser tab, you can clear the cache to recover the memory immediately, before the clean timer clears it. Note that clearing the cache does not free the memory instantly. It simply makes it available for the .NET runtime garbage collector (GC), since no process now locks the document.
Note
For more information about mechanisms behind DevExpress Web reporting, including the client-sever communication protocol and server-side report storage, review the following help topic: Document Viewer Lifecycle.
Caching Guidance
This section includes some tips on cache management if you opt for database-based caching. Note that your application specifics may allow you to choose a file-based cache or an Azure Blob and Table Storage-based cache.
| Platform and Environment | Tip |
|---|---|
| ASP.NET Web Forms & MVC | Use Database Cache (XPO-based Storage). |
| If you already use Distributed Cache in ASP.NET Core Application | Use Distributed Cache in ASP.NET Core Apps. |
| If you have to use Redis in ASP.NET Core App | Use Distributed Cache in ASP.NET Core Apps. |
| ASP.NET Core App with a database that has no IDistributedCache implementation out-of-the-box | Use Database Cache (XPO-based Storage). |
| Any other web application | Use Database Cache (XPO-based Storage). |
Document Expiration Tips
The distributed cache in ASP.NET Core apps does not implement sliding expiration mode. The expiration mode for reports and documents in this scenario can be categorized as absolute expiration.
If it is critical to maintain document integrity and strictly adhere to sliding expiration mode, so that all document entities are available for the time specified with the Time To Live settings, use XPO-based storage.
Event Handlers in Cached Documents
When an object is in the cache, event handlers and user scripts are detached from the document instance, and you cannot rely on code execution in the event handlers.
Event handlers are dropped when a document is unloaded from memory after a certain period of time or when the application pool is recycled. In this case, the newly created document object loads the finalized pages from the repository, and no events related to page generation occur.
Web Document Viewer receives the XtraReport or CachedReportSourceWeb objects, but cannot attach event handlers for the document-related events such as XlSheetCreated. This occurs due to the fact that the document generation engine uses the XtraReport or CachedReportSourceWeb objects while the request for a document is handled by the DevExpress.XtraPrinting.Caching.CachedDocumentSource object.
You can call the following methods on the application startup to prevent the use of the DevExpress.XtraPrinting.Caching.CachedDocumentSource object, and attach event handlers to the XtraReport object:
| ASP.NET Core | ASP.NET Web Forms & MVC |
|---|---|
| DisableCachedDocumentSource() | DisableCachedDocumentSource() |
However, even in this case, when the document is unloaded after a timeout, the event handlers are disabled. The timeout intervals can be set with CacheCleanerSettings. To restore event handlers when the document is subsequently read from the long-term cache into memory, use the approach from the following example: