Binding to a Non-embedded Report Loaded into a Cache Management Utility Class

Article
06/18/2008

Object Model

This report binding scenario uses ReportDocument (see Report Binding with ReportDocument Object Model).

Location of Reports

Reports are located on the file directory.

Description

This report binding scenario is similar to the following report binding scenario Binding to a Cached Embedded Report Class. The difference with this scenario is that reports are not embedded. For more information about non-embedded reports, see Should I Use Embedded or Non-embedded Reports?.

Crystal Reports for Visual Studio comes with two features to assist in the caching of reports with the ASP.NET Cache object:

A built-in report cache management framework, which recognizes when identical reports have unique parameters or logon credentials that require a unique key for each instance being cached.
An interface, ICachedReport that identifies report cache management utility classes to the report cache management framework.

In Binding to a Cached Embedded Report Class, you learned about the Cached[report name] class that is automatically created when a report is embedded in the project. However, you can manually create a cache management utility class that manages non-embedded reports. For a code sample, see the Implementation section below.

For detailed information on how to cache reports and use the cache management utility class, see Should I Use Regular or Cached Reports?.

Use of caching

Caching has a limited and specific use, which can overuse system resources if not managed carefully. To learn when caching should be used, see Cache Reports with "High Shareability".

Pros

Made for shareability: ideal for storing reports that have high shareability and few permutations in parameters or logon information.
Optimizes data access: if reports with high shareability are very large, or have a query that is so complex that it takes several minutes to retrieve, the data is accessed more quickly with the cache management utility class.

Cons

Server taxing: reports that remain in the ASP.NET Cache object can burden memory resources on the server.
Persistence issues: cache has certain dependencies that allow it to check for changes in a report instance and recache the report instance. However, if the database changes, the report instance in the Cache does not refresh to show that change.
Consumes resources: a report with parameters that are called frequently with different parameter strings (especially if one of those parameters is the user id) mean a new cached report each time. This consumes system resources. If the report is not highly shared, the report instance should instead be assigned to a Session object. See Session and Persistence of the ReportDocument Object Model.

To cache and then bind a non-embedded report to a CrystalReportViewer control

Note

This procedure works only with a project that has been created from Project Setup. Project Setup contains specific namespace references and code configuration that is required for this procedure, and you will be unable to complete the procedure without that configuration. Therefore, before you begin this procedure, you must first follow the steps in Project Setup.

Locate the World Sales Report.rpt file in the General Business subdirectory. For information about sample reports, see Sample Reports' Directory.
Copy to the clipboard the complete file directory path, including World Sales Report.rpt.
Within the ConfigureCrystalReports() method (that you created in Project Setup), declare a reportPath string variable and assign a string that contains the World Sales Report file directory path that you copied in the previous step.

``` vb
Dim reportPath As String = _
   "C:\Program Files\Microsoft Visual Studio 9.0\" _
   & "Crystal Reports\Samples\En\Reports\General Business\" _
   & "World Sales Report.rpt"
```

``` csharp
string reportPath = 
   "C:\\Program Files\\Microsoft Visual Studio 9.0\\"
   + "Crystal Reports\\Samples\\En\\Reports\\General Business\\"
   + "World Sales Report.rpt";
```

Declare and instantiate the NonEmbeddedReportCacher class, and then pass to it the reportFile string variable.

> [!NOTE]
> <P>To learn how to create the NonEmbeddedReportCacher class, see the step procedure following this step procedure.</P>


``` vb
Dim myNonEmbeddedReportCacher As NonEmbeddedReportCacher = _New NonEmbeddedReportCacher(reportFile)
```

``` csharp
NonEmbeddedReportCacher nonEmbeddedReportCacher = new NonEmbeddedReportCacher(reportFile);
```

Assign the report cache management utility class instance to the ReportSource property of the CrystalReportViewer control.

``` vb
myCrystalReportViewer.ReportSource = myNonEmbeddedReportCacher
```

``` csharp
crystalReportViewer.ReportSource = nonEmbeddedReportCacher;
```

To create the NonEmbeddedReportCacher cache management utility class

Create a new class in your project named NonEmbeddedReportCacher.

``` vb
Public Class NonEmbeddedReportCacher
    
End Class
```

``` csharp
using System;

namespace MyWebApplication
{
   public class NonEmbeddedReportCacher
   {
      public NonEmbeddedReportCacher()
      {
      }
   }
}
```

Append the ICachedReport interface to the class signature.

``` vb
Public Class NonEmbeddedReportCacher
    Implements ICachedReport
```

``` csharp
public class NonEmbeddedReportCacher : ICachedReport
```

Add three "Imports" [Visual Basic] or "using" [C#] statements to the top of the class.

``` vb
Imports CrystalDecisions.Shared
Imports CrystalDecisions.ReportSource
Imports CrystalDecisions.CrystalReports.Engine
```

``` csharp
using CrystalDecisions.Shared;
using CrystalDecisions.ReportSource;
using CrystalDecisions.CrystalReports.Engine;
```

Within the class, declare two class-level instances: a string instance named reportFileName and a ReportDocument instance named nonEmbeddedReportDocument.

``` vb
Private reportFileName As String
Private nonEmbeddedReportDocument As ReportDocument
```

``` csharp
private string reportFileName;
private ReportDocument nonEmbeddedReportDocument;
```

Set the constructor to accept a reportFileName string, and within the constructor, assign that string to the reportFileName class variable.
```
Public Sub New(ByVal reportFileName As String)
    Me.reportFileName = reportFileName
End Sub
```
```
public NonEmbeddedReportCacher(string reportFileName)
{
   this.reportFileName = reportFileName;
}
```
The remaining steps all implement properties or methods that are required by the interface:
- IsCacheable
- ShareDBLogonInfo
- CacheTimeOut
- CreateReport()
- GetCustomizedCacheKey(RequestContext request)
Create the IsCacheable property, which should return True.

``` vb
Public Overridable Property IsCacheable() As Boolean Implements ICachedReport.IsCacheable
    Get
        Return True
    End Get
    Set(ByVal Value As Boolean)
    End Set
End Property
```

``` csharp
public virtual Boolean IsCacheable
{
   get
   {
      return true;
   }
   set
   {
   }
}
```

Create the ShareDBLogonInfo property, which should return False.

``` vb
Public Overridable Property ShareDBLogonInfo() As Boolean Implements ICachedReport.ShareDBLogonInfo
    Get
        Return False
    End Get
    Set(ByVal Value As Boolean)
    End Set
End Property
```

``` csharp
public virtual Boolean ShareDBLogonInfo
{
   get
   {
      return false;
   }
   set
   {
   }
}
```

Create the CacheTimeOut property, which returns a constant from the CachedReportConstants class.

``` vb
Public Overridable Property CacheTimeOut() As TimeSpan Implements ICachedReport.CacheTimeOut
    Get
        Return CachedReportConstants.DEFAULT_TIMEOUT
    End Get
    Set(ByVal Value As TimeSpan)
    End Set
End Property
```

``` csharp
public virtual TimeSpan CacheTimeOut
{
   get
   {
      return CachedReportConstants.DEFAULT_TIMEOUT;
   }
   set
   {
   }
}
```

Create the CreateReport() method, which returns a non-embedded report loaded into the class level ReportDocument instance.

``` vb
Public Overridable Function CreateReport() As ReportDocument Implements ICachedReport.CreateReport
    If nonEmbeddedReportDocument Is Nothing Then
        nonEmbeddedReportDocument = New ReportDocument()
        nonEmbeddedReportDocument.Load(reportFileName)
    End If
    Return nonEmbeddedReportDocument
End Function
```

``` csharp
public virtual ReportDocument CreateReport()
{
   if (nonEmbeddedReportDocument == null)
   {
      nonEmbeddedReportDocument = new ReportDocument();
      nonEmbeddedReportDocument.Load(reportFileName);
   }
   return nonEmbeddedReportDocument;
}
```

Create the GetCustomizedCacheKey() method and return null.

> [!NOTE]
> <P>Returning null from this method cues the Crystal Reports .NET SDK to manage the cache lookup key itself. The alternative is to create and add your own customized cache key method here.</P>


``` vb
Public Overridable Function GetCustomizedCacheKey(ByVal request As RequestContext) As String Implements ICachedReport.GetCustomizedCacheKey
    Return Nothing
End Function
```

``` csharp
public virtual String GetCustomizedCacheKey(RequestContext request)
{
   return null;
}
```

To view the report, build and run your project.

Share via