Understanding the Crystal Reports Object Model
page 2 of 3
by Jeff McWherter
Average Rating: This article has not yet been rated.
Views (Total / Last 10 Days): 21017/ 44

Getting Data to Your Reports

The first methods that developers are most likely to run into within the Crystal Reports object model are the methods that actually get the data to the ReportDocument.

Data Source

The DataSource property of the ReportDocument object has four overloads allowing a developer to pass in a Dataset, DataReader, Datatable or an IEnumerable containing the set of data that will be reported on.

In recent years with Object-Relational Mappers (ORM's) becoming more popular, the ability to pass an IEnumerable to the ReportDocument has become a very important option when generating reports.


The SetParameterValue is another common method that is used when getting data to Crystal Reports. The SetParameterValue sets the value of a parameter that is used within the report. I have learned through the creation of many Crystal Reports that it is best to have the data filtered before it gets to Crystal Reports. The DataSource that is passed to the report should only contain the data that should be shown in the report. Databases, such as SQL server, are much faster at filtering data then the Crystal Reports API.

Write XML Schema

This tip is not contained within the Crystal Reports Object model, but it is a tip that is relevant to getting data to the report. There is a handy method found on a DataSet object that will create an XML schema for the data contained in the DataSet. This schema contains information about the fields and the tables contained in the DataSet.

Listing 1: Using the WriteXmlSchema method

DataSet reportDataSet = FunctionThatGetsReportDataSet;

Listing 2: Example XML Schema

<?xml version="1.0" standalone="yes"?>
<xs:schema id="ArrayOfEmployee" xmlns="" 
  <xs:element name="ArrayOfEmployee" msdata:IsDataSet="true" 
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="Employee">
              <xs:element name="FirstName" type="xs:string" minOccurs="0" />
              <xs:element name="LastName" type="xs:string" minOccurs="0" />
              <xs:element name="Address" type="xs:string" minOccurs="0" />
              <xs:element name="City" type="xs:string" minOccurs="0" />
              <xs:element name="State" type="xs:string" minOccurs="0" />
              <xs:element name="PostalCode" type="xs:string" minOccurs="0" />
              <xs:element name="Role" type="xs:string" minOccurs="0" />

This XML schema can then be used within the Crystal Reports IDE as a data connection to render the fields to allow you to create a report.

Figure 1: Selecting the ADO.NET XML type as a connection type

Figure 2: ADO.NET XML connection with the XML schema selected

Figure 3: Field Explorer with the XML schema imported

Receiving Summary Information

Many reports have a variety of summary information saved within the report. In most cases the summary information is set during design time using the Crystal Reports IDE or the tools provided within Visual Studio. There may be times when you need to set the summary information at run time and the Crystal API provides a set of properties to accomplish this.

Listing 3: Report summary options

using (ReportDocument report = new ReportDocument())
    report.SummaryInfo.ReportAuthor = "Jeff McWherter";
    report.SummaryInfo.ReportComments = 
        "Lists all customers for each year";
    report.SummaryInfo.ReportSubject = "Customers by Year";
    report.SummaryInfo.ReportTitle = "Customers by Year";
    report.SummaryInfo.KeywordsInReport = "Customers Year earnings";


The default Crystal Report Viewer provides functionality to export a Crystal Report. Often times the functionality provided needs to be extended, or in some cases limited; in this situation you would most likely create your own export page using code similar to what is shown below.

The example below will get a set of data from the database, pass it to the report object, and then create an export of the report. Notice that the report is not rendered on the screen.

Listing 4: Exporting a Report programmatically

using (ReportDocument reportToExport = new ReportDocument())
    reportToExport.ExportOptions.ExportDestinationType =       
    reportToExport.ExportOptions.ExportFormatType =           
    reportToExport.ExportOptions.DestinationOptions = options;

The Report Object model provides functionality to create exports in the following formats:

·         PDF

·         HTML 3.2 and HTML 4.0

·         MHTML

·         Microsoft Excel (97-2003)

·         Microsoft Excel (97-2003) Data-only

·         Microsoft Word (97-2003)

·         Microsoft Word (97-2003) - Editable

·         ODBC

·         Record Style - Columns with spaces and Record Style - Columns without spaces

·         Report Definition

·         Rich Text Format (RTF)

·         Separated Values (CSV)

·         Tab Separated Text (TTX)

·         Text

·         XML

·         XML Legacy

Suppressing Report Sections

Many times developers need to hide (suppress) a section of a Crystal Report. If the logic for this task were placed on the Crystal Report, it would make most sense to place it in a function. When I develop Crystal Reports, I try to keep Crystal Reports functions to a minimum. This makes the reports easier to maintain, and keeps business logic out of the report itself. Crystal Reports allows you to name sections to aid in finding them programmatically. When you open a Crystal Report in the Visual Studio IDE, the Crystal Reports tools provided there allow you to set the Name property on a section.

Figure 4: Name property of a section of a Crystal Report within Visual Studio

Listing 5: Suppressing a section programmatically

using (ReportDocument report = new ReportDocument())
        .SectionFormat.EnableSuppress = true;
    crvViewer.ReportSource = report;

The Crystal Reports Viewer (Web Control)

Table 1: Selection of common properties worth describing


For showing the report as-is or with scroll-bars.


Should the bottom toolbar be shown in the viewer, this defaults to true.


For showing the Group Tree on the left-hand side of the viewer.


Should the viewer show the button to display the dialog that will print the report, this defaults to true.


Should the viewer show the button that refreshes the data for the report, this defaults to true.


Should the viewer show the options that allow for searching in a report, it defaults to true.


Should the zoom features be shown, defaults to true


Height of the report viewer control


Width of the report viewer control


Should the Crystal reports logo be shown in the toolbar, this defaults to true.


For displaying a report in separate pages or one long page


Path to the images that are used for the toolbars, often times developers will override these images to match the style of their applcation

Dynamic Images

I was recently working with a client who felt that the charting component of Crystal Reports 2008 was not "elegant" enough. The client and I found a charting control that fit our needs, which would render the chart as a PNG. Before the report was rendered we called the charting control with our data to create the PNG, and then used logic similar to the example below to dynamically change an image.

Listing 6: Code to add the chart path to a dataset

DataSet chartData = new DataSet();
DataTable chartTable = new DataTable();                     
// build the chart and set the image path to the ChartImagePath field
chartTable.Rows.Add(new object[] { 
GetChartPath(ref chartCustomers) });

Adding a dynamic image to your report

• Add an image to your report.

• Right click on the image and selecte "Format Graphic."

• On the "Picture Tab," Click the formula button (X+2 button).

• Create a formula to pull the chart image path from the dataset.

Figure 5: Graphic location


Figure 6: Graphic location formula


View Entire Article

User Comments

Title: poor article   
Name: Hamid
Date: 2009-07-22 2:09:38 AM
I have VS.NET 2008 and there isn't "Format Graphic" when right-click on picture and just there is "Format Object" and there isn't any formula button (X+2 button) in it. It would be a good point if you inform readers about some exceptions.
Thank You
Title: API is powerful, but...   
Name: David (hand-on)
Date: 2009-07-17 2:34:02 PM
This article is a great starting point for all Crystal developers not very familiar with the Crystal API. You can really program whole report instead of using standard design.
But it is such a headache to support those reports. Contrary to the goal of this article - declare separation of business rules and presentation - this approach just mixing both together. I would use stored procedures where it is possible (unfortunately it is quite often a DBA privilege)
Title: Windward > Crystal Reports for Easy to Use Business Reporting   
Name: G-ram
Date: 2009-05-22 6:27:11 PM
While Crystal Reports maintains its role as the leader in reporting software it still challenges non technical users, if you want to overcome this issue come Demo Windward reports here
Title: useful article   
Name: santosh
Date: 2009-05-14 8:12:16 AM
very good article
please provide advanced crystal reporting concepts also

Product Spotlight
Product Spotlight 

Community Advice: ASP | SQL | XML | Regular Expressions | Windows

©Copyright 1998-2024 ASPAlliance.com  |  Page Processed at 2024-06-23 8:11:47 PM  AspAlliance Recent Articles RSS Feed
About ASPAlliance | Newsgroups | Advertise | Authors | Email Lists | Feedback | Link To Us | Privacy | Search