Report Application Server .NET SDK Developer Guide

Session and persistence of the ReportClientDocument (RAS) and the ReportDocument object models

What is Session?

Session is a Web server-based approach used in both ASP and ASP.NET for preserving state. Session allows you to persist any object for the entire length of a user's session by storing that object in the Web server's memory.

Session is typically used to do either of these things:

Store information that needs to persist its state during the entire length of a user session, such as logon or other information required as users navigate the Web application.
Store an object that needs to persist its state only across a page reload or a functionally grouped set of pages.

The strength of Session is that it preserves the user's state information on the Web server for access at any time from any page. Since the browser doesn't have to store any of this information, any browser can be used, even browser devices such as PDAs or cell phones.

Limitations of this persistence approach

The amount of server memory required by Session grows as more users log on.
Each user who accesses the Web application generates a separate Session object. Each Session object lasts for the length of the user's visit plus an inactivity period.
If many objects are persisted into each Session, and many users are using the Web application simultaneously (creating many Sessions), the amount of server memory devoted to Session persistence can become significant, limiting scalability.

Persisting the ReportClientDocument or the ReportDocument object model with Session

If the report has been encapsulated within the ReportClientDocument or the ReportDocument object model, the object model must be persisted using a server-based approach such as Session.

To persist a report within the ReportClientDocument or ReportDocument object model using Session, instantiate the ReportClientDocument or ReportDocument, and then assign it to Session.

Session is the simplest approach and is preferred when you are building an ASP.NET Web application using RAS. It is also the recommended approach for storing ReportClientDocument or ReportDocument instances where the report has low shareability (that is, they are not used as shared resources with other objects).

Contrasting Session and ViewState

Session is primarily concerned with persisting the state of objects in the code-behind class. ViewState is primarily concerned with persisting the state of controls on the Web page. When a control on the Web page is bound to an object in the code-behind class and both need to be persisted across page reloads, Session and ViewState share the roles of persistence.

In this case, ViewState persists a CrystalReportViewer control, and Session persists a ReportClientDocument or a ReportDocument object that is bound to the control.

Future considerations: using a Session state server in a Web farm or Web garden environment

A small number of users may eventually port their .NET Framework application to a Web farm (a collection of Web servers on separate CPUs providing the same Web application) or a Web garden (a collection of Web server instances on a single machine providing the same application). Some Web farms and Web gardens manage all Sessions from multiple Web servers by using a Session State server to hold all Sessions on a single centralized machine.

In this scenario, it becomes important that all objects in Session be serializable, because a Session State server serializes Session content to transfer and store Session content on the server.

Serializing the ReportClientDocument class

The ReportDocument class is serializable by default; however, the ReportClientDocument class is not. Therefore, when persisting changes to a report in the ReportClientDocument object model in a Web farm or Web garden that shares Session on a Session State server, you cannot use Session.