hile AJAX is the current rage for building interactive browser-based client applications, the action on the server side has focused on Web services. In fact, Web services have become the de-facto standard for exposing business functions at the server level. Given these conditions, a central development question becomes: How do you enable your AJAX-based applications to communicate with Web services? This article explores how you can use Microsoft Atlas (recently renamed to ASP.NET AJAX) to achieve just that.
To follow along, you’ll need Visual Studio 2005 and Microsoft Atlas downloaded and installed. If you don’t have Visual Studio 2005 installed, you can download a free Visual Studio Express version. This article explains how to interact with Web services through Atlas using an application I’ve called “ZipCodeRUs.” The ZipCodeRUs application retrieves detailed ZIP code information such as the names of cities, counties, and their latitude, longitude, area code, etc. for up to three ZIP codes entered by the user. It relies on a free and publicly available Web service at tilisoft.com to retrieve the information. The ZipCodeRUs application illustrates Atlas’s Web service prowess in two ways:
- It demonstrates Atlas’s JavaScript proxies asynchronously communicating with an ASP.NET (.asmx) Web service (which functions simply as a conduit to the external Tilisoft ZIP code Web service).
- It demonstrates Atlas’s capability to batch web service calls from JavaScript client to server
| Author’s Note: Microsoft Atlas also provides the ability to create XML-based declarative bridges to external Web services without having to create conduit services; however, this article does not cover this bridge feature. |
 |
? |
| Figure 1. Creating a New Atlas Web Application: When you install the Microsoft Atlas CTP, you’ll find a new project template called “‘Atlas’ Web Site” in the “New Web Site” dialog. |
The full downloadable code for the ZipCodeRUs application accompanies this article.
Getting Started with Atlas Web Services
In Microsoft Visual Studio, create a new Web application for ZipCodeRUs by selecting the “Atlas Web Site” template as shown in Figure 1. The “Atlas Web Site” template is installed when you download and install the Microsoft Atlas CTP. The “Atlas Web Site” template creates a Web site that includes a reference to the Microsoft.Web.Atlas.dll and a Web.config file that preconfigures the Web site for using Atlas.
If you need to add Atlas capabilities to an existing ASP.NET application you can find the procedure in this Atlas web site in the section titled “Adding Atlas features to an existing ASP.NET application.”
One problem with AJAX applications that rely on external Web services (services that aren’t provided at the same domain as the application itself) is that you can’t use JavaScript to access such Web services directly?browsers will prevent all such “cross-scripting” access. For security reasons, browsers allow JavaScript on a Web page to access only Web sites from the domain where the page originated. To solve this problem, the Atlas JavaScript client relies on .asmx files (ASP.NET Web services) to create runtime JavaScript proxies. In other words, the client calls a Web service exposed by the home domain, which in turn calls the external Web service, then simply passes the response back to the client.
Therefore, before you can call an external Web service from your Atlas client, you first need to create a strongly typed proxy. For this example, I’ve built a C# proxy for the ZipCode Web service and an ASP.NET Web service that serves as a conduit.
Create a Proxy Client Class
There are two ways of creating Web service client proxy classes. You can use wsdl.exe at the Visual Studio command prompt to create these proxy classes or you can create a Web reference from within the Visual Studio IDE. Here’s how to use wsdl.exe from your application’s App_Code folder to create strongly typed proxy classes for the ZipCode Web service. Note that the following code is a single line when typed at the command prompt.
C:projectsipCodeRUSApp_code> wsdl.exe http://www.tilisoft.com/ws/LocInfo/ZipCode.asmx?WSDL /namespace:Tilisoft.ZipCodeThe preceding command creates a ZipCode.cs file containing a TiliSoft.ZipCode proxy class that you can use in your local code.
Next, you need to create the conduit Web service. Right click the root item in Solution Explorer, select the “Add New Item?” option from the popup menu, and then select the Web service template. I’ve named the service “ZipCodeConduitService.”
The ZipCodeConduitService has a single function called GetZipCodeInfo that takes two string parameters: a string correlationID, and a ZIP code. When invoked, the service uses the generated proxy classes for TiliSoft Web service to retrieve results, pass them back to the ZipCodeConduitData application. To demonstrate Atlas’s exception-handling capabilities, I’ve added a twist: If the ZIP code entered by the user is “error’, GetZipCodeInfo() throws a ZipCodeConduitException. Here’s the code for ZipCodeConduitService Web service class:
... [WebService(Namespace = "http://tempuri.org/")] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] public class ZipCodeConduitService : System.Web.Services.WebService { ... [WebMethod] public ZipCodeConduitData GetZipCodeInfo(String corelationId, String zipCode) { if (zipCode.Equals("error")) { throw new ZipCodeConduitException(corelationId, "Here is an error just for you!! Enjoy!"); } ZipCode xZipCodeService = new ZipCode(); ZipCodeConduitData zipCodeConduitData = null; ZipCodeData xZipCodeData = xZipCodeService.GetInfo(zipCode); zipCodeConduitData = new ZipCodeConduitData(corelationId, zipCode, xZipCodeData); return zipCodeConduitData; } }In the preceding code, ZipCodeConduitData is a value object used to pass information between clients and the ZipCodeConduitService. The ZipCodeConduitData class has get properties as shown below. The CorelationId property lets clients track their requests.
... using Tilisoft.ZipCode; public class ZipCodeConduitData { public ZipCodeConduitData(String corelationId, ZipCodeData data) { hydrate(corelationId, data); } String _corelationId; public String CorelationId { get { return _corelationId; } } ... String _county; public String County { get { return _county; } } String _city; public String City { get { return _city; } } ... private void hydrate(String corelationId, ZipCodeData data) { _corelationId = corelationId; if (data.ZipCodeInfo.Count > 0) { _zipCode = data.ZipCodeInfo[0].ZIPCODE; _county = data.ZipCodeInfo[0].COUNTY; _city = data.ZipCodeInfo[0].CITY; ... } } }The ZipCodeConduitException is a C# exception class that extends System.Exception. The exception class includes the correlationId value that clients send with each request as shown in the code snippet below.
... using System;
public class ZipCodeConduitException : System.Exception { String _corelationId; public String CorelationId { get { return _corelationId; } set { _corelationId = value; } } public ZipCodeConduitException(String corelationId, String message):base(message) { _corelationId = corelationId; } }Building the ZipCode JavaScript Client
Now that the server-side Web service code is ready, you can create a JavaScript client that accesses the service. Add ZipCodeConduitClient.aspx by adding a Web form to your ZipCodeRUs using the “Add New Item?”, “Web Form” option
In the ZipCodeConduitClient.aspx code, enable Microsoft Atlas by creating a an instance of Atlas’s ScriptManager and adding a reference to the ASP.NET-based Web service ZipCodeConduitService.asmx file to the element of the Web page as shown in the code below.
... Zip Code Information Service - Atlas JavaScript Conduit Client ... |
? |
| Figure 2. ZipCodeConduitClient.aspx: The figure shows the ZipCodeConduitClient.aspx page in design mode in Visual Studio. |
Interestingly, the preceding code enables batched Web service requests between JavaScript and the Web service. Adding the webRequestManager element, with the enableBatching attribute value set to true causes Atlas to handle all the grunt work of accumulating all the requests and executing them at all at once in a batch. Atlas also keeps track of all the return values and objects from the Web service. The code above batches up to five requests (or waits for three seconds to accumulate additional requests?whichever occurs first) and then executes all the requests at once.
Now you can create visual elements of the web page by adding HTML and ASP elements along the lines a shown below to create a page that looks similar to the one shown in Figure 2.
... Enter ZipCodes: 1> 2> 3>
ZipCode ...
...Notice that the “Get Information” (named buttonZipCode in the source code) button is wired to invoke the OnbuttonZipCode_click() JavaScript function, which runs the code shown below.
In the OnbuttonZipCode_click function, the ZipCodeConduitService JavaScript proxy object is implicitly made available by Atlas because of the
You can see those functions in the code below. These functions receive a result parameter, which contains the response returned by the server. In this case, the ZipCodeConduitService returns an instance of the ZipCodeConduitData class to the OnComplete() function, and returns a ZipCodeConduitException exception to OnError().
... function OnComplete(result) { document.getElementById('message').innerHTML = "Ready"; if (result.CorelationId == '1') { document.getElementById('corelationId1').innerHTML = result.CorelationId; ... document.getElementById('message1').innerHTML = result.Message; } else if (result.CorelationId == '2') { ... } else if (result.CorelationId == '3') { ... } } function OnError(result) { displayMessage(result); } 
? Figure 3. ZipCodeConduitClient In Action: Here's the ZipCodeConduitClient.aspx page running in a Web browser showing the results retrieved for three ZIP codes.
function OnTimeout(result) { document.getElementById('message').innerHTML = "Request Timeout"; } function displayMessage(result) { if (result.CorelationId == '1') { document.getElementById('message1').innerHTML = result.get_message(); } ... } The Code in Action
With both the server and client code in place, you’re ready to enjoy the fruits of your labor. Start ZipCodeConduitClient.aspx in debug mode in Visual Studio or deploy your application to a Web site and enter three ZIP codes to retrieve details of all three ZIP codes at once as shown in Figure 3.
AJAX made developing responsive Web applications simpler, and now Microsoft has raised the ante by simplifying the process of calling Web services from AJAX-enabled client applications. As AJAX moves further into mainstream development, you can expect Microsoft to integrate Atlas even more closely into Visual Studio and other Microsoft development platform and products.
