Document Viewer Lifecycle

• Sep 18, 2023
• 5 minutes to read

This document provides reference information about the DevExpress HTML5 Document Viewer’s lifecycle. It explains the mechanisms behind DevExpress Web reporting, including the client-sever communication protocol and server-side report storage.

The Document Viewer’s Client-Server Communication Protocol

The HTML5 Document Viewer stores reports and performs all operations on the server. The client sends commands to initiate these operations and receives data to display. To send a command or request data, the Document Viewer sends Fetch requests to the DXXRDV.axd handler (ASP.NET WebForms and ASP.NET MVC) or the WebDocumentViewerController (ASP.NET Core) on the server. Depending on the user’s actions and the current phase of the viewed report’s lifecycle, these requests can specify the following commands in their payload:

Command	Description
openReport	Instructs the server to load a report’s layout
startBuild	Triggers the document creation process (the report’s CreateDocument method is called). The report creation process is carried out in a background thread. This command is sent when a parameter is submitted, a drill-down detail region is opened/closed, and sorting is applied.
getBuildStatus	Checks on the document creation progress. The client sends this request multiple times before the document is created. The client updates the progress indicators based on the server response.
getDocumentData	Loads the created document’s metadata after the document is created.
getPage	A GET request that loads a document page’s layout data (bricks and image). This request can be executed after the getBuildStatus request is executed for the first time to load data for a page that was created. This request is also executed after the zoom factor is changed to load a suitably sized image.
close	A request to close a document or a report and generated document when the Close method is called on the client.

A browser’s developer tools provides information on how and when the viewer sends these requests to communicate with its server side.

How Reports are Stored

Report Definitions and Report Documents

On the server, every report is stored in the following fundamental states:

• A report layout definition - A report layout without data.
• A report document - A document built from a layout definition. A report document can be rebuilt multiple times.

Refer to the Store Report Layouts and Documents documentation section for more information.

Caching Mechanisms

Report layout definitions and generated documents are cached on the server side. The Document Viewer uses two caching levels:

• A short-time Cache - This is the fastest cache that ensures that frequent operation are always fast, its Time to Live resets with every request. The Cache stores report layouts and documents in their object representation.
• A Storage - A long-time cache that can be configured to serialize the cached data and temporarily unload it to the file system or Azure Cloud Storage.

Report Lifecycle

A report’s lifecycle begins when the server calls the OpenReport method. This method call produces an XtraReport instance and saves it to the In-Memory Cache and Storage.

Note

In the demonstrated lifecycle, the Storage is configured to use the file system or Azure Cloud Storage. In in-memory mode, the Storage and Cache are cleared simultaneously.

The Time to Live for cached report layouts and documents can differ depending on how the CacheCleanerSettings and StorageCleanerSettings are configured.

The steps below illustrate the full lifecycle:

1. [Server] The OpenReport method is called to load a report’s layout definition (REPX), the loaded layout is put into both the In-Memory Cache and Storage.
2. [Server] Report document creation process is started. While this process is running, the generated document’s data (PRNX) is temporary stored in the Cache.
3. [Client] The client-side UI is rendered on the web page.
4. [Client] The viewer sends a getBuildStatus HTTP request.
5. [Server] The server responds that the document is still being generated, but the first few pages are ready.
6. [Client] The viewer sends the getPage request to get the created page’s data.
7. [Server] The document creation process is complete. The generated report’s document (PRNX) is saved to storage.
8. [Client] A getBuildStatus request is sent. The server responds that the document is ready and all its pages are available.
9. [Client] A getDocumentData request is sent.
10. [Server - 1 minute later] The client did not request the report document’s data during this time, so the server removes this data from the In-Memory Cache.
11. [Client] A getPage request is sent when a user scrolls the document to a new page.
12. [Server] The server loads it to the In-Memory Cache again when the client requests the document data.
13. [Server - 1 minute later] The report’s document is cleared from the In-Memory Cache.
14. [Server - 2 hour later] The report’s document is cleared from Storage. The report’s layout data is cleared from In-Memory Cache and Storage.

Note that if the report was opened from the report URL, the Document Viewer can request the report resolution service and restore the report layout even if the report layout is automatically deleted from the repository after the timeout period expires.

Note

For more information on report resolution services, review the following help topic: Use Report Name Resolution Services.

The default timeout period is 2 hours. It is the default value of the reportTimeToLive parameter for cached report layouts in the repository. Use the StorageCleanerSettings.CreateDefault() method to specify the reportTimeToLive parameter value to set the expiration time interval for cached report layouts.

Note

For more information on Document Viewer cache, review the following help topic: Web Document Viewer Cache Management.