Web.config Settings for ReportViewer

Article
07/13/2009

If you are using the ReportViewer Web server control, you can set ASP.NET Web.config application settings to configure the ReportViewer at run time. This topic describes the Web.config application settings used to connect to a remote report server, store temporary streams, and provide custom strings to the control user interface. It also provides recommendations for how to use <sessionState> and <machineKey> settings for ReportViewer applications that run in Web farm deployments, and explains how the <httpHandlers> Web.config section defines the settings for the HTTP handler used by the ReportViewer Web server control.

Configuring <appSettings> Elements for ReportViewer Controls

To configure custom application settings for the ReportViewer Web server control, you can add the following keys to the <appSettings> section in the application's Web.config file. The value of these keys is a fully qualified class name that implements a specific interface.

Key	Used by
ReportViewerServerConnection	This key specifies a class that implements the IReportServerConnection interface. This interface provides report server connection information when session state is turned off or when you do not want to store connection information in the ASP.NET session. If all reports used in your application are processed on the same report server, it is more efficient to use the ReportViewerServerConnection key to specify the connection information once in the Web.config file than to store the ReportServerUrl and TimeOut properties on each ServerReport object in session.
ReportViewerTemporaryStorage	This key specifies a class that implements the ITemporaryStorage interface. This interface is used to store the temporary streams that are sent by the report server rather than hold them in memory, thereby improving the scalability of your application.
ReportViewerMessages	This key specifies a class that implements the IReportViewerMessages interface. This interface is used to provide customized user interface messages.

Specifying the Fully Qualified Class

The value for each key is a class that implements the interface and the location of the assembly that contains it. In ASP.NET, there are several ways to specify the class by using this syntax:

<add key="MyKeyName" value="MyNamespace.MyClass, Location" />

If the class is implemented in an assembly, the location can be the application bin folder or the global assembly cache (GAC). In this case, the key value must be specified as a fully qualified assembly name that includes version, culture, and public key token values. Alternatively, if the class is implemented in a source code file in the APP_CODE folder of your application, that folder is the location you should specify.

The following examples are valid ways of specifying a fully qualified class in the GAC, the application bin folder, or in the APP_CODE folder:

<add key="ReportViewerServerConnection" value="MyNamespace.MyClass, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken= 00000000000000000 "/>

-- OR --

<add key="ReportViewerServerConnection" value="MyNamespace.MyClass, MyAssembly"/>

-- OR --

<add key="ReportViewerServerConnection" value=" MyNamespace.MyClass, APP_CODE"/>

ReportViewerServerConnection

If you implement the IReportServerConnection or IReportServerConnection2 interface to provide report server connection information, you must define the ReportViewerServerConnection key in the Web.config file. The key specifies your custom class that implements IReportServerConnection and the location of the assembly or source file that contains it.

If you provide the class in the ReportViewerServerConnection key, be sure that you do not set other properties on the ServerReport object that might conflict with it. Specifically, do not set the ServerReport.Timeout, ServerReport.ReportServerUrl, ServerReport.ReportServerCredentials, ServerReport.Cookies, or ServerReport.Headers properties.

The following example illustrates the syntax for the ReportViewerServerConnection key. It specifies the class that implements IReportServerConnection2 in an assembly named MyAssembly that is located in the application Bin folder:

<appSettings>
    <add key="ReportViewerServerConnection" value="MyNamespace.MyRVServerConnectionClass, MyAssembly"/>
</appSettings>

To view a code example of a class that implements IReportServerConnection, see Specifying Connections and Credentials for the ReportViewer Web Server Control.

ReportViewerTemporaryStorage

You must set the ReportViewerTemporaryStorage key to specify an object that implements the ITemporaryStorage interface. Implement this interface if you want to store the temporary streams that are sent by the report server rather than hold them in memory. Because each request must be completed before a new request can be started, only the current page is stored at any given time. This setting is used only for server reports. The following example illustrates the syntax for the ReportViewerTemporaryStorage key:

<appSettings>
    <add key="ReportViewerTemporaryStorage" value="MyNamespace.MyTemporaryStorageClass, MyAssembly" />
</appSettings>

ReportViewerMessages

You must set the ReportViewerMessages key to specify an object that implements IReportViewerMessages, which is in an interface that provides custom strings to the ReportViewer control. You can use this interface to support string localization for languages other than the ones provided by default. The following example illustrates the syntax for the ReportViewerMessages key.

<appSettings>
    <add key="ReportViewerMessages" value="MyNamespace.MyRVMessageClass, MyAssembly" />
</appSettings>

Configuring <system.web> Elements for ReportViewer Controls

In the application's Web.config file, you can define settings in the <system.web> section to determine report session behavior at run time. The ReportViewer control also uses this section to register settings for an HTTP handler that the control provides. The following elements are used: <sessionState>, <machineKey>, and <httpHandler>.

<sessionState>

You can use the sessionState element to determine whether session state is stored in process, turned off, or handled by the out-of-process ASP.NET state service.

InProc is the default setting and you can use it if your application runs on one computer. Do not use this setting if your reports run in an application that runs in a Web farm.

Off must be not used if the ReportViewer control is processing a client report definition (.rdlc) file in local mode. Local mode requires session state. If you are using remote mode, you can turn session state off. If you disable session state, be sure to specify ReportViewerServerConnection in the <appSetting> element.

You can also use the other <sessionState> modes: Custom, SQLServer, and StateServer.

<machineKey>

If you are deploying a ReportViewer control in a Web farm or cluster, you must specify the <machineKey> element to force all nodes in the farm to use the same process identity, thereby ensuring that view state saved from one computer can be read by any computer.

Note

Setting the <machineKey> element to synchronize view state in a Web farm is a best practice recommendation provided in the Microsoft .NET Framework 2.0 documentation. For more information about configuring view state validation for a network of Web services, see machineKey Element (ASP.NET Settings Schema).

In the .NET Framework 2.0, view state validation is enabled by default and uses ASP.NET process identity information to perform validation. Validation by process identity does not work in a cluster or Web farm scenario where the process identity varies for each node. To force all nodes to use the same process identity, you can generate a validation key to support view state validation and manually configure each node to use it.

Generate a validation key. You can use the autogenerate functionality provided by the .NET Framework or you can create the key some other way. Do not use the AutoGenerate option when setting the validationKey attribute.
Generate a decryption key. For the decryption key, you can create an explicit value or set decryptionKey to AutoGenerate.
Open the Web.config file for each node in the Web farm and set the machineKey element. You must specify the validation key, decryption key, and the type of encryption used for validation of data.
Repeat these steps for each node in the Web farm or cluster deployment.

<httHandlers>

The ReportViewer Web server control includes an HTTP handler that is used to display images that are embedded or referenced in a report, export reports to different output formats, provide a calendar control used to select dates for a report parameter, and keep a report session open.

Configuration settings for the HTTP handler are specified in the httpHandlers element of your application Web.config file. The configuration settings are entered into the Web.config file automatically when you drag the ReportViewer Web server control from the Toolbox onto your Web page.

You cannot remove or modify the HTTP handler configuration settings. If you modify or delete the <httpHandlers> settings in Web.config, the ReportViewer Web server control will throw the following error when you view the .aspx page: "The ReportViewer Web control HTTP Handler has not been registered in the application Web.config file". The error message includes the configuration information that the HTTP handler requires; you can copy these settings verbatim into the Web.config file. The string will be similar to the following example (note that version information and PublicKeyToken will be different):

<httpHandlers>
   <add path="Reserved.ReportViewerWebControl.axd" verb="*" 
   type="Microsoft.Reporting.WebForms.HttpHandler, 
   Microsoft.ReportViewer.WebForms, Version=8.0.0.0, 
   Culture=neutral, PublicKeyToken=0000000000000000" validate="false" 
   />
</httpHandlers>

The HTTP handler is part of the control; it cannot be removed or replaced with custom functionality that you provide.

Share via