Working with PageRequestManager Events

10/22/2014

17 minutes to read

In this article

The PageRequestManager class in the Microsoft AJAX Library coordinates with the ScriptManager and UpdatePanel server controls on an AJAX-enabled ASP.NET Web page to enable partial-page updating. The PageRequestManager class exposes methods, properties, and events to make client programming easier when page elements are performing asynchronous postbacks. For example, the PageRequestManager class enables you to handle events in the client page life cycle and to provide custom event handlers that are specific to partial-page updates.

To use the PageRequestManager class in client script, you must put a ScriptManager server control on the Web page. The EnablePartialRendering property of the ScriptManager control must be set to true (which is the default). When EnablePartialRendering is set to true, the client-script library that contains the PageRequestManager class is available in the page.

Getting an Instance of the PageRequestManager Class

There is one PageRequestManager instance per page. You do not create an instance of the class. Instead, you get a reference to the current instance by calling the getInstance method, as shown in the following example:

When you have the current instance of the PageRequestManager class, you can access all its methods, properties, and events. For example, you can get the isInAsyncPostBack property to determine whether an asynchronous postback is in progress, as shown in the following example:

If the EnablePartialRendering property of the ScriptManager control is false, you cannot access the isInAsyncPostBack property because there is no PageRequestManager instance.

Client Page Life-cycle Events

During ordinary page processing in the browser, the window.onload DOM event is raised when the page first loads. Similarly, the window.onunload DOM event is raised when the page is refreshed or when the user moves away from the page.

However, these events are not raised during asynchronous postbacks. To help you manage these types of events for asynchronous postbacks, the PageRequestManager class exposes a set of events. These resemble window.load and other DOM events, but they also occur during asynchronous postbacks. For each asynchronous postback, all page events in the PageRequestManager class are raised and any attached event handlers are called.

You can write client script to handle events raised by the PageRequestManager class. Different event argument objects are passed to handlers for different events. The following table summarizes the PageRequestManager class events and the corresponding event argument classes. The order of the events in the table is the order of the events for a single asynchronous postback without errors.

initializeRequest
Raised before the request is initialized for an asynchronous postback. Event data is passed to handlers as an InitializeRequestEventArgs object. The object makes available the element that caused the postback and the underlying request object.

beginRequest
Raised just before the asynchronous postback is sent to the server. Event data is passed to handlers as a BeginRequestEventArgs object. The object makes available the element that caused the postback and the underlying request object.

pageLoading
Raised after the response to the most recent asynchronous postback has been received but before any updates to the page have been made. Event data is passed to handlers as a PageLoadingEventArgs object. The object makes available information about what panels will be deleted and updated as a result of the most recent asynchronous postback.

pageLoaded
Raised after page regions are updated after the most recent postback. Event data is passed to handlers as a PageLoadedEventArgs object. The object makes available information about what panels were created or updated. For synchronous postbacks, panels can only be created, but for asynchronous postbacks, panels can be both created and updated.

endRequest
Raised when request processing is finished. Event data is passed to handlers as an EndRequestEventArgs object. The object makes available information about errors that have occurred and whether the error was handled. It also makes available the response object.

If you use the RegisterDataItem method of the ScriptManager control to send extra data during an asynchronous postback, you can access that data from the PageLoadingEventArgs, PageLoadedEventArgs, and EndRequestEventArgs objects.

The sequence of events varies with different scenarios. The order in the previous table is for a single, successful asynchronous postback. Other scenarios include the following:

Multiple postbacks where the most recent postback takes precedence, which is the default behavior. Only events for the most recent asynchronous postback are raised.

Multiple postbacks where one postback is given precedence, which cancels all subsequent postbacks until it is finished. Only the initializeRequest event is raised for canceled postbacks.

An asynchronous postback that is stopped. Depending on when the postback is stopped, some events might not be raised.

An initial request (HTTP GET) of a page, or a page refresh. When a page is first loaded or when it is refreshed in the browser, only the pageLoaded event is raised.

Stopping and Canceling Asynchronous Postbacks

Two common tasks are to stop an asynchronous postback that is underway and to cancel a new request before it has begun. To perform these tasks, you do the following:

To stop an existing asynchronous postback, you call the abortPostback method of the PageRequestManager class.

To cancel a new asynchronous postback, you handle the initializeRequest event of the PageRequestManager class and set the cancel property to true.

Stopping an Asynchronous PostBack

The following example shows how to stop an asynchronous postback. The initializeRequest event handler script checks whether the user has chosen to stop the postback. If so, the code calls the abortPostback method.

Canceling New Asynchronous Postbacks

The following example shows how to give precedence to a specific asynchronous postback. This cancels all subsequent asynchronous postbacks until the current one finishes. (By default, the most recent asynchronous postback takes precedence.) The initializeRequest event handler checks whether the asynchronous postback was initiated by an element on the page that has precedence. If it was, all subsequent postbacks are canceled by setting the cancel property of the InitializeRequestEventArgs object. The InitializeRequestEventArgs event inherits from the CancelEventArgs class, where the cancel property is defined.

Displaying a Custom Error Message

The following example shows how to display a custom error message when an error occurs during an asynchronous postback. The AsyncPostBackError event of the ScriptManager control is handled in server code, and information about the error is sent to the browser to be displayed.

Animating Panels

The following example shows how to animate an UpdatePanel control to notify the user that the content has changed. When you click the LinkButton controls, a border around the UpdatePanel control is shown briefly.