Building Report-enabled Applications with the New ReportViewer Controls (Part 1 of 2) : Page 2

Remote Mode
In remote mode, the Report Server renders the report. In this mode, you would typically use the Report Designer to author the report definition. When the report is ready, you deploy the report to the report catalog to make it available to report clients. The remote mode offers the following main advantages:

• Centralized report management. You deploy and centrally manage all of your reports in a single repository—the report catalog.
• Rich feature set. You can leverage all Report Server features, such as scheduling, security, session and snapshot execution, linked reports, My Reports, etc. Note that the actual feature set varies among the RS editions.

Figure 3. Remote Mode: In remote mode, the report is rendered by the Report Server.

When you configure the ReportViewer in remote mode, it essentially acts as a thin presentation layer to the Report Server. The Report Server does the heavy lifting to process the report; the ReportViewer renders the report (see Figure 3). Behind the scenes, the ReportViewer calls the Report Server APIs to retrieve report and parameter metadata, pass parameters, and carry out user-initiated commands, such as zooming, printing, searching, etc. The ReportViewer performs most of its inner workings by making SOAP calls to the RS Web service. The noticeable exception is that report preview and rendering use URL addressability for performance reasons, to avoid incurring additional overhead for serializing the report payload—because the SOAP protocol is less efficient for transferring large chunks of data. A special RGDI rendering extension (new to RS 2005) is used to render the report, while a previewed report is rendered in EMF format. By default, exceptions thrown during report processing are embedded in the ReportViewer report pane. If this is not acceptable, you can handle the ReportError event of the ReportViewer object programmatically. The Exception property of the ReportErrorEventArgs class gives you the error that occurred. Setting the Handled property to true will prevent the ReportViewer from displaying an error message.

Requesting a Server Report
Developers who have generated reports by integrating with the RS Web service will undoubtedly appreciate the simplicity the ReportViewer brings to the table. Requesting a server report that doesn't require parameters takes only a few lines of code.

   reportViewer.ProcessingMode = 
   Microsoft.Reporting.WinForms.ProcessingMode.Remote;
   // Get the Report Server endpoint from the application 
   // config file
   reportViewer.ServerReport.ReportServerUrl = new 
      Uri(Settings.Default.ReportServerEndPoint);
   reportViewer.ServerReport.ReportPath = 
      "/Prologika/Customer Orders";
   reportViewer.RefreshReport();

The preceding code sets the ReportViewer ProcessingMode property to ProcessingMode.Remote because it's requesting a server-based report. Next, it sets the ReportServerUrl property to the Report Server endpoint and report path retrieved from the config file, and finally, calls the RefreshReport method, which submits the report request and renders the report. It really can't be simpler! No need to mess with WebMethod arguments and save the report payload to a physical file. No need to handle images and sessions.

Note that if you need to request a specific history run for a report configured for snapshot execution, set the reportViewer.ServerReport.HistoryId property to the desired history identifier.

Handling Report Parameters
The ReportViewer can detect the report parameters for parameterized reports automatically. When the ShowParameterPrompts property is set to True (the default), the ReportViewer displays parameter placeholders in the Parameter Area of the toolbar. This behavior is consistent with rendering reports in the Report Manager. Behind the scenes, the ReportViewer invokes the LoadReport method (new with RS 2005) which returns an ExecutionInfo object describing the report, including the report parameters. The ReportViewer uses this information to configure the parameter prompts, displaying appropriate controls. For example, it displays a calendar control for parameters with the DateTime data type, or a multi-select list for multi-valued parameters.

If the parameter prompts don't meet your integration requirements, you can hide the parameters area and implement your own UI instead. You can call the ReportViewer GetParameters method to obtain the parameter metadata. After collecting the parameters, you can pass them to the ReportViewer as follows:

   ReportParameter[] parameters = new ReportParameter[2];
   parameters[0] = new ReportParameter("Date", "1/1/2003");
   parameters[1] = new ReportParameter("CustomerID", 
      new string[] { "14335", "15094" });
   reportViewer.ServerReport.SetParameters(parameters);

In the code above, the Customer Orders report takes two parameters. Note that the CustomerID parameter is configured as a multi-value parameter (new with RS 2005). You can pass multiple parameter values by constructing a string array. The SetParameters method invokes the SetExecutionParameters method, which prepares the report execution object in anticipation of the Render call (submitted when the report is refreshed).

Author's Note: In VB.NET arrays are zero-based. Thus, the code Dim ReportParameter(1) declares an array that holds two parameters.

Previous Page

Next Page