Binding to an Unmanaged RAS Server Using ReportDocument.FileName Property

Object Model

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

Location of Reports

In this scenario, you leverage your existing embedded report. You continue to reference the embedded report through its report wrapper class in your code, but you redirect the embedded report through the FileName property to an external (and much faster) copy located on the unmanaged RAS server (see Report Application Server (RAS).

Description

This is an optimized version of report binding scenario Binding to Unmanaged RAS Using ReportDocument.Load() Method.

Projects that were originally created with embedded reports and the ReportDocument object model in Crystal Reports for Visual Studio can now be easily ported to the unmanaged RAS server.

In this scenario you bind an embedded report (which is designed to work with Crystal Reports) at runtime to the unmanaged RAS server, and further optimize it by placing a copy of the report in a folder that is directly accessible to the RAS server. You achieve this by adding two lines of code to do the following:

• Assign the name of the RAS server to the ReportDocument.ReportAppServer property.
• Pass a RAS-accessible directory path string to the ReportDocument.FileName property.

You can also bind a non-embedded report to an unmanaged RAS server. You achieve this by deleting the call to the ReportDocument.Load(String filename) method described in Binding to a Non-embedded Report Loaded into the ReportDocument Class, and replacing it with the code described in the steps described above.

This scenario demonstrates that in Crystal Reports Developer you can bind embedded or non-embedded reports that use the ReportDocument object model directly to a RAS server, which uses the ReportClientDocument object model. How is that possible? In Crystal Reports 10 the ReportDocument object model was rewritten as a proxy layer that addresses the ReportClientDocument object model. For more information, see ReportClientDocument Object Model (RAS) in Architecture.

However, the default scenario in Binding to Unmanaged RAS Using ReportDocument.Load() Method has a performance limitation: loading the embedded report up to the RAS server each time is slow. To increase performance, copy the report to a file directory that is visible from the RAS server, and then pass the directory path string into the FileName property of the report instance.

The underlying ReportClientDocument object model can be accessed directly through the ReportDocument.ReportClientDocument property, allowing you to modify the report with the ReportClientDocument object model at runtime. For a code sample, see the Implementation section below.

Pros

• Maintains all original code that interacted with reports that use the ReportDocument object model, while still providing full access to the underlying ReportClientDocument object model through the ReportDocument.ReportClientDocument property.

  Note

  The ReportClientDocument object model allows you to programmatically create, modify and save changes to the report definition file. For further information, see ReportClientDocument Object Model (RAS) in Architecture.

• Significant performance gains, due to superior performance of the report engine in the Report Application Server (RAS). See Comparing Architectures Across Business Objects Reporting Solutions for more information.

• Additional performance gains from copying the report to a file directory that is visible from the RAS server.

Cons

• Code requires minor additions. Each time that a report is bound to the CrystalReportViewer control with ReportDocument, two lines of code must be added. For a code sample, see the section below.
• Making a copy of the embedded report to a file directory visible from the RAS server increases maintenance requirements. If a report must be modified or deleted those changes must be propagated into both the embedded report in the Visual Studio project and the report copy in the directory that is visible to the RAS server.
• Upgrading to unmanaged RAS greatly increases report performance, but not as much as by upgrading to managed RAS.

To load a copy of an embedded report from a file directory visible to the indicated unmanaged RAS server

• The unmanaged Report Application Server (RAS) 10 must be installed and verified to be working.
• Locate and write down the name of an unmanaged RAS server on the network. For the purposes of this example, the server name is "RAS01".

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.

RAS only works with a Web project.

1. Within the ConfigureCrystalReports() method (that you created in Project Setup), you have the following report binding code.

Between these two lines of code, you must add two new lines of code (see steps 2 and 4) that do two things before they bind the report to the CrystalReportViewer control:

  - Identify an unmanaged RAS server on the network.
  - Provide the file path that contains a copy of the report.

``` vb
Dim hierarchicalGroupingReport As Hierarchical_Grouping = New
Hierarchical_Grouping()
myCrystalReportViewer.ReportSource = hierarchicalGroupingReport
```

``` csharp
Hierarchical_Grouping hierarchicalGroupingReport = new
Hierarchical_Grouping();
crystalReportViewer.ReportSource = hierarchicalGroupingReport;
```

2. After the hierarchicalGroupingReport instantiation, enter the name of the RAS server into the ReportApplicationServer property of the hierarchicalGroupingReport variable.

   hierarchicalGroupingReport.ReportAppServer = "RAS01"
   

   hierarchicalGroupingReport.ReportAppServer = "RAS01";
   

3. Copy the report to the Report Application Server 10 directory on the C drive of the RAS server: C:\Program Files\Crystal Decisions\Report Application Server 10\Reports\

4. Next enter the file path to the report into your code, prefixed with the "RAS" protocol.

> [!NOTE]
> <P>This path is the default directory to store the RAS reports. The RAS server may reject other report paths with an "Access denied" error.</P>


The report binding code from [Project Setup](ms227453\(v=vs.90\).md) now follows this line of code.

``` vb
hierarchicalGroupingReport.FileName = "ras://C:\Program
Files\Crystal Decisions" _
               & "\Report Application Server 10\Reports" _
               & "\Hierarchical_Grouping.rpt"
```

``` csharp
hierarchicalGroupingReport.FileName = "ras://C:\\Program
Files\\Crystal Decisions"
               + "\\Report Application Server 10\\Reports"
               + "\\Hierarchical_Grouping.rpt";
```

5. To view the report, build and run your project.

The report is now loaded from the file path and served from the unmanaged Report Application Server (RAS).

To access the ReportClientDocument object model from within the ReportDocument object model, see the code section in Binding to Unmanaged RAS Using ReportDocument.Load() Method.

See Also

• Binding to an Unmanaged RAS Server Using ReportClientDocument.Open() Method

• Detailed Listing of All Scenarios