How to work with client callbacks in an ASP.NET Web application

In this topic

• About working with client callbacks in an ASP.NET Web application
• Implementing client callbacks
• Callback events

The source code for this walkthrough is included in the SampleCallback.aspx page in the sample Common_Callback.

About working with client callbacks in an ASP.NET Web application

1. Create the server-side code to be invoked by the client.
2. Create the client-side code to invoke the callback request and process the response.

Implementing client callbacks

1. Implement the System.Web.UI.ICallbackEventHandler. The ICallbackEventHandler interface can be implemented on a page or a Web control. The interface contains two key methods: RaiseCallbackEvent(string EventArgs) and GetCallbackResult(). RaiseCallbackEvent() receives the message in the callback request sent from the client. It parses the message and determines what server-side logic will be executed. Once the server-side code is finished, it creates a string of values to be sent to the client using the GetCallbackResult() method.
   
   The following code is an implementation example of both methods—behind the Default.aspx.cs page. The eventArgument is updated via a callback request from the client.

public partial class Default: System.Web.UI.Page, System.Web.UI.ICallbackEventHandler
{
    string returnstring;
    string ICallbackEventHandler.GetCallbackResult()
    {
        return returnstring;
    }
    void ICallbackEventHandler.RaiseCallbackEvent(string eventArgument)
    {
        if (eventArgument == "getservertime")
        {
            returnstring = DateTime.Now.ToString();
        }
    }

2. Call the GetCallbackEventReference method on the Page class. The GetCallbackEventReference method creates a JavaScript string on the client Web page to start the callback. The usage and method parameters are as follows:
   

public string sCallBackFunctionInvocation;
protected void Page_Load(object sender, EventArgs e)
{
    sCallBackFunctionInvocation = Page.ClientScript.GetCallbackEventReference(this, 
        "message", "processMyResult", "context", "postMyError", true);
}

3. Create the client-side code to trigger the callback and process the response. Implementing System.Web.UI.ICallbackEventHandler and calling GetCallbackEventReference adds a line similar to the following script tag in your aspx page at runtime:

 < script src = 
     "/MyWebsite/WebResource.axd?d=TqQApA1CcEIyShhLjzTczw2&t=632657807109074470"
     type = "text/javascript" >  <  / script >

 < html >  < head >  < title > Untitled Page <  / title >  < script language = 
     "javascript" type = "text/javascript" > function getServerTime(){
    var message = 'getservertime';
    var context = 'Page1';
     <  %= sCallBackFunctionInvocation %  > 
}

function processMyResult(returnmessage, context){
    var timediv = document.getElementById('timelabel');
    timediv.innerHTML = returnmessage;
}

function postMyError(returnmessage, context){
    alert("Callback Error: " + returnmessage + ", " + context);
}

 <  / script >  <  / head >  < body >  < form id = "form1" runat = "server" >  <
     input type = "button" value = "Get Server Time" onclick = "getServerTime();" / 
     >  < div id = "timelabel" >  <  / div >  <  / form >  <  / body >  <  / html >

1. Add an HTML element and a JavaScript function to create a callback request. In the previous HTML code, the click event of an HTML button triggers a call to the getServerTime JavaScript function, which in turn calls WebForm_DoCallback. The message variable is set to getservertime, which is used by the server to determine the action to execute. The <%=sCallBackFunctionInvocation%> server variable is translated to WebForm_DoCallback('__Page', message, processMyResult, context, postMyError, true) at runtime.
2. Add two JavaScript functions to process the callback response and update the page. The processMyResult function takes the callback response string and updates the text content of a div tag in the HTML page. This occurs dynamically so other objects in the page are not redrawn. The postMyError function receives the callback message if an error occurs on the server. If an error occurs, an alert box appears.

Callback events

1. After the Web page loads, the onClick event of an HTML button is triggered, which calls the user-defined getServerTime JavaScript function.
2. The getServerTime function sets the message and context variables to be sent to the server and calls the ASP.NET 2.0 defined WebForm_DoCallback function to create and send the callback request.
3. A new XMLHttpRequest object is created to send and receive the asynchronous call to and from the server.
4. The XMLHttpRequest object posts the HTTP request to the server containing the message. On the server, the RaiseCallbackEvent method parses the argument (message) and executes business logic—in this case, it converts the time on the server to a string. The GetCallbackResult method passes this string back to the XMLHttpRequest object waiting on the client.
5. The ASP.NET 2.0 WebResource for callbacks directs the callback response string to the registered callback response function, the user-defined processMyResult function.
6. The processMyResult function uses the content of the callback response string to dynamically update HTML in the Web page. In this case, it inserts HTML into an existing <div> tag to display the server time.

See Also: