How Do I Use Report Viewer Controls?

Report viewer controls are .NET controls that can be added to a form in a Windows or Web application, to display reports on that form.

When you plan to build an application with the Crystal Reports SDK, one of your most important considerations is how to use the report viewer controls. Learning the SDK Fundamentals that affect these controls helps you to choose the best structure for your Crystal Reports for Visual Studio project.

What are .NET controls?

Microsoft .NET controls are special type of classes that are displayed in the Toolbox of Visual Studio. They are added to a Web or Windows Form as GUI objects, and they inherit from a common base control class. Typical .NET controls include: Button, DropDownList, CheckBox, TextBox, or DataGrid.

Microsoft .NET controls conform to the following best practice: separate the presentation layer from the business logic layer. They encapsulate display information within the control itself on the Web or Windows Form. In the code-behind class, the .NET control is instantiated as a class level instance. This instance variable gives access to the control's properties, methods, and events.

Microsoft .NET controls are functionally identical for both Windows and Web Forms. The .NET Framework views each Web page as a form that contains controls, like in a Windows application.

Why does Crystal Reports use .NET controls for report viewing?

One of the strengths of reporting tools is that they encapsulate the complex issues of report structure, design, and rendering within a simple GUI tool. Similarly, .NET controls encapsulate complex display and data population issues within a simple GUI object on a Web or Windows Form.

With the use of .NET controls, complex reporting and display are brought together. All of the complex report information, which used to be encapsulated only in the Crystal Reports stand-alone application, has now been encapsulated within a .NET control as a report viewer.

How many report viewer controls are there?

Crystal Reports for Visual Studio comes with two versions of the CrystalReportViewer control: one for Web applications, and one for Windows applications. The CrystalReportViewer control, located within the CrystalDecisions.Web namespace, is used by ASP.NET Web projects. The CrystalReportViewer control, located within the CrystalDecisions.Windows.Forms namespace, is used by Windows projects.

The CrystalReportPartsViewer control is used to display only parts of reports in a Web page. To learn how to use the report parts control, see Tutorial: Displaying Report Parts with the CrystalReportPartsViewer Control.

Displaying a report using the CrystalReportViewer control

The CrystalReportViewer control displays only one report at a time. Which report is displayed by the control is determined by which report you bind to your code. To tell the control which report to display, you bind the ReportSource property of the control to a particular report. At runtime, the control loads the report that is bound to the ReportSource property and displays it.

In its simplest form, the assignment looks like this:

crystalReportViewer1.ReportSource = "C:\WorldSalesReport.rpt"

crystalReportViewer1.ReportSource = "C:\\WorldSalesReport.rpt";

In this case, the report is bound to the control directly from its path in the file directory.

This demonstrates the most basic way to bind a report to the CrystalReportViewer control. For a complete list of binding scenarios, see Which Report Binding Scenario Should I Use?

Does the CrystalReportViewer control bind to data objects?

No. The CrystalReportViewer control binds to a report object, not a data object.

That is because the purpose of the CrystalReportViewer control is different than other .NET controls. Other .NET controls bind to data and format the raw data onto the page. Because the embedded Crystal Reports Designer does this automatically every time it creates a report (a report by definition encapsulates data retrieval and display), the CrystalReportViewer control is only concerned with the display of a report object.

The following table compares binding to a .NET data control versus binding to a CrystalReportViewer control.

To help you remember that a CrystalReportViewer control binds to a report object, rather than a data object, the source property of the report viewer control is named ReportSource (not DataSource).

Auto report binding

One other difference in binding a CrystalReportViewer control is that you do not need to manually call a bind method, like you would for most other .NET controls. Instead, the control automatically binds the report viewer to the report object. For more information on report binding, see Which Report Binding Scenario Should I Use?.

In this section:

• The CrystalReportViewer Control

• The CrystalReportPartsViewer Control