Understanding ASP.NET AJAX Web Service Proxies

Proxy code plays an important role in sending and receiving messages to and from Web Services.  If you've worked with Web Services before in .NET, Java or other programming frameworks then chances are you used a client-side proxy to call a Web Service.  With .NET, proxies are generated using wsdl.exe or Visual Studio's Add Web Reference menu option.  ASP.NET AJAX proxies aren't created this way, however.  In fact, they're even easier to create compared to C# or VB.NET Web Service proxies. An ASP.NET AJAX Web Service proxy is created by using the Services property of the ScriptManager control:

<asp:ScriptManager ID="ScriptManager1" runat="server">
  <Services>
    <asp:ServiceReference Path="~/CustomersService.asmx" />
  </Services>
</asp:ScriptManager>

This code causes the ScriptManager to dynamically generate a proxy for the CustomersService.asmx service when the page loads and embed a reference to the proxy script in the page using the standard HTML <script> tag.  Here's an example of what the proxy script reference looks like once it is embedded in a page:

<script src="CustomersService.asmx/js" type="text/javascript"></script>

In cases where a client-side proxy isn't shared across multiple pages and you don't need to leverage browser caching, you can force the entire proxy script to be embedded directly in the page by using the ServiceReference control's InlineScript property:

 <asp:ScriptManager ID="ScriptManager1" runat="server">
  <Services>
    <asp:ServiceReference Path="~/CustomersService.asmx" InlineScript="true" />
  </Services>
</asp:ScriptManager>

This can be useful when you'd like to see what code is being generated for the proxy or when you'd like to minimize the number of network calls being made to the server.  You can also view the JavaScript proxy code that is generated by typing the path to the .NET Web Service in the browser and adding "/js" on the end.  For example:  http://localhost/WebService.asmx/js

To call a .NET Web Service from an ASP.NET AJAX page using the supplied proxy script the Web Service has to have the ScriptService attribute applied to it.  This attribute acts as a marker which "AJAX enables" the Web Service and allows JSON (JavaScript Object Notation) objects to be sent instead of SOAP messages.  JSON is a compact messaging format based upon JavaScript syntax that is integrated into the ASP.NET AJAX framework.  An example of using the ScriptService attribute is shown next:

namespace InterfaceTraining {
    [System.Web.Script.Services.ScriptService]
    [WebService(Namespace = "http://xmlforasp.net")]
    [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
    public class CustomersService : System.Web.Services.WebService {

        [WebMethod]
        public Customer[] GetCustomersByCountry(string country)
        {
            return Biz.BAL.GetCustomersByCountry(country);
        }
    }
}

Calling a Web Service using an ASP.NET AJAX client-side proxy is quite straightforward.  For example, to call the GetCustomersByCountry() Web Method shown above you would reference the service's namespace, the class name and finally the Web Method name.  The example that follows calls the GetCustomersByCountry() Web Method using the JavaScript proxy and passes a country as a parameter along with a callback function.  The callback function processes the result returned by the Web Service.

function GetCustomerByCountry() {
    var country = $get("txtCountry").value;
    InterfaceTraining.CustomersService.GetCustomersByCountry(country, OnWSRequestComplete);
}

function OnWSRequestComplete(results) {
    var searchResults = $get("searchResults"); 
    searchResults.control.set_data(results);
}

While Web Services aren't required when you need to access data asynchronously in an ASP.NET AJAX page (afterall, you can use the UpdatePanel control in many cases), they can be very useful when data in a page needs to be updated in a database or when data needs to be dynamically injected into a page.  Using Web Services can also minimize the size of the request and response messages when compared to the size of equivalent UpdatePanel messages since only data is sent with Web Service calls. HTML mark-up is handled by the client-side and normally not sent in the request/response JSON Web Service messages thus keeping the messages smaller overall.  This doesn't mean that you shouldn't use the ASP.NET AJAX UpdatePanel control.  It'll save you a ton of time compared to going the Web Service route.  However, there will be times when you don't necessarily need an UpdatePanel to accomplish the goals of a given page or application.

If you're interested in learning more about ASP.NET AJAX check out Microsoft's site at http://ajax.asp.net/.  I've also published a few videos on the topic as well:

 

comments powered by Disqus

3 Comments

  • You can find a video that demonstrates this on my blog:

    http://weblogs.asp.net/dwahlin/archive/2006/12/01/video-calling-web-services-using-asp-net-ajax-and-javascript.aspx

  • Are there special requirements for accessing the web service cross-domain?

    Reason I ask... I have success implementing the web service and calling it from the client WHEN both are on localhost. BUT, I have not achieved success in trying to do the same when trying to access the web service from a different client (and vice versa).

  • ASP.NET AJAX calls to a Web Service can&#39;t be made cross-domain due to security. &nbsp;So, while you can certainly call the service from a page within the same domain as the Web Service (as it sounds like you&#39;ve done), you won&#39;t be able to leverage the ASP.NET AJAX framework to do a cross-domain call.&nbsp; This is due to how the XmlHttp object works.

Comments have been disabled for this content.