SqlReportViewer is a specialized implementation of UXDocumentViewer designed to work with Microsoft SQL Server 2008 Reporting Services document. SqlReportViewer includes sophisticated parsing and layout rendering implementation which presents the report identical to the design. In addition, it also features automatic pagination capability which renders the report based on the paper size defined in the report. This behavior is similar to the PDF export result in the SQL Server Reporting Services (further abbreviated as SSRS). To learn more about SQL Reporting Services, please visit MSDN Library.

SqlReportViewer supports SQL reporting service actions such as Toggle item, Go to report, Go to bookmark, and Go to URL, as well as exporting. The supported export formats in SQL reporting service, such as XML, CSV, PDF, HTML, Excel, and Word, are well supported in SqlReportViewer.

SqlReportViewer Overview

SqlReportViewer is an advanced and feature-rich report viewer control which renders SSRS reports with identical layout and appearance as the report design. It supports most report items available in SSRS such as TextBox, Line, Image as well as comprehensive support for Matrix, Table and List (Tablix). SqlReportViewer supports both Silverlight and WPF platforms equipped with key features such as pixel-perfect document rendering, search and highlight matching words, text selection, copy to clipboard, navigate to page, background loading and printing support.

In addition, SqlReportViewer also features historical journal navigation using the back and forward toolbar button. Toggle item and goto report actions will automatically add an entry to the historical navigation list.

The following table lists the supported SQL reporting service control.

As shown in the table above, most report items in SSRS are natively supported in the SqlReportViewer control. However, some controls such as Chart, Map, and Gauge are not rendered by default. To render these controls, a custom rendering class must be implemented such as described in How-to: Extending SqlReportViewer Rendering Engine.

Using SqlDocumentViewer

SqlReportViewer shares many common features with UXDocumentViewer such as rich navigation support, zoom presets, text selection, search, localization and printing. To learn about these shared features in details, please refer to UXDocumentViewer Overview.

In addition, SqlReportViewer provides a number of advanced features to work with SQL reporting service report such as background loading feature which is designed to handle relatively large report, report navigation, and report browser.

Before you can use SqlReportViewer, you need to first register the rendering extension and configure the server-side settings such as handlers and service points. To get started, please see Walkthrough: Configuring SqlReportViewer for First Time Use.

The following example shows the XAML code to display a SSRS report in SqlReportViewer.

<Intersoft:SqlReportViewer ReportProxyHandler="http://adventureworks.com/SqlReportViewerHandler.ashx" 
                           ReportServer="http://localhost/ReportServer" 
                           ReportName="/Customers Report" />

Before you can use SqlReportViewer to display a report, you need to first design the report using either Report Builder or Visual Studio tools for SSRS. The following illustration shows the design-time environment for SSRS and the viewer results in the SqlReportViewer. To learn more about designing report in SSRS, please visit MSDN Library.

Understanding SqlReportViewer Elements

SqlReportViewer facilitates users with the capability to view, search, and navigate a SQL report. To achieve these capabilities, SqlReportViewer comes with rich user interface elements that consisted of UXResizablePane, UXNavigationPane, UXVirtualizingListBox, UXTreeView, UXSearchBox, UXToolBar and UXStatusBar.

The following figure illustrates the rich user interface elements of SqlReportViewer in details.

The top illustration shows the control's elements with the navigation pane expanded, while the bottom illustration shows the control's elements with the navigation pane minimized.

Although the SqlReportViewer already provides predefined UI elements to allow rich user interaction, you are free to customize any of the elements to suit your application's preferences – thanks to the loosely-coupled architecture design that made the customization possible. You can customize the styles and appearance of the elements entirely by editing the control template using designer tools such as Expression Blend. To learn more about the commands used in the predefined UI elements, see the SqlReportViewer Commands section later in this topic.

Configuring Report Browser Feature

Report browser feature automatically load the list of available report in the report server. By default this feature is enabled. However, user has the option to disable the feature by setting EnableAutomaticListFetching property to False.

You can also define the custom report list by adding a new SQLReportMetadata instance to the report collection which is accessible through the ReportNavigationList property.

Configuring Loading Mode

SqlReportViewer supports three loading strategies such as discussed below.

• All
  All the pages are rendered on initial load.
• OnDemand
  All the pages is buffered in the client and only the displayed page is rendered.
• Streaming
  Only the displayed page is sent to the client and rendered. The streaming option also allow caching for 15 minutes, in which within the duration the resulted XAML is not reprocesses from the reporting service. The available caching option during streaming are FileState, opting for FileState requires the FileStateServerConnection property to be filled, and PageCache.

By default, SqlReportViewer is set to use load-on-demand mode which means that only pages visible in the document will be rendered. The rest of pages will be rendered when they become visible in the view due to user interactions, for instances, through page scrolling or outline navigation. Depending on your scenario, you may wish to load all pages in SqlReportViewer initially which can be achieved by setting the LoadingMode property value to All.

Another available loading strategy is Streaming mode which only load and render the visible pages in the document.

Enabling Background Loading

Designed for performance, SqlReportViewer is capable in handling large SQL report without performance bottleneck, thanks to the innovative background loading feature. Background loading allows pages to be preloaded in the background during application's idle time. This means that the background loading will pause the process when it detects user's activities such as mouse movement or key press.

The idle latency can be customized through the IdleLatency property which is set to 3 seconds by default. You can disable this feature by setting the EnableBackgroundLoading property value to False.

Configuring Report Parameters

Comprehensive report parameter support is available in the SqlReportViewer control. The parameter panel will be automatically displayed with the respective parameters defined in the SSRS report. Based on the parameter type defined, SqlReportViewer will use different input control to match the defined parameter type.

The following table describes the control associated to each parameter type.

If predefined values are available in the report, SqlReportViewer will use UXComboBox control to display the options.

SqlReportViewer also includes built-in validation for required parameters, i.e., the parameters which AllowBlank and AllowNull properties are set to False in the report. When the Submit button is clicked, the required parameters will be automatically validated. A validation error message when be displayed for each required parameter that has not been filled. Also note that Boolean type parameter is considered as False by default.

SqlReportViewer also exposes a command, set through the SubmitParameterCommand property, which will be invoked when the Submit button is clicked. The submit action will be executed when the IsReportParameterError property value is true.

The collection of currently displayed report parameters object can be obtained from the ReportParameters property. You can extend the parameter by implementing ISqlParameterMetadata interface and overwriting the ReportParameters property.

Extending SqlReportViewer Rendering Engine

As explained in the previous topics, some report items require rendering engine extension in order to be rendered successfully in the SqlReportViewer. These controls are:

• Chart
• Gauge
• Map
• Data Bar
• Sparkline

The provided rendering engine extension for the controls are:

Each renderer provides two override functions which should be implemented to successfully render the conttrol representation in SqlReportViewer:

• void RenderItem(Chart chart, ReportRenderItem reportRenderItem)
  Invoked when rendering control in the page.
• string RenderItem(Chart chart, out string customAttribute)
  Invoked when rendering control inside a tablix container.

By default, without extending rendering engine, the control is rendered as a text placeholder as shown in the left image below.

Extending chart rendering engine using Silverlight toolkit assembly will result in the right image. For more detailed explanation about rendering engine extension, see How-to: Extending SqlReportViewer Rendering Engine.

Using SqlReportViewer to Display Multiple Reports

SqlReportViewer is designed to handle numerous reporting scenarios such as single report scenario and multiple report scenario. To learn more about the scenarios, see the topics below.

• How-to: Use SqlReportViewer to Display a Single Report 
• How-to: Use SqlReportViewer to Display Multiple Reports

Localizing SqlReportViewer

SqlReportViewer provides full localization support for the textual content used in the user interface elements. The following table lists the localizable string resources.

SqlReportViewer Toolbar

SqlReportViewer provides comprehensive commands for rich viewing experiences. Many of the essential commands are presented as command buttons in the toolbar and status bar section of the control. The complete elements can be seen in the section above.

The following table lists the commands presented in the toolbar section of the SqlReportViewer control.

Report Navigation
	Navigate to the previous report in the history.
	Navigate to the next report in the history.
Export
	Export displayed report to XML format.
	Export displayed report to CSV format.
	Export displayed report to PDF format.
	Export displayed report to HTML 4.0 format.
	Export displayed report to JPEG image format.
	Export displayed report to Microsoft Excel format.
	Export displayed report to Microsoft Word format.
Page Navigation
	Displays the current page shown in the content section and the total page count of the document. You can enter a page number to directly jump to the specific page.
	Scroll to the previous page in the document.
	Scroll to the next page in the document.
	Show or hide the navigation section.
	Sets the navigation mode to Thumbnails.
	Sets the navigation mode to Report Links.
Page Zooming
	Sets the zoom mode to show the actual size of the document.
	Sets the zoom mode to fit the width of the document.
	Sets the zoom mode to fit the height of the document.
	Magnify the document size by a preset ratio.
Search
	TextBox to fill in the search criteria.
Others
	Toggle the SqlReportViewer control to fill the screen.
	Print the document using print file dialog.
	Copy the highlighted text.
	Reload the report list from the report server.

SqlReportViewer Commands

SqlReportViewer is built around the commanding semantics which allows the document interaction to be executed through declarative definition in the XAML markup. The commanding semantics is also an ideal approach for MVVM pattern development.

In addition to the commands in UXDocumentViewer, SqlReportViewer also includes predefined commands to interact with the report document which are described in the following table.