CodeProject; Tools & Code: Crystal Reports Helper Class May Make Crystal Easier To Use

Crystal Reports helper class
Click title for source at CodeProject.com…

By Jan Schreuder.



Introduction
Integrating Crystal Reports in a .Net application can be difficult. There are a number of things you need to know to succesfully run reports from inside your application. The helper class described in this article offers a number of methods that can be useful when you want to integrate Crystal Reports in your .Net application. Integrating Crystal Reports will be a lot simpler when you use this helper class.

The helper class contains methods that will help you to:

• Assign database conenctions or DataSet objects to a report
• Print a report from code in a WinForms application
• Export a report from code to disk in a WinForms application
• Export a report to an ASP.Net form.
• Download the report to an internet client from inside an ASP.Net application.
• Tweak the way the Crystal Reports viewer presents itself in a Windows Forms application.

The Demo solution which you can download demonstrates some of the features of this class. You will need Sql Server 2000 with the Pubs and NorthWind database to use it.

Background
I started building this helper class a few years back, when I had to integrate Crystal Reports in an Windows GUI application. I had to solve the following problems:

• Assign DataSet objects to a report.
• Assign a database connection to a report.
• Export the report to an Adobe PDF file.
• Integrate the Crystal Reports viewer in the application.

The helper class was originally designed for use with .Net 1.1 applications. Visual Studio 2003 came with a trimmed down version of Crystal Reports 9, which was called Crystal for .Net. At this moment, Visual Studio 2005 comes with an updated version which is based on Crystal Reports 10.

Common actions handled by the CrystalHelper class

Assign a connection to a report
One of the problems most developers face when integrating Crystal Reports is getting it to work on another system. This problem is caused by the fact that Crystal requires a valid database connection. When you develop a report, this is usually a connection to your development database. But when you deploy a report, you will need to assign the correct database connection to each table in your report. The following code shows how this can be done:



If you have one or more subreports, then it get’s even more complex. You will need to perform the above action for each of the subreports. To do this you will need to check all sections in the report and then assign the connection info again to all tables in each subreport. For example:



The two code sections above are handled by the “Open()” method in the CrystalHelper class.

Assign a DataSet to a report
A similar problem occurs when you want to assign a DataSet to a report. The dataset must be assigned to the report, but also to all subreports. The code to do this will look like this:



This code is also part of the Open() method in this CrystalHelper class.

Using the code to integrate a report

Print report
The first code sample shows how you can print a report when the report is an embedded resource and the data is stored in a DataSet:

As you can see in this example is that the code to handle the report is very simple and straight forward. The “Open()”method will ensure the DataSet is assigned to all sections.

When you use embedded queries in your report, then you will need to assign the database connection instead of assigning a DataSet as in the example above. The code would then look like this:




Again you see that using Crystal Reports with this helper class makes integrating reports very simple. In the example above, I used a fully qualified connection with a valid user Id and password. The version of Crystal Reports that is included with Visual Studio 2005 also supports integrated security. For that purpose, the CrystalHelper class also features a property “IntegratedSecurity”.

This property defaults to “false” but setting it to “true” will allow you to use integrated security as show in this example:


If the report is included in your solution as a content file, rather than an embedded resource, then you can replace this line:


with this line:


Export a report
Exporting a report can be done to the following Export formats:

• Word (*.doc)
• Excel (*.xls)
• Rich text (*.rtf)
• Portable Doc Format (*.pdf)

The helper class features four methods to perform an export. The first two simply export the file to a specified location. These two methods are usefull for WinForms applications, or when you need to export files to a server in an ASP.Net environment. The first of these has a file name as an argument. The type of export is determined by checking the extension given to the file:



The second also allows you to specify the Export format as an argument:



When you use these methods in an ASP.Net application, you will probably want the files to be exported to the client. For this purpose, the helper class implements two methods which require you to pass the HttpResponse object. The first of these methods will simply write the exported file to the response:



This will result in the report being shown inside the client internet browser, provided the application that supports the export format is installed. The second method allows you to specify if the export has to be sent as an attachment in which case you can specify the file name for the export. The user will be shown a dialog in which he/she can specify a download location.



Showing the report a the Crystal Reports viewer control
The last option to show a report is using the Crystal Reports viewer control. Assuming you have the control on your form (Windows or ASP.Net), you can do the following:



Tweaking the Crystal Reports viewer control

Change the name of a tab
When the report is shown, the viewer will always show a tab. This is a very useful feature when you have subreports, or drill-down features in your report. The only thing is that the name of the tab is always “Main Report” or the name of your subreport. Changing the name of a tab is easily done by making the following call:

The first argument is the viewer control. The second is always the current name of the tab. The last argument is the new name for the tab. You need to be aware though, that changing the names of the tabs is a bit tricky. First of all, you are only sure that the first tab (MainReport) is always there. The other tabs are only shown when a user clicks to enter a subreport or drill-down section. You will need to respond to the events thrown by the viewer to make sure the names of the tabs are adjusted when a new tab is made visible.

Hide the tabs

If you want to hide the tabs, then you can simply use this call:

This is of course reversable by calling the same method with true as the second argument.


Hide the statusbar
The report viewer also shows a status bar. This can be hidden by using the following call:

This is of course reversable by calling the same method with true as the second argument.

Valuable resources
A lot of the information I needed to build this helper class was found on the Internet. I found the following resources to be very useful when you need to do something with Crystal Reports:

• Crystal knowledge base at Business Objects
• Forums section on BusinessObjects.com
• Crystal Reports forum at Microsoft Forums

Compatibility issues
I realise that by providing only the .Net 2.0 sources that readers may wonder if the helper class can accomodate older versions. The answer is yes but you will need to remove the code that is not supported in .Net 1.1. This will also eliminate some of the features supported by this class.

History

• June 12, 2007 – Implemented export to HttpResponse. New documentation is generated using SandCastle and the Sandcastle Help File Builder.
• March 8, 2007 – Fixed bug reported by Matthew Noonan.
• December 6, 2006 – Added .Net 1.1 version of the class and demo application.
• August 8, 2006 – Included more samples and background.
• August 3, 2006 – Included resources.
• August 2, 2006 – First time on Code Project.