Cache and Persistence of the ReportDocument Object Model

Cache is a server-based approach in ASP.NET for preserving state. Cache is functionally similar to the Application object found in both ASP and ASP.NET:

• Application allows you to persist any object across application scope.
• Objects placed into Application are available to all users. But Application, being general to the entire application, is not designed to preserve user-specific information.

Cache shares all of these features with Application, but it adds new levels of intelligence for managing transient data:

• An object added to the cache can be configured with file-based, key-based, or time-based dependencies. If the associated file or key changes, or if a certain period of time passes, the object is automatically removed from the cache, and an updated version is placed in the cache the next time the object is required.
• An object added to the cache that has no dependencies and is underused is automatically expired.
• When an object is removed from cache, an event is triggered. You can write code to run on that event and load an updated version of the object to the Cache.

If an alternative version of an object is added using the original key string, it overwrites the previous version. To prevent overwriting, concatenate the alternative definition to the key string to make each alternative version of the object unique.

The strength of Cache over Application is that, like Application, it stores information that is accessible to all users, but Cache can also update itself based on changes in its dependencies.

Limitations of this persistence approach

Developers who are new to Cache may be tempted to use it everywhere for persistence, replacing Session with Cache. However, Cache is not designed to replace the functionality of the Session object. Attempting to emulate Session uniqueness by concatenating user-specific data to the Cache key loads up the Cache with user objects that, unlike with Session, does not expire after a user's timeout period. As a result, Cache ends up placing a higher demand on Web server memory than the Session object did.

If you need to persist user-specific data, continue to use the Session object.

For alternate persistence approaches see:

• ViewState and Persistence of the CrystalReportViewer Object Model
• Session and Persistence of the ReportDocument Object Model

Persisting the ReportDocument object model with Cache

If the report has been encapsulated within the ReportDocument object model, the ReportDocument object model must be persisted using a server-based approach such as Session or Cache.

You can persist a report within the ReportDocument object model using Cache in one of two ways:

• Instantiate the report and then assign it to the Cache object, using the same syntax as for assigning a report to the Session object.

  This method only works for a report that has high shareability, where the ReportDocument instance occurs exactly once, using a single set of parameters and logon credentials. For a ReportDocument instance that may occur multiple times due to variation in its parameters and logon information, reassigning to the Cache object using the same key string overwrites the previous version of the ReportDocument instance. For information about caching with high shareability, see Cache Reports with "High Shareability".

• Instantiate a version of the report class that implements the ICachedReport interface.

  The Crystal Reports SDK includes a built-in caching framework for reports. Any report that implements the ICachedReport interface is automatically added to the cache with a unique key based on parameters and user logon credentials. This method works for any report that has high shareability, but may have a few versions due to minor variations in parameters and logon credentials. For reports with low shareability (that are user-specific), assign them to the Session object instead.

To persist an embedded report that implements ICachedReport

1. Add the report to the project.

This creates an embedded report class. It also creates a cached report class that loads and returns a cached instance of the embedded report class.

2. Instantiate the cached report class.

3. Assign the cached class instance to the CrystalReportViewer control.

> [!NOTE]
> <P>To work through a detailed example of this procedure, see <A href="ms227391(v=vs.90).md">Binding to a Cached Embedded Report Class</A>.</P>

To persist a non-embedded report through a utility class that implements ICachedReport

1. Create your own cache management utility class and set it to implement ICachedReport.

2. In this utility class, load the non-embedded report from a path string using the ReportDocument.Load() method.

3. Code the implementation method CreateReport() to return the ReportDocument instance of the non-embedded report.

4. Instantiate the report cache management utility class.

5. Assign that class instance to the CrystalReportViewer control.

   Note

   To work through a detailed example of this procedure, see Binding to a Non-embedded Report Loaded into a Cache Management Utility Class.

Limitations of persisting the ReportDocument object model with Cache

Cache is the best approach to use when persisting ReportDocument instances that have a high degree of shareability across users. If the report is user-specific, then Cache will waste server memory creating user-based instances at an application level that will last in server memory past user expiry. User-specific reports should be assigned to Session instead.

Contrasting Cache and Viewstate

Cache is primarily concerned with persisting the state of objects in the code-behind class. ViewState is primarily concerned with persisting the state of controls on the Web page. When a control on the Web page is bound to an object in the code-behind class and both need to be persisted across page reloads, Cache and ViewState share the roles of persistence.

In this case ViewState persists a CrystalReportViewer control, and Cache persists a ReportDocument object that is bound to the control.

See Also

• Persistence Limitations When Report Binding in the Page_Load Event Handler

• Which Persistence Approach Should I Use with Crystal Reports?