The Report Engine Object Model is the .NET programmatic entry point to the Crystal Reports engine. It provides a collection of objects, methods, and properties that enable you to process, save, export, and print reports. While doing that, you are able to manipulate the report by modifying parameter values, database credentials, sorting, and grouping. The Report Engine Object Model (hereafter referred to as the object model) consists of a standard .NET assembly called CrystalDecisions.CrystalReports.Engine.dll. As the name of the dll implies, the namespace for all the objects contained in this dll is CrystalDecisions. CrystalReports.Engine. Because this is a standard .NET assembly, the object model contained within it can be used from any .NET programming language or tool. All sample code within this chapter uses the Visual Basic .NET language, but any .NET-compliant language could, of course, be used. Keep in mind that although the object model is pure "managed" code, the underlying report engine is not. This means you can perform a pure "xcopy" deployment that Microsoft likes to advertise that all .NET applications can do.
There are many objects and thus capabilities in the object model. This chapter does not explain all of them but rather covers the most common scenarios. For a complete reference of all objects, properties, and methods, consult the Crystal Reports 10 documentation that is installed to the MSDN Help Collection. Some of you may be skeptical about the product documentation because in the past it was very sparse. However, there is much more information in the documentation in version 10 than ever before; have a look through it and you will be impressed.
The main object you use when working with the object model is the ReportDocument object. It is the root object in the object model hierarchy and forms the entry point to opening reports. The first step in opening reports is to create a new instance of the ReportDocument class. Then to open a report file, call the Load method. This method takes a single parameter, which is a string that points to the RPT file. An example of this is as follows:
Dim Report As New ReportDocument Report.Load("C:My ReportsSales.rpt")
One common way to handle file paths is to use Application.StartupPath to determine the current location of the Windows Forms executable and reference report files relative to there.
The other way to load a report is to use a strongly typed report object. A strongly typed report object is an object automatically generated when a report is added to the Visual Studio .NET project. This object (sometimes called code-behind) is specific to the report file both in its class name and properties. For example, a report added to the project called InvoiceReport.rpt would in turn have a class called InvoiceReport. Instead of calling the Load method, a developer only needs to create an instance of the InvoiceReport class. This class knows how to locate the report. In the case of strongly typed reports, instead of having an external RPT file, the report file is compiled into the application executable. The report is loaded out of the applications resources from there. Whether you use a ReportDocument (untyped report) or a strongly typed report, the rest of the object model is the same.
One of the most common uses of the object model is to run a report and export it to another file format. In past versions, exporting required a good sized chunk of code. Fortunately exporting in version 10 is very easy with the updated object model. First, a ReportDocument object needs to be created and a report loaded into it. After that is done, several exporting methods are available to you:
A common argument to all these exporting methods is the export format type. This is specified using the ExportFormatType enumeration found in the CrystalDecisions.Shared namespace. Its generally a good idea to add a reference to CrystalDecisions.Shared.dll because you will find many common objects used in the object model located in this assembly. The following list describes the members of the ExportFormatType enumeration:
When exporting to Crystal Reports format, a standard RPT file is created; however, the report has saved data. This is quite useful because you can run a report once and export to Crystal Reports format and then have many people view that report using the saved data. In this scenario, only one hit is made to the database even though many people are viewing the report. This is similar to creating a report instance in the Crystal Enterprise environment. This feature can be used to affect a greater scalability by introducing a "report instance" delivery model.
A common scenario for exporting would be processing many reports in a batch job. This is a great use of the object model. To help you do this effectively, Ill share a few tips here. First, you need to clean up to make sure memory is released, and second, use multiple threads to maximize the time available for processing reports. The report engine object model is thread safe. Listing 29.1 illustrates a multithreaded report processing class. Listing 29.2 shows how this class could be called.
Imports System.Threading Imports CrystalDecisions.Shared Imports CrystalDecisions.CrystalReports.Engine Public Class BatchProcessor Private ReportList As New ArrayList Private OutputFolder As String Private BatchCounter As Integer Call this method to add a report to the list of reports to be processed by the batch processor Public Sub AddReportJob(ByVal ReportPath As String) ReportList.Add(ReportPath) End Sub This runs an individual report job Private Sub ProcessNextReportJob(ByVal Index As Object) Dim report As New ReportDocument Dim outputFileName As String Load the report based on index report.Load(ReportList(Index)) Construct an output filename outputFileName = "Report" & Index & ".pdf" Call the ExportToDisk method report.ExportToDisk(ExportFormatType.PortableDocFormat, _ OutputFolder & "" & outputFileName) Make sure to clean up the report object report.Close() Decrement a counter of remaining jobs BatchCounter = BatchCounter - 1 End Sub Public Sub ExecuteBatch(ByVal OutputFolder As String) Me.OutputFolder = OutputFolder BatchCounter = ReportList.Count Grab the current time Dim startTime As DateTime = DateTime.Now Start the batch job Dim i As Integer For i = 1 To ReportList.Count Use the .NET ThreadPool class to handle the multiple requests Dim wc As New WaitCallback(AddressOf ProcessNextReportJob) ThreadPool.QueueUserWorkItem(wc, i - 1) Next While BatchCounter > 0 Thread.Sleep(250) End While Dim elapsedTime As TimeSpan = DateTime.Now.Subtract(startTime) MessageBox.Show("Batch completed in " + _ elapsedTime.Seconds.ToString() & " seconds") End Sub End Class
Dim bp As New BatchProcessor bp.AddReportJob("C:TempReportsReport1.rpt") bp.AddReportJob("C:TempReportsReport2.rpt") bp.AddReportJob("C:TempReportsReport3.rpt") bp.AddReportJob("C:TempReportsReport4.rpt") bp.AddReportJob("C:TempReportsReport5.rpt") bp.AddReportJob("C:TempReportsReport6.rpt") bp.AddReportJob("C:TempReportsReport7.rpt") bp.AddReportJob("C:TempReportsReport8.rpt") bp.AddReportJob("C:TempReportsReport9.rpt") bp.AddReportJob("C:TempReportsReport10.rpt") bp.ExecuteBatch("C:TempOutput")
Although the fantasy of a paperless office floats around our heads, the reality today is that no matter how much technology for viewing reports is produced, people will always want to print them. Along these lines, the object model supports printing reports to printers. This is accomplished by calling the ReportDocuments PrintToPrinter method. It takes the following arguments, which determine basic print settings:
In addition to these printing options, there is another set of more advanced options. These options are in the form of properties and are contained in the ReportDocuments PrintOptions object:
Keep in mind that whatever account the report engine object model is running under needs access to the printer when the PrintToPrinter method is invoked. Sometimes when the object model is used in ASP.NET, it is running under a Guest-level account, which does not have access to the machines printers. If this is the case, you need to install and grant access to the printers for that account.