Telerik blogs

My team and I have been working hard to bring you the cool web services functionality that shipped with r.a.d.ajax in Q3 a week ago. And now, when the goodies are out in the open, people are beginning to explore the new features and looking for suitable ways to use them. I have been reading some of the initial support tickets we received about the web services support in r.a.d.ajax and it seems that quite a few people would appreciate some guidance with this somewhat advanced feature of the product. This blog post is meant to get you guys started.

Scared of JavaScript? Scare no more! If you don’t want to write a single line of code ever you can use the already excellent RadAjaxManager and RadAjaxPanel controls that ship since v1.0 of the framework.

But what about getting rid of that viewstate on every AJAX request even if you only need to populate a simple table of data? What if you want the fastest performance possible in delivering data with asynchronous calls? Feeling a little adventurous or skilled enough to take on some JavaScript action? Read on, my friend, you are in for some really cool stuff.

Ingredients:

1 RadAjaxServiceManager control, 1 Web Service, Basic JavaScript knowledge and 5 minutes of your time.

How to cook:

Place the RadAjaxServiceManager on your form, click “Configure” and simply type the relative path the web service in your application. I am assuming you already have one created.

Now, let’s switch to the “Source” view of your aspx file. We can see that the designer has generated the following markup for you:

<rada:RadAjaxServiceManager ID="RadAjaxServiceManager1" runat="server">    
    <WebServices>       
        <rada:WebServiceReference Path="~/MyService.asmx" />   
    </WebServices>
</rada:RadAjaxServiceManager>

Since all the action happens on the client you will need to write up some nominal amount of code to call the web service.

<script type="text/javascript">               
function CallService(param1)   
{       
    MyService.MyMethod(param1, ServiceCompleteCallback, ServiceErrorCallback);               
};
function ServiceCompleteCallback(ResponseObject, ResponseAsXml, ResponseAsText)   
{       
    //handle the response…   
};
function ServiceErrorCallback(args)   
{       
    alert("Error occurred:" + args.ErrorText);   
};   

</script>

Now let’s take this code apart. The first method receives user parameters and calls the web service instance we have generated on the client. But wait! How did that get in there? Well, through the magic of reflection, we have enumerated all web methods of our web service and have generated a client JavaScript proxy object which has all the proxy methods for the service. The naming convention we used is straightforward:

<WebServiceName>.<WebMethodName>([user parameters…], ServiceCompleteCallback, ServiceErrorCallback);


So what are the two special parameters at the end? Since web services are called asynchronously we require callback functions (or handlers – it’s the same thing) to be called when the service call completes.

If everything goes ok and the service returns the needed information the ServiceCompleteCallback is called.

function ServiceCompleteCallback(ResponseObject, ResponseAsXml, ResponseAsText)    
{       
   //handle the service response   
};

The method receives three arguments. The first one is probably the most important for you. It is a (JSON) representation of the data returned by the web service. RadAjax now features an advanced client-side SOAP parser which deals with simple values, arrays, datasets, datatables even custom objects! Moreover, the parser successfully handles the ISO8601 date format used in the SOAP response and tries to parse primitive types as much as possible (sometimes using heuristics and guesswork).

 
The two other parameters are straightforward: ResponseAsXml returns an XML document object (IE Only) and the ResponseAsText provides you with the raw response from the server.

The other callback function ServiceErrorCallback is called whenever there is something wrong with your request (the service is down, a server-side exception is thrown etc.) We are providing this handler to facilitate error handling on the client. If you wish to display a debug error message you can use the the ErrorText of the args parameter.

function ServiceErrorCallback(args)
{    
    alert("Error occurred: " + args.ErrorText);
}

So far I have covered the most important tasks involved in using the RadAjaxServiceManager control. If you want to see some real life examples download the latest version of the r.a.d.ajax control and you can find them inside the quick start framework. One can also see them live in action here. If there is interest I may be posting some more advanced guidelines on how to utilize web services in your applications in the future.


About the Author

Vladimir Milev

Vladimir Milev is a developer manager.

Comments

Comments are disabled in preview mode.