Professional.Crystal.Reports.for.Visual.Studio..NET [Electronic resources] نسخه متنی

Using the Crystal Report Viewer for Web Forms

For report files that live externally to your application (for instance, as a standalone report file, created with either this or a previous version of Crystal Reports) there is not much to creating a simple preview form for your report. We are going to walk through that process in the following section.

Earlier we created a new project called web_viewer_basic and within that project there should be a default Web Form (WebForm1.aspx) that was created when you created the project. To start, we need to drag or draw the Crystal Report Viewer onto our Web Form:

From that point, we need to set the ReportSource property to let the viewer know where to get the report from. To access this property, locate the Properties window for the Crystal Report Viewer and open the (DataBindings) property, by clicking on the ellipse at the side, to show the dialog that appears below:

Click on the ReportSource property and click on the radio button to select Custom Binding Expression. In this example, we are going to assume that you have unzipped the download files for this chapter to your hard drive in a folder called CrystalReports\Chapter04 - included in these files is a Sales Graph report (sales_graph.rpt) that we will be using through this walkthrough.

Once you have entered the name and path for your report, click OK to accept your changes and return to the form we were working with. The report will now be displayed in a "Preview" mode in the form designer, as shown here:

If we were working with a Windows form, this would be all that is required to actually preview a report. Since Web Forms work a little differently, there is an extra step involved before we can run our application and preview our report.

Double-click anywhere on your form to open the code view for the form and locate the section of code marked Web Form Designer generated code. Expand this section to find the Page_Init function and add a line of code immediately after the InitializeComponent () call to bind your report to the viewer when the page is initialized:

Private Sub Page_Init(ByVal sender As System.Object, ByVal e As
System.EventArgs) Handles MyBase.Init
'CODEGEN: This method call is required by the Web Form Designer
'Do not modify it using the code editor.
InitializeComponent()
CrystalReportviewer1.DataBind()
End Sub

Whenever you run your application and preview the form, your report will be displayed in the Crystal Report Viewer, as shown next:

The viewer interacts with the Crystal Reports print engine, runs the report, and displays the results. From your report preview, you can drill-down into the details or search for a value, without having to do any additional coding.

If you only have one or two reports that you want to integrate into a view-only application and you don't need to customize any features at run time, this may be all you need. But for applications that required a more sophisticated integration with Crystal Reports.NET, you probably need to look a bit further.

In the following sections, we are going to walk through adding a report to your application, binding the report to the Crystal Report Viewer, and customizing the viewer.

Adding a Report to Your Application

To add a new report to your application, you have two choices - you can either use an existing report that you have created (using this or a previous version of Crystal Reports), or you can use the Report Designer integrated within Visual Studio .NET to create a report from scratch. For our purposes, we are going to add an existing report to our next sample application (for more information on creating reports from scratch, check out Chapter 2: Getting Started with Crystal Reports.)

In this example, we will add the Sales Graph report to web_viewer_basic2. Whereas the approach in our first example favors publication of a report that will always be found by the same path, but is subject to regular updates, this option favors a report that is not likely to change and so can be incorporated into the application, allowing us to alter its features, or even build it from the ground up. This is also relevant to whether we are using strongly typed or untyped reports, as we discussed in the last chapter.

Once again, you have the choice of building the project or using the code provided - but remember that if you use the code provided, you must create a virtual directory for it in IIS on your machine.

To add our Sales Graph report to this new project, select Project | Add Existing Item, which will open the dialog shown below. Change the drop-down list to show All files and specify *.rpt for the file name to filter the list to show only the available reports.

Once you have selected the Sales_Graph.rpt report, click Open and this report will be added to your project in the Solution Explorer.

Once you have added your report to your project, it will appear in the Solutions Explorer and you can view the design of the report using the Report Designer and access its properties through its Properties page.

Adding the Report Viewer to a Web Form

You can add the Crystal Report Viewer from the Web Forms Toolbox and drag or draw the viewer onto your form - unlike the Crystal Report Viewer for Windows forms, the Web Forms Viewer does not provide a view of how the viewer will appear on your page until you actually bind a report to it, at design or run time.

In fact, we'll do this now for web_viewer_basic2. Just drag a CryStalReportViewer over from the Toolbox and place it on the Web Form. Don't bother setting a report source for it yet, as we are about to look at different methods for binding the report to the viewer.

The Crystal Report Viewer can be used on existing forms to display a report side by side with other controls, or you could add the report to a new form to have a separate window for previewing reports.

Binding a Report to the Report Viewer

With the Report Viewer added to your form, we now need to bind a report to the viewer itself. As we saw in Chapter 3 for Windows-based applications, there are five different ways to bind a report to the Crystal Report Viewer:

By report name

By report object

By binding to an untyped report

By binding to strongly-typed report

By binding to strongly-typed cached report

Binding by Report Name

To bind a report using the report name, as we did in our first example, all you need to do is set the ReportSource property, either through the Data Bindings properties for the report or through the form's code, as shown here:

CrystalReportViewer1.ReportSource =
"C:\CrystalReports\Chapter04\web_viewer_basic\sales_graph.rpt"

Then in the Page_Init event of your form, you would need to add a single line of code to call the DataBind method immediately after the InitializeComponent() call, as shown here:

CrystalReportViewer1.DataBind()

If you prefer to set the initial report source using the property pages, you will need to open the Properties page for the report viewer, and then select the (DataBindings) property as we did in the first example.

But since we have added the report to our application, we could also bind the report by creating a report object, loading the report into the object, and binding the object to the Crystal Report Viewer.

Binding by Report Object

Binding by a report object works slightly differently depending on if you have added the report to your project, or if you are referencing it externally. For a report that resides external to your application, you need to first specify an import of the CrystalDecisions.CrystalReports.Engine, which will allow you to create the object.

If this is not already present, we shall add it. In the Solution Explorer, right-click on your project title and select Properties from the right-click menu to open the dialog shown below.

Under the Common Properties folder, use the Imports option to add the CrystalDecisions.CrystalReports.Engine namespace to your project and click OK to return to your form.

With this namespace imported, we now need to create the report object as a ReportDocument in the form's Declarations section, as shown:

Dim myReport as New ReportDocument()

With our object now ready to be used, we can now load the external report file by placing the following code under the Page_Init event:

...
InitializeComponent()
myReport.Load("C:\CrystalReports\Chapter04\sales_graph.rpt")
CrystalReportViewer1.ReportSource = myReport

If the report you are using has actually been added to your project (as ours was above), a class was automatically generated for the report, so we could use the class instead to bind the report to the viewer (while the import and Public declaration remain the same):

...
InitializeComponent()
myReport = New sales_graph()
CrystalReportViewer1.ReportSource = myReport

or, if you wanted to eliminate the myReport variable:

CrystalReportViewer1.ReportSource = New sales_graph()

Which method you choose will depend on where the report is physically located and how you wish to access it.

Binding to an Untyped Report

When working with Crystal Reports.NET, you can add individual report files to your project and use and reference them to view reports from your application. Taking this a step further, you could also use these reports as components, which is where we start looking at typing.

When integrating reports into an application, we can either use strongly-typed reports or untyped reports. If you have been working with Visual Studio .NET for any length of time, you have probably heard of strongly-typed objects. A strongly-typed object is predefined with a number of attributes that are specific to that object, giving programmers more structure and a rigorous set of rules to follow, whereas an untyped report does not have this structure or rules applied to it, making it more difficult to work with.

Within the frame of reference of Crystal Reports.NET, a strongly-typed report can be any report that has been added to your project. When you add a report to a project, you will notice that in addition to the report, another file (with a .vb extension) is also added, as shown overleaf:

Note

This file is hidden until you select Show All Files from the Solution Explorer.

This additional file is the report source file and contains a report class specific to each report, called ReportDocument, which is derived from the ReportClass class and is created automatically for you.

An example of an untyped report would be a report that is stored externally to your project. For instance, you could view a report by setting an external reference (as in our first example, where we set the ReportSource property in the (DataBindings) to "C:\CrystalReports\Chapter04\web_viewer_basic\sales_graph.rpt".

We'll just have a brief look at how we do this. Create a virtual directory called web_viewer_untyped pointing at C: \CrystalReports\Chapter04\web_viewer_untyped (if this is where you have downloaded the source code to) or alternatively build it from scratch.

To add a report component to your application, switch to the Layout view of your form and look in the toolbox under Components. In this section, you should see a component labeled ReportDocument. Drag this component onto your form, which will open the dialog shown below:

It is using this dialog that we set whether our ReportDocument component is typed or untyped. If you select Untyped ReportDocument, then we are not really accomplishing much new here. Drag a new CrystalReportViewer onto the Web Form, and then load a report into ReportDocument1 and bind the component to the viewer.

...
InitializeComponent()
Dim ReportDocument1 As New ReportDocument()
ReportDocument1.Load("C:\CrystalReports\Chapter04\sales_graph.rpt")
CrystalReportViewer1.ReportSource = ReportDocument1

Binding to a Strongly-Typed Report

Finally, you can choose to add a strongly-typed report component, which probably has the simplest binding method of all. First of all, add the report that you wish to bind to your project. In our case, this will be sales_graph.rpt. To create a strongly-typed ReportDocument component, drag the ReportDocument component onto your Web Form. (The code for this Web Form is available in the code download for the chapter as web_viewer_stronglytyped.)

You will then see the same dialog before, with a drop-down list of all of the available reports that are in your project. Select an existing report to create a strongly-typed ReportDocument. Now, insert the CrystalDecisions.CrystalReports.Engine namespace into the project using the Properties page as we did previously, drag on a CrystalReportViewer, and we're set. From that point, we just need to set the ReportSource property in the Page_Init event once more:

CrystalReportViewer1.ReportSource = sales_graph1

(Where sales_graph1 is the name automatically assigned to the ReportDocument component when you added it to your form.)

Binding to a Strongly-Typed Cached Report

Another option for strongly-typed reports is the ability to use ASP.NET caching with your report. When you added your report to your application, you may have noticed that there was a checkbox for Generate cached strongly-typed report. Report caching is based on the underlying ASP.NET caching model and provides an easy way to improve your application's performance.

When a report is cached, the subsequent Web Form that is used to view the report will load faster when accessed by different users. To add a report to your Web Form as a cached report, select this option as you add a strongly-typed report to your application from the dialog shown overleaf:

You will see that your report file will be inserted as cached_sales_graph1 and an additional object will be inserted into the Web Form's source file.

You could then bind to this particular cached report just as you would to any other strongly-typed report, but with a different name:

CrystalReportViewer1.ReportSource = cached_sales_graph1

When multiple users visit the same report, they will actually be looking at a cached copy and not hitting the database in real time. (To ensure this is true, the viewer by default does not have a refresh button showing.)

So regardless of which method you choose to bind your report to the viewer, the result is the same. For ease of use and functionality provided, the easiest method is going to be to stick with strongly-typed reports, because in the long run the structure and coding standards will mean you can create reporting applications quickly, in a consistent manner.

After binding, you can run your application and when the form is loaded the Crystal Report Viewer will run the report you have set in the ReportSource property and display a preview of it. But before we can move on to customizing the viewer, we need to look at working with secured databases.

Note

Before we finish up with viewer basics and binding, keep in mind that reports that were created from a secure data source may require a user name and password. Turn back to Chapter 3 to the section titled "Passing Database Logon Info" to review the use of the LogonInfo collection - it behaves in the same way for either the web or Windows form viewers and the same goes for the record selection formula - it can be returned or set using the SelectionFormula property, and its use is also described in Chapter 3.