Handling ReportViewer Events
The ReportViewer supports a number of events that your code can handle at runtime. For example, the Windows Forms ReportViewer always processes the report request on a background thread to keep the main application thread responsive. If the application needs to be notified when the repot is ready, it can sink the RenderingComplete event. It is important to note that these events are raised by the control, not by the report processor. Therefore, you cannot use these events to change the report definition. Instead, the ReportViewer raises events when the control state changes, giving your application a chance to do some pre- or post-processing of remote and local reports.

Although the ReportViewer raises events in both modes, you will probably find them more useful in local mode. That's because in local mode, your application handles additional reporting tasks, e.g. passing data to a drillthrough report or subreport, collecting parameters, etc. WinReporter demonstrates how your application can handle two of the most useful events—Drillthrough and Hyperlink.

Implementing Report Drillthrough
As with its server counterpart, the Customer Orders local report allows the end user to click on an order number to drill through to the Sales Order Detail.rdlc report and see the order details. However, as with any local report, the application has to supply the data for the drillthrough report. This happens in the Drillthrough event.

   
   private void reportViewer_Drillthrough(object sender, 
      DrillthroughEventArgs e)
   {
       if (e.Report is ServerReport) return;
   
       LocalReport localReport = (LocalReport)e.Report;
       // Sales Order Detail local report 
       // takes two datasets
       // Load the Sales Order dataset
       OrderTableAdapter orderAdapter = new 
          Entities.SalesOrderTableAdapters.
          OrderTableAdapter();
       SalesOrder.OrderDataTable orderTable = 
          orderAdapter.GetData(localReport.
          OriginalParametersToDrillthrough[0].Values[0]);
       // Load the Sales Order Detail dataset
       OrderDetailTableAdapter orderDetailAdapter = new 
          OrderDetailTableAdapter();
       SalesOrderDetail.OrderDetailDataTable 
          orderDetailTable = orderDetailAdapter.GetData(
          localReport.OriginalParametersToDrillthrough[0].
          Values[0]);
   
       localReport.DataSources.Add(new ReportDataSource(
          "SalesOrder", orderTable));
       localReport.DataSources.Add(new ReportDataSource(
          "SalesOrderDetail", orderDetailTable));
   }
   

The ReportViewer passes the drillthrough target report in the DrillthroughEventArgs argument. First, the code checks the source of the drillthrough event. In this case, you need handle only drillthrough events, and only those from local reports. The application gets the selected order number from the OriginalParametersToDrillthrough property. Finally, the application passes the two datasets to the Sales Order Detail report (one for the order header and another for the order details).

Figure 6. Raising Events: Use a hyperlink event to raise an event back to the application.

Implementing a Custom Navigation Action
Sometimes, you may need to pass some information from the report to the application—in other words, implement update capabilities. In an example scenario, a user can click on the customer identifier inside the report. The application intercepts the event and displays the customer details. You might want to let the user update the customer record and save it back to the database. Then, the application would refresh the report to show the changed data.

You can use a Hyperlink event to implement this scenario. First, define a "Jump to URL" action on the textbox control that displays the customer identifier (see Figure 6). Next, sink the ReportViewer Hyperlink event.

   private void reportViewer_Hyperlink(object sender, 
      HyperlinkEventArgs e)
   {
       Uri uri = new Uri(e.Hyperlink);
       if (uri.Scheme.ToLower() == "customerid")
       {
           e.Cancel = true;
           // Load the customer details in another form
         ((ReportViewer)sender).RefreshReport(); 
       }
   }

The HyperlinkEventArgs exposes the hyperlink itself. Assuming that the end user has clicked on customer 14335, the hyperlink will look like "customerid:14335." Since there may be other hyperlink events raised by the same report or other reports, we check the hyperlink schema, which in this case will return "customerid." Next, the application does whatever it needs to with this customer. Finally, the event handler refreshes the report to show the updated results.

Building a report-enabling custom application doesn't have to be a tedious chore. If you are tasked to report-enable.NET 2.0 Windows Forms applications and you target RS 2005, do yourself a favor and use the Windows Forms ReportViewer. Configure the ReportViewer in remote mode when requesting server reports, and consider local mode, when you need to distribute reports with your application or bind the report to an application dataset.

From here, I suggest you review the resources available on the ReportViewer website, where you'll see how to get the most out of the ReportViewer in local mode, including using custom assemblies, working with subreports, binding to object data sources, generating the report definition on the fly, and more. Make sure to check also ReportViewer newsgroup on MSDN where you can post questions and get feedback from the technical community.