Binding to Unmanaged RAS Using ReportDocument.Load() Method

Object Model

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

Location of Reports

Reports are embedded into the project. At runtime the report is loaded over the network into an indicated Report Application Server (RAS).

Description

Visual Studio projects that use embedded reports and the ReportDocument object model in Crystal Reports for Visual Studio can now be easily ported to an unmanaged RAS server.

In this scenario, you load an embedded report over the network and into an indicated unmanaged Report Application Server (RAS). For a code sample, see the Implementation section below to add two lines of code that do the following:

• Assign the name of the RAS server to the ReportDocument.ReportAppServer property.
• Call the ReportDocument.Load() method.

Although embedded reports are written for the ReportDocument object model, in Crystal Reports Developer you can bind embedded reports directly to the RAS server, which uses the ReportClientDocument object model. This is possible because in Crystal Reports Developer, the ReportDocument object model has been rewritten as a proxy layer that addresses the ReportClientDocument object model. For more information, see ReportClientDocument Object Model (RAS).

The underlying ReportClientDocument object model can be accessed directly through the ReportDocument.ReportClientDocument property. This allows you to modify the report with the ReportClientDocument object model at runtime.

Pros

• Ability to maintain all original code that interacted with reports that use the ReportDocument object model, while at the same time 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.

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, see the Implementation section below.
• Upgrading to a RAS server greatly increases report performance.

To load an embedded report over the network to an indicated unmanaged RAS server

• The 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.

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 that identifies an unmanaged RAS server on the network and then load this embedded report onto that RAS server, before binding the report to the CrystalReportViewer control.

   hierarchicalGroupingReport = New Hierarchical_Grouping()
   myCrystalReportViewer.ReportSource = hierarchicalGroupingReport
   

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

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

   hierarchicalGroupingReport.ReportAppServer = "RAS01"
   

   hierarchicalGroupingReport.ReportAppServer = "RAS01";
   

3. Call the ReportDocument.Load().

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

``` vb
hierarchicalGroupingReport.Load("rassdk://C:\report.rpt",
"RAS01")
```

``` csharp
hierarchicalGroupingReport.Load(@"rassdk://C:\report.rpt",
"RAS01");
```

4. Compile and debug your project.

The report is now being loaded from the project over the network to the unmanaged Report Application Server (RAS).

To access the ReportClientDocument object model from within the ReportDocument object model

1. Exit out of debug mode from the previous procedure.

2. Add the following assemblies as references to your project.

   • CrystalDecisions.ReportAppServer.ClientDoc
   • CrystalDecisions.ReportAppServer.Controllers
   • CrystalDecisions.ReportAppServer.DataDefModel

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

   Imports CrystalDecisions.ReportAppServer.ClientDoc
   Imports CrystalDecisions.ReportAppServer.Controllers
   Imports CrystalDecisions.ReportAppServer.DataDefModel
   

   using CrystalDecisions.ReportAppServer.ClientDoc;
   using CrystalDecisions.ReportAppServer.DataDefModel;
   using CrystalDecisions.ReportAppServer.Controllers;
   

4. Within the ConfigureCrystalReports() method, between the line of code that calls the Load() method and the line of code that binds the report to the control, enter a call to a new private helper method named ModifyReport.

   ModifyReport()
   

   ModifyReport();
   

5. Create the ModifyReport() private helper method as per the sample below. The purpose of this code is to demonstrate access to the ReportClientDocument object model within the ReportDocument object model. This code removes the first available field from the fields displayed on the report.

   Note

   If the Database table field is not found in the reports result field collection, the application throws an exception.

   Private Sub ModifyReport()
       Dim myReportClientDocument As ISCDReportClientDocument = _
           hierarchicalGroupingReport.ReportClientDocument
       Dim myTables As Tables = _
           myReportClientDocument.DatabaseController.Database.Tables
       Dim myTable As CrystalDecisions.ReportAppServer.DataDefModel.Table
       myTable = CType(myTables(0), CrystalDecisions.ReportAppServer.DataDefModel.Table)
       Dim myFields As Fields = myTable.DataFields
   
       Dim myField As ISCRField
       For Each myField In myFields
           Dim myResultFieldController As ResultFieldController = _
               myReportClientDocument.DataDefController.ResultFieldController
           Try
               myResultFieldController.Remove(myField)
               Exit For
           Catch
           End Try
       Next
   End Sub
   

   private void ModifyReport()
   {
      ISCDReportClientDocument reportClientDocument = hierarchicalGroupingReport.ReportClientDocument;
      Tables tables = reportClientDocument.DatabaseController.Database.Tables;
      CrystalDecisions.ReportAppServer.DataDefModel.Table table =
         (CrystalDecisions.ReportAppServer.DataDefModel.Table)tables[0];
      Fields fields = table.DataFields;
   
      for (int i = 0; i < fields.Count; i++)
      {
         ISCRField field = fields[i];
         ResultFieldController resultFieldController = 
            reportClientDocument.DataDefController.ResultFieldController;
         try
         {
            resultFieldController.Remove(field);
            break;
         }
         catch
         {
         }
      }
   }
   

   Note

   Everything that was programmed against to the underlying ReportClientDocument object model logically occurs in the enclosing ReportDocument instance, which is bound to the CrystalReportViewer control.In this code sample, the field removal demonstrated here occurs only at runtime. It is not saved back to the report definition file.

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

See Also

• Binding to an Unmanaged RAS Server Using ReportDocument.FileName Property

• Detailed Listing of All Scenarios