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)
Code-Behind (Step 3)
A Look Under The Hood
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:
Completion Callback -A client-side method that will be called when the Page Method returns successfully. You saw this used back in the first example.
Error Callback - A client-side method that will be called if the Page Method errors. The error callback will also be called if the Page Method timed out.
Context - An object that will be passed to the callbacks.
Before these three parameters, you would include any parameters needed for your server-side method as you’ll see in the next example.
To show the example of parameters in use, we’ll start with the server-side code, two static methods. One that errors and one that waits so that we can see a timeout. These simple methods will take a “command” from the client, just to illustrate passing a value to the server from client-side code.
Not too much going on there that needs explanation, now on to the client-side code…
The code here looks similar to the first example, but notice the change in the parameters being passed. Note, in this example there isn’t any indication to the user that the server is processing since we are just looking at the parameters. First, you’ll notice that we are passing our “command” to the server, which is simply a string value. Next, we use the completion callback, then the error callback, and finally, for the context, we will just use the method name. In the error callback, you can see that we are testing the result for whether it is a timeout or not, and displaying a different message based on the error type.
You can see there are two test methods, testTimeout and testError. These call the server side Page Methods, ProcessCommandTimeout and ProcessCommandError, respectively. To illustrate the error, I’m just throwing an exception server-side. For the timeout, I’m setting the timeout to only one second so that you can see the timeout. You can set the timeout for a Page Method by using PageMethods.set_timeout(milliseconds); which you can see in line 4 in the client-side code above.
Things to Note
As you can see, Page Methods are easy to use. There are many situations where they make much more sense than the UpdatePanel. Of course you could always use Web or WCF service, but both of these are overkill for certain page-level tasks. There are some things to note when using Page Methods.
- Page Methods MUST Be static (Shared in VB.NET) - For those of you who aren’t familiar with static methods, this basically means that the method is completely self-contained and cannot access things in the class. For example, this means you won’t be able to access server controls from inside a Page Method. This is where people start to tune out. Hang in there for a minute. Just because you can’t access the control server-side does not mean that you can’t manipulate it. For example, let’s say you are getting data from the server (say a database) and you need to fill in an ASP.NET TextBox. You won’t be able to set the Text property of the TextBox, but on the client-side you would be able to set the value property of the DOM INPUT element.
- Page Methods CAN access Session - Accessing Session with a Page Method is simple, just access it using the HttpContent, for example HttpContext.Current.Session[“myKey”]. I was disappointed to find out that Page Methods always have Session enabled unlike a typical WebMethod.
- Page Methods are specific to the page - if you need the functionality in multiple places, a Web or WCF service would be a better option.
I really like Page Methods, but again, for certain tasks. If your two choices for doing an asynchronous task are the UpdatePanel or a Page Method, you should always opt for the lighter-weight approach and choose the Page Method approach. Don’t get me wrong, I appreciate the Microsoft providing us with the UpdatePanel, but with simplicity comes inefficiency. I hope that developers add this approach to their toolkits, and next time they think of some design where there are have multiple UpdatePanels on the page, or they are performing a task like an Ad Rotator with an UpdatePanel and a Timer, that they will think, “hey, an UpdatePanel for this is silly.”
Looking for the source code for this article? [Get it here!]
Looking for more Page Method stuff? Here’s some links to check out:
- Why do ASP.NET AJAX page methods have to be static?
- Using jQuery to directly call ASP.NET AJAX page methods
- How to… move from AjaxPro to ASP.NET AJAX PageMethods
- Why ASP.NET AJAX UpdatePanels Are Dangerous
- Ajax Page Methods Will Always Have Session
- Are you making these 3 common ASP.NET AJAX mistakes?