Should I Use Regular or Cached Reports?

When you plan an application to build with the Crystal Reports SDK, one of your most important considerations is whether to use regular or cached reports. Learning the SDK fundamentals that affect report caching helps you to choose the best structure for your Crystal Reports for Visual Studio project.

What are cached reports?

Cached reports are report objects that have been stored in the ASP.NET Cache object, to increase performance and scalability. Crystal Reports supplies a specific framework for placing ReportDocument instances in the Cache. That framework automatically caches any report that implements the ICachedReport interface.

What is the ASP.NET Cache object?

In both ASP and ASP.NET, report objects are placed in Session or Application on the Web server, for two reasons:

1. To persist the state of the report object across page reloads.
2. To improve scalability and performance by placing large or slow-to-load reports into server memory.

In ASP.NET, an augmented variation of the Application object called Cache was introduced. Like Application, Cache still persists single instances of a report object, to be shared by all users. However, Cache adds intelligence that looks for file-based, key-based or time-based dependencies. These dependencies can automatically expire and even refresh report objects within the Cache, to keep the contents of the Cache current.

How are report objects placed into the ASP.NET Cache object?

You can place report objects into the ASP.NET Cache object two ways:

• Assign the report object to Cache with the same syntax that assigns a report object to Session or Application (explicit assignment).
• Instantiate a version of the report that implements the ICachedReport interface. The report engine looks for any report object that implements this interface and automatically places that report object into the Cache (implicit assignment).

What is the ICachedReport interface?

The ICachedReport interface flags any report classes that enable ICachedReport to work with the Crystal Reports caching framework. This customized framework provides a layer over the ASP.NET Cache object, to meet specific needs of report caching.

The ICachedReport interface comes with method signatures that, when implemented in the report class, tells the framework how to cache that particular class.

What report caching features are provided when I embed a report into a Visual Studio project?

When you create or import a report into a Visual Studio project, that report is embedded into the project and two classes are automatically generated:

• A report wrapper class (with the same name as the report).

  This wrapper class represents the report in the project and inherits from ReportDocument. For more information, see Should I Use Embedded or Non-embedded Reports?.

• A cache management utility class (named Cached[ReportName] class).

  This cache management utility class handles the caching for that embedded report, by use of the ASP.NET Cache object and the caching framework that is built into the Crystal Reports SDK.

The following table shows the items that are generated when you add the Hierarchical Grouping report (found in the Sample Reports' Directory) to a Crystal Reports for Visual Studio project:

The report wrapper class and the cache management utility class have separate tasks:

• The report wrapper class inherits from ReportDocument and, therefore, has access to the complete ReportDocument object model. It is the core class that you program against to interact with the report.
• The cache management utility class manages and stores instances of the report wrapper class into the ASP.NET Cache object. It recognizes distinct instances of the report wrapper class and prevents those instances from overwriting each other in the Cache. For example, it recognizes differences that are created when parameters and logons are changed. To do that, it assigns a unique key for each unique instance of the report wrapper class.
• To identify itself to the caching functionality of the Crystal Reports .NET Framework, the cache management utility class implements the ICachedReport interface.

Both the report wrapper class and cache management utility class are generated in the same class file. To view both classes, right-click on the report class file in Solution Explorer, and choose View Code. When the file opens, you can find code for the report wrapper class at the top of the file, and the cache management utility class half way down.

When should I cache reports?

Keep only a low percentage of report objects in the ASP.NET Cache object. Most report objects have low shareability (that is, they are not used as shared resources with other objects). Therefore, they don't make economical use of Cache. If persistence is required, place report objects in the user's Session object instead.

Place the report object into ASP.NET Cache only when the report has high shareability. This is particularly important if the report object is very large or has a query that is so complex that it takes several minutes to retrieve the data.

See Also

• Binding to a Cached Embedded Report Class

• Cache Reports with "High Shareability"