| When creating simple reports, you won't usually hard-code the properties or call many of the methods exposed by the ReportViewer, with the obvious exception of the ReportViewer.RefreshReport method. However, as your reports and report applications get more sophisticated, you'll want to leverage the underlying classes used to manage reports. For example, if you want to use a menu to launch a selected report, you can use the ReportViewer instance's LocalReport property (which exposes a LocalReport instance) to point to a specific RDLC file and its associated Data Source. This way, you can reuse a single ReportViewer instance or instantiate a new form that hosts the ReportViewer. I'll show an example of that application later in this section. Another approach might be to permit your application to launch any selected report from its source RDLC file. In this case, you would have to extract the embedded queries and create an appropriate Data Source or provide one through other means. That application is fodder for a whitepaperany volunteers? The ReportViewer Properties Let's take a short look at the fundamental ReportViewer properties, methods, and events. I'll save a detailed look for later. All of these (basic) properties are exposed via the Visual Studio property page: CurrentPage: Gets or sets the report's current page. This can be used to get the ReportViewer to navigate to a specific page in the report. DocumentMapCollapsed, DocumentMapWidth, and ShowDocumentMapButton: These properties determine how the Document Map and the button to activate a Document Map are displayed. I illustrate programming and use of Document Maps in our Reporting Services book and in the final section in this chapter. Basically, this is an area exposed on the left side of the report that permits users to navigate to a specific section of the report. For example, the report shown in Figure 14.23 includes a document map that permits easy navigation to each section of the reportone section for each product color. Figure 14.23. Enabling the Document Map.  HyperlinkTarget: Gets or sets where to go when a hyperlink in the report is clicked. This link can point to a subreport or to a URL. LocalReport: Addresses and describes a LocalReport instance that points to the local RDLC report (file) and Data Source being managed by the ReportViewer. I discuss the LocalReport class in depth later in this section and throughout the chapter. ProcessingMode: Determines whether the ReportViewer is processing a client-side (local) or server-side (remote) report. This property defaults to "local". PromptAreaCollapsed: When linking to remote Reporting Services reports, this property determines whether the parameter prompts are shown (the default) or hidden. This property setting has no effect on "local" mode reportsit makes sense only for remote mode. ServerReport: This property addresses and describes a ServerReport instance. When set, the ReportViewer is set to "remote" mode. The ServerReport instance addresses a Reporting Services 2005 deployed report. I discuss the ServerReport class later in this section. ShowCredentialPrompts: This property (used only in remote mode in server-hosted reports) determines whether the user is prompted for logon credentials as specified by the Reporting Services deployed report configuration. ShowExportControls, ShowFindControls, ShowPageNavigationControls, ShowPrintButton, ShowPromptAreaButton, ShowToolbar, ShowZoomControl, and ShowRefreshButton: These properties determine which option buttons are displayed by the ReportViewer toolbar, as shown in Figure 14.24. Depending on what functionality you want to expose to your application user, you might want to hide some of these buttons (which are all on by default). Figure 14.24. The ReportViewer toolbar.  ShowReportBody: Determines whether the report body should be visible in the ReportViewer. ZoomMode and ZoomPercent: Gets or sets if the report is shown 100% or zoomed in or out and at what percent.
The ReportViewer Methods The following methods are those you're most likely to access. JumpToBookmark, JumpToDocumentMapID: Navigates the ReportViewer to the selected bookmark or document ID. PerformBack: Navigates the ReportViewer back to the parent report from a drillthrough report. RefreshReport: Calling this method flushes the current report and re-renders the report using the current state of the DataTable bound to the LocalReport or ServerReport property. A call to this method is added to Form_Load whenever you make a change to the ReportViewer Data Source via the ReportViewer Tasks dialog. Reset: This method clears the ReportViewer properties to their default state and replaces the LocalReport object with a new instance. This method might be necessary when you set up a report with the ReportViewer UI but want to override those settings at runtime. This method is not documented but is accessible in the class.
The ReportViewer Events The following events are those you're most likely to use to monitor your report application: Back: This event fires when the user navigates back from a drillthrough report. BookmarkNavigation: Fires when the user navigates to a bookmark in report. Drillthrough: Fires when a report item programmed with an action is clicked. This event is responsible for populating the targeted report's Data Source. I show an example of its use later in this chapter. DocumentMapNavigation: Fires when the document map is selected. Hyperlink: Fires when the user clicks a report hyperlink. PageNavigation: Fires when the user changes the current page. Print, ReportExport: Fires when the user requests to print or export the report. RenderingBegin, RenderingComplete: Fires as the report begins and ends rendering. ReportError: Fires when an error occurs in the report. This event returns a ReportError instance that contains the Exception and Handled arguments. Handled is True if the host application has dealt with the exception.
The LocalReport Class The ReportViewer Tasks dialog is your UI portal to the LocalReport (or ServerReport) instanceor, at least, some of their properties. If you set the ReportViewer ProcessingMode to Local (or don't change the default setting), the LocalReport instance contains properties to address the report being displayed, address the Data Source(s), and set other properties to describe the report and how it behaves. Only a few of these properties are exposed via the ReportViewer Tasks, so you'll have to write code to extend its functionality if you want to do anything but launch an ordinary report (without parameters). The LocalReport Properties Let's walk through the LocalReport class to explore the properties, methods, and events you'll likely encounter as you create reports. DataSources: Gets a collection of data sources used by the report. This collection stores ReportDataSource instances that names the Data Source and DataTable used to populate the report. A single LocalReport instance can source data from (virtually) any number of Data Sources. I illustrate how to manage the DataSources collection later in this chapter. DisplayName: Gets or sets the display name of the report. This is rarely set or referenced in the UI. EnableExternalImages: Indicates whether the report can be rendered if it has external images. EnableHyperlinks: Indicates whether the report can be rendered if it contains hyperlink actions. IsDrillthroughReport: Indicates whether the report is a drillthrough report. This read-only property indicates whether the report being launched is a "drill-through" report. A report of this kind is simply a report that's been invoked by referencing it in an action dialog. I illustrate how to set up and manage drill-through reports later in this chapter. OriginalParametersToDrillthrough: Returns the parameters passed from a parent report to a drillthrough report. If the drill-through report needs to adapt its behavior (or query processing) based on parameters passed to the host report, you need to set this property to True. ReportEmbeddedResource: Gets or sets the name of the report embedded resource. This property points to the RDLC file. ReportPath: Gets or sets the local file system path of the local report.
The LocalReport Methods The LocalReport methods play a pivotal role when it comes to managing report parameters and report behavior. AddTrustedCodeModuleInCurrentAppDomain: Adds the supplied assembly to the list of assemblies that are trusted to execute in the current AppDomain. ExecuteReportInCurrentAppDomain: Causes processing extensions and expressions in the report to be executed in the current AppDomain. ExecuteReportInSandboxAppDomain: Causes processing extensions and expressions to be executed in an application domain with limited permissions. GetDataSourceNames: Returns a string list of the names of all data sources used within the local report. GetDefaultPageSettings: Gets the default page settings specified in the local report. GetDocumentMap: Returns the representation of the document map for the local report. GetParameters: Returns report parameter properties for the report. This method returns a ReportParameterInfoCollection that contains ReportParameterInfo objects. These objects define the report parameters in great detail and are used to pass parameters from the UI to the report processor. GetTotalPages: Returns the total number of logical pages in the report. ListRenderingExtensions: Returns all available rendering extensions for the local report. LoadReportDefinition: Loads a report definition from the local file system. This method can be used to load a RDLC file stored in the local file system. LoadSubreportDefinition: Loads a subreport definition. Refresh: Causes the local report to be rendered with new data. Render: Processes the report and renders it in the specified formatunfortunately, only EXCEL rendering is supported in the RTM version. SetParameters: Sets report parameter properties for the local report. Later in this chapter, I discuss how to create an array of ReportParameter objects and use the SetParameters method to apply it to the report.
The LocalReport Events There is only one LocalReport eventthe SubreportProcessing event. It's fired when a SubReport item is invoked by the ReportViewer. This event is responsible for supplying data to the subreport. I show how to create subreports later in this chapter and include a long section on how to manage the LocalReport instance to launch custom reports, manage drill-through and hyperlinked reports, as well as manage subreports. The ServerReport Class The ReportViewer control can also act as a launching pad for Reporting Services (2005 or later) reports. In this case, the ReportViewer sets the ProcessingMode to Server and exposes a ServerReport class. You'll need to code some extra steps if you intend to set report parameters before invoking the report, so I'll illustrate how to do so next. Remember that, by default, a server report exposes its own parameter prompts. You can choose to override these parameters in code or let the report UI handle them, but that raises a number of complex and undocumented issues. |
