Introduction

MS AJAX provides a networking layer whose purpose is to make easier to send asynchronous requests to the browser in order to add AJAX capabilities to a web page. The net layer abstracts and simplifies the details of the XmlHttpRequest object and provides a cross-browser programming interface.

Plus, if you are not a JavaScript addict, MS AJAX provides a declarative programming model (ala ASP.NET) that allows to program against the client framework without writing a single line of javascript code.

The example

In the following snippet we'll see how is possible to invoke a web service method asynchronously and processing the results using only declarative code.

For this purpose, we're going to create a simple web service, called MyWebService.asmx, that contains a method called Echo(), that simply returns back the string given as an argument. The following is the code to put in the MyWebService.asmx file:

Follows the code relative to an ASP.NET page in which we declare a TextBox and a Button. If the user types some text in the TextBox and then clicks the Button, the Echo() method will be invoked asynchronously and the returned string will be displayed in a MS AJAX Label control thanks to a binding between the Label and the web method result.

Code overview

The structure of the above ASP.NET reflects a key point in the MS AJAX philosophy: the client-side functionality is added by "upgrading" some static HTML elements to MS AJAX controls. In fact, the HTML textbox becomes an MS AJAX textBox while the HTML button becomes an MS AJAX button. The upgrade happens in the declarative xml-section that is used to specify the whole client-side functionality of the page.

There are some interesting concepts in the above declarative code. The first one is the code used for referencing the web service method. This is done with a serviceMethod element whose url and methodName properties specify the name of the web service file and the web method respectively (remember that the web service must be in the same domain as the application, since cross domain calls are not allowed in this context). Inside the serviceMethod node we find a completed element, that represents the completed event raised when the web service method returns. Under the completed element, we are going to declare a set of actions to handle the completed event. An action is a sort of built-in event handler; for example, the invokeMethod action allows to call a method exposed by a MS AJAX control, in response to a particular event.

In our case, we are using the invokeMethod action to explicitly evaluate the binding between the Label and the result property of the serviceMethod instance, as soon as the web method returns. In fact, the result property holds the value returned by the web service method. This binding is declared in the bindings section of the label element that upgrades the HTML span element to a MS AJAX Label control.

An example of a sequence of actions is given in the click node inside the button element. Here we handle the click event raised by the MS AJAX Button with two actions: the first one is a setProperty action that is responsible for setting the toEcho parameter to pass to the web service method with the text typed by the user in the textbox. It is important to notice that the parameters to pass to a method are specified by filling a parameters object with some properties, each one representing a particular parameter: the name of the property is the name of the parameter, while the property value is the value of the corresponding parameter. In the declarative code, we are using the property attribute to access the parameters object and the propertyKey attribute to set a property in the parameters object, while the value attribute is bound to the text typed by the user in the textbox. The result is that we are passing to the Echo() method a toEcho parameter whose value is the textbox's text. An important thing to remember is that the name of the parameters must be the same as the corresponding parameters in the web method declaration.

At this point, the method is invoked using an invokeMethod action, whose target attribute is the id given to the serviceMethod element while the method attribute is the name of the web method to call.

The last thing to point out is that, besides the completed event, a ServiceMethod instance raises other three events:

• timeout, is raised if the asynchronous request used to invoke the web service method timeouts.
• error, is raised if an error occurs during the processing of the asynchronous request.
• aborted, is raised if the asynchronous request used to invoke the web service method is aborted. The serviceMethod instance exposes an abort() method that can be invoked to abort the asynchronous request.

The above events can be handled in the same way as the completed event.

Conclusions

In this article we've seen how the combination of declarative code and the MS AJAX framework allows to invoke a web service method asynchronously without writing a single line of JavaScript. We talked also about some nice features of the client framework like declarative event handling, actions and bindings.

About Alessandro Gallo

Alessandro "Garbin" Gallo is a Microsoft MVP in the Visual ASP/ASP.NET category and a .NET developer/consultant. He is a contributor for the Ajax Control Toolkit project, owned by Microsoft. Alessandro won the Grand Prize at the "Mash-it-up with ASP.NET AJAX" contest held by Micr... This author has published 23 articles on DotNetSlackers. View other articles or the complete profile here.