Web.config Settings for ReportViewer

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.

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.

In the .NET Framework 2.0 or later, 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.

1. 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.

2. Generate a decryption key. For the decryption key, you can create an explicit value or set decryptionKey to AutoGenerate.

3. 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.

4. 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 retrieve 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, keep a report session open, and support the client-side scripting functionality in the ReportViewer cotrol.

Configuration settings for the HTTP handlers are specified in the system.web/httpHandlers element and the system.webServer/handlers element. of your application Web.config file. The handler specified in system.web/httpHandler is used by Internet Information Services (IIS) 6.0 or IIS 7.0 in Classic mode, whereas the handler specified in system.webServer/handlers is used by IIS 7.0 in Integrated mode. 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 form. The HTTP handlers are part of the control; they cannot be removed or replaced.

You must keep the HTTP handler that applies to your IIS version in its respective section. If you remove or modify the HTTP handler configuration settings, the ReportViewer Web server control in your Web form will display an error message that tells you to add it back to the respective section in the web.config file. The HTTP handlers in both system.web/httpHandlers and system.webServer/handlers are duplicated below:

<system.web>
   <httpHandlers>
      <add path="Reserved.ReportViewerWebControl.axd" verb="*" 
      type="Microsoft.Reporting.WebForms.HttpHandler, 
      Microsoft.ReportViewer.WebForms, Version=10.0.0.0, 
      Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" validate="false" 
      />
   </httpHandlers>
</system.web>
<system.webServer>
   <handlers>
      <add name="ReportViewerWebControlHandler" 
      preCondition="integratedMode"
      verb="*" path="Reserved.ReportViewerWebControl.axd" 
      type="Microsoft.Reporting.WebForms.HttpHandler, 
      Microsoft.ReportViewer.WebForms, Version=10.0.0.0, 
      Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" 
      />
</handlers>
</system.webServer>

See Also

Reference

httpHandlers Element (ASP.NET Settings Schema)

Concepts

Adding and Configuring the ReportViewer Controls

Deploying Reports and ReportViewer Controls

Other Resources

handler