What best practices should I use when working with the CrystalReportViewer control?

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

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:

• ReportClientDocument Object Model
• ReportDocument object model
• InfoObject object model (BOE)

In this scenario, where the report is encapsulated by one of the object models (such as the ReportClientDocument), 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).

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.

However, in most binding scenarios, using the CrystalReportViewer as an object model is discouraged. Use instead the ReportClientDocument (RAS) object model, for the following reasons:

• The CrystalReportViewer object model raises the risk of object model conflict.
• The CrystalReportViewer object model offers limited interaction with reports; it contains only a small subset of the features available in the ReportClientDocument (RAS) object model.
• The CrystalReportViewer object model blurs the separation of the presentation layer and the underlying business logic in your code.

Avoid mixing the object models

Use of the CrystalReportViewer control in its role as a limited object model works properly, provided you bind the control directly to the report with a simple path string.

But if you encapsulate the report into the ReportClientDocument object model and bind the control to that object model, stop using the CrystalReportViewer object model right away. The limited model that is provided by the CrystalReportViewer control becomes redundant to the more powerful object model that it is bound to. Also, settings that are applied to the CrystalReportViewer object model are visible to the other object model, which could result in unexpected behaviors and exceptions.

For example, you may want to use the ReportClientDocument object model to export or print a monthly report from the server. If you have set a month parameter on this report with the CrystalReportViewer object model, you may experience problems. The ReportClientDocument object model cannot see parameter settings applied in the CrystalReportViewer object model. It tries to export or print the report without knowledge of that month parameter setting, and then displays the wrong month or even throws an exception.

When you bind the control to one of the underlying object models, the best answer is to limit use of the CrystalReportViewer control to report display settings only.

© 2021 SAP AG. All rights reserved.

http://www.sap.com/sapbusinessobjects/

Support services

http://service.sap.com/bosap-support/

Created with the Personal Edition of HelpNDoc: Easy EPub and documentation editor