When it comes to lightweight client-side communication, I’ve noticed that many of you prefer ASP.NET AJAX’s page methods to full ASMX web services. In fact, page methods came up in the very first comment on my article about using jQuery to consume ASMX web services.

Given their popularity, I’d like to give them their due attention. As a result of Justin‘s question in those comments, I discovered that you can call page methods via jQuery. In fact, it turns out that you can even do it without involving the ScriptManager at all.

In this post, I will clarify exactly what is and isn’t necessary in order to use page methods. Then, I’ll show you how to use jQuery to call a page method without using the ScriptManager.


Creating a page method for testing purposes.

Writing a page method is easy. They must be declared as static, and they must be decorated with the [WebMethod] attribute. Beyond that, ASP.NET AJAX takes care of the rest on the server side.

This will be our page method for the example:

public partial class _Default : Page 
{
  [WebMethod]
  public static string GetDate()
  {
    return DateTime.Now.ToString();
  }
}

What about the ScriptManager and EnablePageMethods?

Traditionally, one of your first steps when utilizing page methods is to set the ScriptManager’s EnablePageMethods property to true.

Luckily, that property is a bit of a misnomer. It doesn’t enable page methods at all, but simply generates an inline JavaScript proxy for all of the appropriate methods in your page’s code-behind.

For example, if a ScriptManager is added to the above example’s corresponding Default.aspx and its EnablePageMethods property is set to true, this JavaScript will be injected into the page:

var PageMethods = function() {
 PageMethods.initializeBase(this);
 this._timeout = 0;
 this._userContext = null;
 this._succeeded = null;
 this._failed = null;
}
 
PageMethods.prototype = {
_get_path:function() {
 var p = this.get_path();
 if (p) return p;
 else return PageMethods._staticInstance.get_path();},
GetDate:function(succeededCallback, failedCallback, userContext) {
return this._invoke(this._get_path(), 'GetDate',false,{},
  succeededCallback,failedCallback,userContext); }}
PageMethods.registerClass('PageMethods',Sys.Net.WebServiceProxy);
PageMethods._staticInstance = new PageMethods();
 
// Generic initialization code omitted for brevity.
 
PageMethods.set_path("/jQuery-Page-Method/Default.aspx");
PageMethods.GetDate = function(onSuccess,onFailed,userContext) {
 PageMethods._staticInstance.GetDate(onSuccess,onFailed,userContext);
}

Don’t worry if you don’t understand this code. You don’t need to understand how it works. Just understand that this JavaScript proxy is what allows you to call page methods via the PageMethods.MethodName syntax.

The important takeaway here is that the PageMethods proxy object boils down to a fancy wrapper for a regular ASP.NET service call.

Calling the page method with jQuery instead.

Knowing that a page method is consumed in the same way as a web service, consuming it with jQuery isn’t difficult. For more detailed information, see my previous article about making jQuery work with ASP.NET AJAX’s JSON serialized web services.

Using the jQuery.ajax method, this is all there is to it:

$.ajax({
  type: "POST",
  url: "PageName.aspx/MethodName",
  data: "{}",
  contentType: "application/json; charset=utf-8",
  dataType: "json",
  success: function(msg) {
    // Do something interesting here.
  }
});

Putting it all together.

Corresponding to the example page method above, here’s our Default.aspx:

<html>
<head>
  <title>Calling a page method with jQuery</title>
  <script type="text/javascript" src="jquery-1.2.6.min.js"></script>
  <script type="text/javascript" src="Default.js"></script>
</head>
<body>
  <div id="Result">Click here for the time.</div>
</body>
</html>

As you can see, there’s no ScriptManager required, much less EnablePageMethods.

As referenced in Default.aspx, this is Default.js:

$(document).ready(function() {
  // Add the page method call as an onclick handler for the div.
  $("#Result").click(function() {
    $.ajax({
      type: "POST",
      url: "Default.aspx/GetDate",
      data: "{}",
      contentType: "application/json; charset=utf-8",
      dataType: "json",
      success: function(msg) {
        // Replace the div's content with the page method's return.
        $("#Result").text(msg.d);
      }
    });
  });
});

The end result is that when our result div is clicked, jQuery makes an AJAX call to the GetDate page method and replaces the div’s text with its result.

If you’re wondering about the msg.d, be sure to see my post about what it is, why it’s there, and why you may not need it in your version of ASP.NET: A breaking change between versions of ASP.NET AJAX

Conclusion

Page methods are much more openly accessible than it may seem at first. The relative unimportance of EnablePageMethods is a nice surprise.

To demonstrate the mechanism with minimal complications, this example has purposely been a minimal one. If you’d like to see a real-world example, take a look at Moses’ great example of using this technique to implement a master-detail drill down in a GridView.

If you’re already using the ScriptManager for other purposes, there’s no harm in using its JavaScript proxy to call your page methods. However, if you aren’t using a ScriptManager or have already included jQuery on your page, I think it makes sense to use the more efficient jQuery method.

Get the source

If you’d like to browse through a complete working example of what’s been covered in this post, take a look at the companion project at GitHub. Or, if you’d like to download the entire project and run it in Visual Studio to see it in action yourself, grab the ZIP archive.

jQuery-Page-Method on GitHubjQuery-Page-Method.zip