Choose the Correct Object Model for Your Project

To choose the correct object model for your project, you must understand best practices for how to work with the CrystalReportViewer control, and know how the CrystalReportViewer interacts with the other object models.

Best practices for working with the CrystalReportViewer control

An effective Web application makes clear separation between its presentation layer and its underlying business logic.

The design of the ASP.NET control naturally encourages that pattern. It encapsulates presentation information into the control, and then binds that control to an underlying object or object model that performs the business logic.

The CrystalReportViewer is a .NET control that adheres to this architecture. It functions as a display object on the Web or Windows Form (the presentation layer), and it can be bound to any of the following report object models:

• ReportDocument object model
• Object models available by upgrade:
  • ReportClientDocument object model (Report Application Server)
  • InfoObject object model (Crystal Reports Server or BusinessObjects Enterprise)

In a best practice scenario, the CrystalReportViewer control binds to one of the object models that performs the business logic, typically for report manipulation.

In that scenario, the CrystalReportViewer control limits its programmatic interaction to modify only display settings (for example, hiding or showing the viewer's toolbar or a button within that toolbar).

The CrystalReportViewer Object Model

The CrystalReportViewer control contains properties and methods that enable interaction with how it displays reports. It also has a small number of properties and methods for interacting with reports that are bound to the control. These properties and methods constitute a limited object model.

Some report binding scenarios rely on the CrystalReportViewer object model. In these scenarios, the CrystalReportViewer control is bound directly to a report (for example, you pass in a path string to the report in a file directory), without first encapsulating the report in an object model. In those scenarios, because the CrystalReportViewer control encapsulates the report directly, you must rely on the control's limited object model for programmatic interaction with the report.

But in most binding scenarios, using CrystalReportViewer as an object model is discouraged. Use instead the ReportDocument object model, for the following reasons:

• The CrystalReportViewer object model raises the risk of object model conflict. For more information, see Avoid Mixing the Object Models.
• The CrystalReportViewer object model offers limited interaction with reports; it contains only a small subset of the features available in the ReportDocument object model.
• The CrystalReportViewer object model blurs the separation of the presentation layer and the underlying business logic in your code.

The ReportDocument Object Model

ReportDocument is a more powerful and more extensive object model than CrystalReportViewer. It ships as part of the Crystal Reports for Visual Studio SDK and provides extensive ability to manipulate reports in the code.

For a description and diagrams of the ReportDocument object model, see ReportDocument Object Model under Architecture.

For tutorials that demonstrate how to code against the ReportDocument object model, see ReportDocument Object Model Tutorials.

Upgraded Object Models

If you upgrade your reporting solution to Crystal Reports Server or BusinessObjects Enterprise, you can take advantage of their object models, ReportClientDocument and InfoObject.

Which object model should you use?

If you do not intend to upgrade to Crystal Reports Server or BusinessObjects Enterprise, the ReportDocument object model is the recommended object model for your development work with the Crystal Reports SDK.