The IPostBackDataHandler Interface

The postback mechanism is one of the pillars of ASP.NET. When a request arrives, the ASP.NET runtime matches the ID of each posted value with a server-side control. For each match found, the ASP.NET runtime invokes a couple of methods on the matching server control. The methods invoked come from a a well-known interface—the IPostBackDataHandler interface.

By implementing the IPostBackDataHandler interface each server control gets a chance to update its current state with data posted by the client. The interface lists two methods—LoadPostData and RaisePostDataChangedEvent.

The ASP.NET runtime invokes LoadPostData on each control to give the control a chance to update its current state with the data coming from the client. Here's the method's signature:

public bool LoadPostData(
    string postDataKey, 
    NameValueCollection postCollection);

The first argument of LoadPostData is the client ID of the control; the second argument is a name-value collection that contains all the data posted from the client. Note that when the ASP.NET runtime gets to process a request, it first copies the posted data from either Request.Form or Request.QueryString into a helper collection. This helper collection is then passed to LoadPostData.

Each control locates the entry in the collection whose key matches the ID of the control. The value associated with the entry, if any, is used to update the value of one or more control properties. For example, input text boxes compare the posted value to the Value properties; check boxes, instead, compare it to the Checked property. The posted value is obtained using the postDataKey parameter as a key to access the values stored in the collection.

Controls that implement the IPostBackDataHandler interface use a boilerplate piece of code to implement the LoadPostData method. Basically, the method updates the key property of the control with the posted value. The code below shows how LoadPostData works for the HtmlInputText control.

bool LoadPostData(string postDataKey, NameValueCollection postColl) 
{
   string oldValue, postedValue;

   // Cache the current value of the property 
   oldValue = this.Value;

	// Get the posted value for the HTML element with the 
   // same ID as the control		
   postedValue = postColl[postDataKey];

   // Compare the posted value with Value and updates if needed
   if (oldValue != postedValue) 
   {
	   this.Value = postedValue;
      return true;
   }
     
	// Indicates whether the state has changed
   return false;
}

LoadPostData is expected to return true if the state of the control changed to incorporate the posted values. For this infrastructure to work, it is key that a one-to-one correspondence exists between the ID of server controls and one client HTML element. The ASP.NET runtime tracks all the controls that return true to LoadPostData and then invokes the RaisePostDataChangedEvent method for each of them—the second method on the IPostBackDataHandler interface. The following code snippet reports what that method does for the HtmlInputText control:

void RaisePostDataChangedEvent() 
{
    this.OnServerChange(EventArgs.Empty);
}

The page that hosts the HtmlInputText control receives a ServerChange control for each hosted instance. A similar behavior is provided by all server controls that implement the IPostBackDataHandler interface. The name of the event may change, however.

Dino Esposito is Wintellect's ADO.NET and XML expert, and a trainer and consultant based in Rome, Italy. Dino is a contributing editor to Windows Developer Network and MSDN Magazine, and the author of several books for Microsoft Press including Building Web Solutions with ASP.NET and ADO.NET and Applied XML Programming for .NET. Contact Dino at [email protected].