If you’ve read things of mine, such as my Wrox Blox Hands On ASP.NET AJAX Control Toolkit, or posts on the ASP.NET Forums, you may have noticed I talk about using ASP.NET AJAX Page Methods lots of the time. Lots of developers using ASP.NET AJAX overuse the UpdatePanel, or use it in situations where it doesn’t make sense. One example of this that I explore in my book is the comparison between using an UpdatePanel for a cascading drop-down effect vs. using the ASP.NET AJAX Control Toolkit’s CascadingDropDown Control with Page Methods. In short, the CascadingDropDown was far more efficient. Most of the time the reasoning for choosing the UpdatePanel is that developers don’t “think” about the repercussions of the UpdatePanel, nor do they think about other approaches to the problems they’re trying to solve. One of my favorite posts on UpdatePanels that I constantly refer developers to is Dave Ward’s blog post titled “Why ASP.NET AJAX UpdatePanels Are Dangerous“. The post does a great job of discussing the point of UpdatePanel overuse and gives an example of using Page Methods for a task instead of the UpdatePanel. Since I still encounter developers who fall into the UpdatePanel trap, I figured it would be a good idea to discuss Page Methods a bit further.
What are ASP.NET AJAX Page Methods?
Simply put, a Page Method is a page specific WebMethod. Instead of creating a full web service for your method, you can conveniently create a method in your page and use it from client-script. Let’s look at how simple it is to use them:
- Add a ScriptManager to your page, this is needed for ASP.NET AJAX interactions of any type (UpdatePanel, AJAX Control Toolkit, etc).
- Set the EnablePageMethods property of the ScriptManager equal to true.
- In the server-side code for the Page, create a static (Shared in VB) method and decorate it with the WebMethod attribute. (Note the WebMethodAttribute is located in the namespace System.Web.Services)
- Use the server-side method from client-side code by simply making a call to PageMethods.YourMethodName;
- Process the server callback. Remember AJAX is asynchronous, so in step 4, we make the request and we need to pass it the callback function in order to process the result. In some cases, you may not need this step, but typically you always are requesting something from the server.
That’s it. Now lets put this together in a small example.
ASPX Code (Steps 1, 2, 4, and 5)
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="BasicExample.aspx.cs" Inherits="VisoftInc.Samples.BasicExample" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Visoft, Inc :: Samples :: Using PageMethods :: Basic Example</title>
</head>
<body>
<script language="javascript" type="text/javascript">
// Step 4: Use the PageMethod from code
function getServerGreeting() {
$get("MessagePlaceholder").innerHTML =
"<img alt=\"Please Wait\" src=\"image\\ajaxwait01.gif\" />";
// NOTE: Instead of using getElementById in the last
// statement, ASP.AJAX has a shortcut to this method
// that does the same thing, $get.
// Call the server method
PageMethods.GetGreeting(getServerGreeting_Success);
}
// Step 5: Process the callback
function getServerGreeting_Success(result) {
/// <summary>
/// This is the callback method to handle the
/// result from the server.
/// </summary>
/// <param name="result">The result from the server</param>
$get("MessagePlaceholder").innerHTML = result;
}
</script>
<form id="form1" runat="server">
<div style="text-align:center; width:200px;">
<!-- Step 1: Add a ScriptManager to the page -->
<!-- Step 2: Set the EnablePageMethods property to true -->
<asp:scriptmanager id="sm" runat="server" enablepagemethods="true" />
<input type="button" value="Get Message" onclick="getServerGreeting()" style="width:100px;" />
<div id="MessagePlaceholder"></div>
</div>
</form>
</body>
</html>
Code-Behind (Step 3)
using System.Threading;
using System.Web.Services;
namespace VisoftInc.Samples
{
public partial class BasicExample : System.Web.UI.Page
{
/// <summary>
/// Simple method which returns a string greeting
/// </summary>
/// <returns>string</returns>
[WebMethod]
public static string GetGreeting()
{
// Step 3: Create a static method and decorate it with
// the WebMethod attribute
// In order to slow the method down a bit to illustrate
// the async call, have the method wait 2 seconds.
Thread.Sleep(2000);
// Return the result
return "Hello PageMethods";
}
}
}
The previous code sample shows all the steps put together. Like all good beginning examples, this one follows the “Hello World” model. You can see where each step is completed by looking at the inline comments. This is the demo you saw in the section above (repeated here off to the right, so you don’t need to scroll back up). In order to make things look a little nicer, I added an AJAX wait image like you see in most AJAX applications while it is waiting to get data from the server. You can get your own customized animations at ajaxload.info. In the example above, the page structure is extremely simple, just a button and a DIV. When the button is clicked, the JavaScript method calls out to the server’s Page Method and passes the reference to the callback function. In this particular case, we are only handling a success callback. Later we’ll look at handling other events like an error, plus we will see how to pass parameters to the server method. In the success callback, the message returned is added to the DIV.
A Look Under The Hood
All of the Page Method magic happens thanks to ASP.NET AJAX. If you view the rendered source from the BasicExample from above, you’ll see the Page Methods JavaScript code.
Here’s a snapshot from Firebug:
I won’t list the full source, since it’s available in any page where PageMethods are enabled. This is similar to the proxy that is created when you add a web service and expose it to client script.
Page Method Parameters
Back in the first example, the only event that was captured was the success callback. How would you pass parameters required by the server method? In addition, what other events can be captured in client-script? The Page Method is just like a web service call from the client-side’s perspective, because of this it follows the web service pattern. The following parameters can be used when calling a Page Method:
13 Comments
Alex -
Have a look at this article: http://dotnetslackers.com/columns/ajax/AspNetAjaxExceptionLogging.aspx. But in your case, if you are just using a Page Method, you can handle the error server side in the Page Method itself. Just wrap your logic in a try-catch and do your logging in the catch. However, for things like timeouts and such, I think you will need to do something along the lines of the article.
Hope this helps,
-Damien
Great article. I was looking for a way of trapping a server side error when calling a pageMethod and that’s what you have nicely shown. One question though – If I don’t specify the errorCallback function and I get a server side error, the pageMethod (by default) shows an alert with the error message on the client. I want to be able to get hold of the error message text (on the client-side would be fine, but server side would be even better), so I can record it to the database and have some insight into what is going wrong; as it stands, only the user of the page sees the error and unless thety report it to me, I won’t know it’s happening. Maybe the result object has a ‘-errorMsg’ property, just like it does for ‘_timedOut’. Thanks in advance!
Robert -
You can do a lot with a string. A "simple string" can be anything from a JSON object or even XML if you want. Serialization is your friend…
-Damien
I’ve never seen an example of using page methods that returns more than a simple string value.
Pankaj-
If you want to access a server control (as a server control), the only way to do this is to use an UpdatePanel…
-Damien
Hi,
I want to know whether there is any way by which i can access a server control in my AjaxMethod. i’ve searched a lot but havn’t found any thing.
Hi Damien,
My problem seem to have been caused by another callback within an update panel.
What I meant was that within a specific page, I pulled in the Prototype.js reference. This same page also contained a ScriptManager and had it’s EnablePageMethods attribute set to true. Whenever I tried to call a WebMethod within a specific function it would not fire my desired method.
Eric
Really useful for me
Eric-
Not sure what you mean by [quote]what if you already have a prototype reference on your page[/quote]. Can you elaborate? What is the error that you are getting?
-Damien
Hi Damien,
Neatly put together, awesome.
I quick question, hopefully you might have an answer for me. The PageMethods inject a prototype class into to the output stream, which is all good but what if you already have a prototype reference on your page, let’s say you use prototype for something else and now you wish to inject a PageMethod call when an HTML control is clicked on? I’m getting an error thrown in my JScript method, removing prototype reference causes the function to fire off as desired.
Any ideas?
Eric
Hi ,
One of the Pretty useful blogs,I hav gone through.
Keep doing.
Mahir,
In terms of the controls in the AJAX Control Toolkit, an easy solution for implementing the services is to use Page Methods. This usually makes a lot of sense since the controls are often Page related. I’ve used them countless times, but haven’t really had an issue with them needing to be static. Remember, you can create objects inside the static method, all that you are really limited from is accessing the controls server-side. That doesn’t mean that you can’t change things client-side :). Then again, I love JavaScript…
-Damien
I created an autocomplete control with pagemethods, which is very good in performance due to pagemethod. But the only thing I face is Static.
Mahir