Page Methods is a new mechanism in ASP.Net application where the server code cab be bound to Asp.Net pages.  It is an easy way to communicate asynchronously with the server using Asp.Net Ajax technologies. It’s an alternate way to call the page which is reliable and low risk.  In a nutshell, it is used to expose the web methods to the client script. 

To enable Page methods we need to drag a ScriptManager control to the page and mark  

the EnablePageMethods to “True”.

<asp:ScriptManager ID="ScriptManager1" runat="server"   
      EnablePageMethods="True">
</asp:ScriptManager>

Go the Code behind file of the page and add a static method and mark them as WebMethod. Lets Say the method name is GetPageMethod which returns a status value

[System.Web.Services.WebMethod]        
public static string GetPageMethod()
{
      return "Welcome PageMethods";
}

Now that the method is exposed add a button control and call a client script which accesses the Webmethods of the page

<asp:Button ID="Button1" runat="server" Text="Call Page Methods"  
      OnClientClick="return fun()"/>

In javascript function we can use PageMethods object to call the WebMethod of the page.

function fun()
{     
      PageMethods.GetStatus(onSucceed, onError);
      return false;
}   
function onSucceed(result)
{
      alert(result);        
}
function onError(result)
{      
}

Now run the application and check the result which shows the alert box with value “Active”. The sample application calls the webmethods of the page using client script without full page cycle.

Let’s say if the page method has two input parameters we can pass paramters as given in the below sample:

      PageMethods.GetStatus(“p1”,”p1”,onSucceed, onError);

We can also access the Session , Application and Cache variables data using the Page Methods. For example:

  protected void Page_Load(object sender, EventArgs e)
{      
      HttpContext.Current.Session["key"] = "SomeValue";
      HttpContext.Current.Application["key1"] = "SomeValue1";
}

Accessing the session data in the page methods:

[System.Web.Services.WebMethod]        
public static string GetStatus(string s1, string s2)
{
      return (string)HttpContext.Current.Session["key"];         
} 

We can also return the application and cache data in the similar way.

return (string)HttpContext.Current.Application["key1"];         
return (string)HttpContext.Current.Cache["key"];         

Script Manager and Page Methods

The ScriptManager renders the java script to access the web methods when the EnabledPageMethods is set to “True”.  An JavaScript object Page Methods is created using which we can access the web methods of the page.    

In order to call web methods using PageMethods object we should add a function for Successful Page method call and a function for UnSuccessful Page method call as seen in our sample above. These functions can be treated as Callback functions.

We can also pass parameters to the page method along with references to call backs  separated by “,”.

We can pass n number of parameters to the page methods from the client script which are required for processing and getting the result.

The syntax for calling the page methods using PageMethods object and passing parameters:

      PageMethods.Somemethod(p1,p1,p3,onSucceed,onError); 

Internally the script manager builds the PageUrl and XmlHttpRequest and then post the request to the server to fetch the required result. Ultimately its all the XmlHttpRequest stuff that is wrapped up for easy usage.

We can pass parameters to Page methods and then the call back methods. We can pass the references to the four call back methods to call when the page method returns. The four call back methods are

·         onSucceed

·         onError

As we discussed we need to have callback function for success page method call and for unsuccessful page method call. Unsuccessful page method call means if there is an   internal server error on the page.

Using the call back method we can fetch the required result from the page and use it on the client script as required.

//CallBack method when the page call succeeds
function onSucceed(results, currentContext, methodName)
{
      alert(results);
}
 
//CallBack method when the page call fails due to interna, server error
function onError(results, currentContext, methodName)
{
      alert(results);
}

The method names and parameter names are user defined.  We can use any name for the callback methods and their parameters.

The OnSucceed parameter indicates the javascript function to be called when the call has succeeded and the result parameter has the result stored in it in our case the string returned from the code behind file.
The OnError parameter indicates the javascript function to be called when error occurs. The success call back method has three parameters:

·         Result – Returns the output of the page method.

·         currentContext – This is used to handle different logic when single callback is used for multiple page method requests. We can also pass array of values as userContext parameter.

·         methodName – This parameter returns the name of  page method called.

 The error call back method has three parameters:

·         Result – Returns the output of the page method.

·         currentContext – This is used to handle different logic when single callback is used for multiple page method requests. We can also pass array of values as userContext parameter.

·         methodName – This parameter returns the name of  page method called.

The result here return the type of the error, stacktrace, message and type of the exceptions. You can display the required information to the end user using the following   methods of error object

get_exceptionType()
get_mesage()
get_stackTrace()
get_statusCode()
get_timedOut()
 
function onError(result)
{
      alert(result.get_message());
}             

Sending the userContext parameter

var contextArray = "u1";     
PageMethods.GetStatus("p1","p2",onSucceed, onError,contextArray);  

And this can be used on the call back to execute different logic

function onSucceed(result,userContext,methodname)
{ 
      if (userContext = “u1”)
      {
            alert(result);
      }
}

Advantages

·         This approach is easier and the code is shorter and reliable.

·         It provides greater compatibility since it is easy to change fast.

·         Less work for developer to write client script and a server method.

·         Page parameters become strongly typed and automatically validated.

·         You don't have to parse and convert parameters by yourself. In ASP.NET, parameters passed on URLs are available through Request.QueryString, only as strings.

·         No need to look at a target page's code to know how to call it. No need for separate documentation about ways to call a page.

·         Page parameters are automatically validated and become strongly typed.

·         As we don’t to post entire viewstate of the page using Page Methods we achieve the bandwidth benefits.

Key Points to Remember

·         The Page Method should be static using the attribute [WebMethod].

·         The Page Method can be in the code behind file of the page and in aspx file as well.

·         The EnablePageMethods property of the script manger should be marked as “True”.

·         The call back methods are mandatory to receive the processed result on the client side.

·         Page Methods don’t support all the datatypes to return to client.

·         We can access the Session. Application and Cache variables using Page Methods.

References

http://randomactsofcoding.blogspot.com/2007/10/introduction-to-pagemethods.html

http://metasapiens.com/PageMethods/features.aspx

http://blogs.msdn.com/sburke/archive/2006/10/21/hint-components-that-use-web-services-with-asp-net-ajax-v1-0-beta.aspx

http://www.singingeels.com/Articles/Using_Page_Methods_in_ASPNET_AJAX.aspx

http://blogs.msdn.com/mattgi/archive/2006/11/15/accessing-session-data-from-javascript.aspx