Using Crystal Reports Web Services

One of the new features of Visual Studio .NET is the web service: a web server “based application that exposes a set of data based on the Extensible Markup Language, or XML. The web service exposes its actual data, as well as its data layout (or schema), through the Hypertext Transport Protocol, or HTTP. Because the XML data layout is simply an extension of HTML and because HTTP is such a ubiquitous communications protocol, virtually all networks, intranet systems, and Internet connection methods (dial-up, firewalls, and so forth) work with these standards already.

Crystal Reports for Visual Studio .NET fully supports web services ”being able to both create and consume web services. Creating a web service based on a Crystal report exposes a report via HTTP to anyone who can consume a web service anywhere on an intranet or the Internet. VS.NET also allows you to create projects that use or consume published Crystal Report web services. In this scenario, you create a Windows or web application, including a Windows Forms Viewer or Web Forms Viewer, which is then bound to the report exposed by the web service.

Note	Creating web services and consuming web services in VS.NET web applications is covered in Chapter 22.

Consuming Web Service Reports in a Windows Application

Once a web service has been created and compiled, you can actually use a web browser to view the properties of the web service. The URL will be provided to you by the web administrator, or the person who created and exposed the web service. Typically, report web service URLs are based on the application or web service used to publish the report, and the report name. For example, if a web service is created with the name of WebService1, and it publishes a report named FedExOrders.rpt, a FedExOrdersService.asmx file will be created in the WebService1 virtual directory. If you type in the following URL in a standard web browser:

http://<

server name

>/WebService1/FedExOrdersService.asmx

you ll see the properties exposed by the report web service. You may click various hyperlinks on this page to see the underlying XML that the web report service exposes, but the report will not be viewable in the browser directly using this URL.

click to expand

In order to view or consume a report web service, you must create a VS.NET Windows application and add a Crystal Windows Forms Viewer to it. You must then bind the Windows Forms Viewer to the report exposed by the report web service. As you might expect, there are several ways to reference a report web service in your Windows application and bind the Windows Forms Viewer to it.

Binding by URL as the ReportSource

Binding report web services to the Windows Forms Viewer must be done in code. The viewer s Report Source property in the Properties box is unable to accept a URL as a value. For this reason, you ll need to bind the report to the viewer s ReportSource property in the code editor (probably in the parent form s Load event). Here s an example:

Private Sub Form1_Load(ByVal sender As System.Object, _


ByVal e As System.EventArgs) Handles MyBase.Load


CrystalReportViewer1.ReportSource = _


"http://localhost/WebService1/FedExOrdersService.asmx"


End Sub

This code fragment shows the Windows Forms Viewer being bound to a report web service exposed on localhost (your own computer s web server). The exposed report is originally entitled FedExOrders.rpt and is published as a web service from a web project named WebService1.

Binding by Adding the Report Web Service as a Reference

You may also add a reference to the web report service to your Windows project and instantiate a copy of any reports exposed by it. To do this, perform the following steps:

Add a reference to the web service by clicking the References category of the Solution Explorer. Right-click the References category and choose Add Web Reference from the pop-up menu. The Add Web Reference dialog box will appear.
In the Address line of the Add Web Reference dialog box, type the full URL for the web service. For example, to add a reference to the FedExOrders report web service discussed previously, you d type:
```
http://localhost/WebService1/FedExOrdersService.asmx
```
You ll see the same web browser display you would see if you navigated to the URL in a standard web browser. Also, a list of all exposed report web services will appear in the box on the right of the dialog box. And, the web server name will appear as the default name for the reference. If you wish to reference the web server by a different name, type it in the Web Reference Name text box. When you re finished, click OK to add the report web services as references.

To reference the web service in the Windows Forms Viewer, you may execute code similar to the following in the Load event of the form containing the viewer:

CrystalReportViewer1.ReportSource = _


New localhost.FedExOrdersService

When you run the application, the report exposed by the web service will appear in the form containing the viewer.

Setting Viewer Properties with Consumed Web Services

The actual report exposed by the report web service isn t strongly typed. For this reason, you don t have the same control you do over a strongly typed report making use of the Report Engine namespace. However, you can still manipulate the report with classes exposed by the Crystal Windows Forms Viewer (you have a much richer set of choices if you ve installed Crystal Reports 10 Developer or Advanced Developer editions).

For example, you can still make use of viewer properties to provide database credentials, set the record selection formula, or supply parameter field values. For example, the following code will supply a beginning and ending date to a date range parameter field included in the report exposed by the report web service:

Dim Parameters As New CrystalDecisions.Shared.ParameterFields


Dim Parameter As New CrystalDecisions.Shared.ParameterField


Dim ParamValue As New CrystalDecisions.Shared.ParameterRangeValue




Parameter.ParameterFieldName = "Date Range"


ParamValue.StartValue = #1/1/2002#


ParamValue.EndValue = #12/31/2002#


Parameter.CurrentValues.Add(ParamValue)




Parameters.Add(Parameter)




CrystalReportViewer1.ParameterFieldInfo = Parameters

Distributing Crystal Reports Windows Applications

Once you ve designed your Crystal Reports Windows application, you ll probably need to package it for deployment to client PCs. Generally speaking, Crystal Reports “based applications are no different than any other application ”you can create a typical Setup and Deployment project using standard VS.NET steps to create a Microsoft Installer package to install the Windows application on the target computer.

When deploying Windows applications that contain Crystal Reports, keep the following general concepts in mind:

The target machine must contain the .NET Framework Depending on how you create your setup project, you may not include the .NET Framework files in the setup routines. Because Crystal Reports for VS.NET fully integrates with the .NET Framework, you ll need to ensure it is installed on the client computer before installing your Crystal web application.
You will need Business Objects “supplied merge modules If you have installed Crystal Reports 10 Developer or Advanced Developer Edition on your development machine, you ll need to distribute updated Crystal Reports 10 modules with your application. This is accomplished by using one (and, if you are embedding geographic maps in your report, an additional) merge module when you build your setup project.

Download the Crystal Reports 10 merge modules from http://support .BusinessObjects.com/MergeModules. You ll find included documentation that specifies what object models, viewers , and features are included with the various merge modules.

If you are using the version of Crystal Reports that ships with Visual Studio .NET, merge modules are found in \Program Files\Common Files\Merge Modules. You may also find updated versions of these merge modules on the Business Objects web site.
Don t forget the keycode When developing your reporting application, you may have noticed a Crystal screen prompting you to register your copy of Crystal Reports for VS.NET. This appears whether you are using the copy of Crystal Reports included with VS.NET or you ve installed Crystal Reports 10 afterward (and, sometimes even if you ve registered your stand-alone copy of Crystal Reports).

While you can bypass this screen when developing your application, you won t be so lucky when it comes time to distribute it. If a valid Crystal keycode isn t specified when you build your setup program, your distributed application won t work. You may obtain the necessary keycode by following the steps in the registration prompt (you ll be taken to the Business Objects web site and asked to supply various pieces of personal information).

Once you re finished with registration, you can display the keycode by choosing Help About Microsoft Development Environment from the VS.NET menus . Note the three-part keycode that appears next to the Crystal Reports entry in the list. Either write it down, or select the Crystal Reports entry and click the Copy Info button to copy the keycode to the Windows clipboard.

When you build your setup project, you must select the primary Crystal Reporting merge module and paste the keycode into the Keycode Properties box.

Note	If you installed Crystal Reports 10 Developer or Advanced Developer Edition, your keycode should be the same keycode on the program CD that you used when you installed stand-alone Crystal Reports 10.