Introduction

In the second part of this series, you saw how to create client Controls and Extenders using the Microsoft Ajax Library and the ASP.NET AJAX server framework. Now, you will learn how to make asynchronous calls to the server in order to process data without reloading a web page.

The Web uses a stateless protocol (HTTP) to exchange data. As a consequence, a user interacts with a web page through multiple request-response transactions. Typically, an action performed by the user (such as submitting a form, or clicking a hyperlink) results in the browser requesting a web page from the server. Therefore, the state of a web application is reloaded at each request. At the same time, the user interface is rendered from scratch.

AJAX (Asynchronous JavaScript and XML) is born when a technique was invented to make the request-response interaction happen in the background - hence the term Asynchronous - without reloading the state of the web application and its whole user interface. This is possible with a JavaScript object called XmlHttpRequest, which was introduced in Internet Explorer 5 and then gradually embedded in all the modern browsers.

In this article, you are going to leverage the ASP.NET AJAX framework in order to make asynchronous calls in a straightforward and transparent way, without directly touching the XmlHttpRequest infrastructure.

Asynchronous calls to Web Services

The Microsoft Ajax Library provides a set of JavaScript objects that let you perform asynchronous calls at a higher level than interacting directly with the XmlHttpRequest object.

The first thing you are going to do is invoke a Web Service asynchronously in order to retrieve some data to display in the Virtual Earth map that you created in the previous parts of this series. Specifically, the data will be displayed as pushpins on the map.

One of the interesting things that you can do with this technique is exchange data by serializing and deserializing server types. This means that, if you declare a Pushpin class on the server side and return an instance through a Web Service, you will be able to access a Pushpin object with the same data in JavaScript, on the client side.

To see how it's done, let's start by creating a Pushpin class on the server side, in the App_Code folder of the website. This is shown in the following listing.

Listing 1: The Pushpin class on the server side

As you can see, this is just a plain old .NET class that holds the relevant data for a Virtual Earth pushpin. More interesting is the declaration of the Web Service that you are going to use to exchange data asynchronously.

Listing 2: The Web Service that will be called asynchronously

Actually, it requires a little effort to perform a basic configuration of a Web Service for ASP.NET AJAX. This is the step-by-step procedure, which you can verify against the previous code snippet:

• Declare the Web Service class and decorate the web methods with the WebMethod attribute, as usual.
• Decorate the class with the ScriptService attribute. This attribute is defined in the System.Web.Script.Services namespace.

The final thing to do is let the ScriptManager control know that we are going to call a Web Service from the client side. This is done by adding a Services section inside the ScriptManager tag. This section holds a ServiceReference tag, which provides the path to the Web Service.

Listing 3: Referencing the Web Service through the ScriptManager

At this point, the Web Service is ready to be called from the client side. Let's demonstrate how it's done by adding the following script block inside the form tag of the web page:

The above code snippet reveals how simple the syntax used to invoke the Web Service from the client side is. In fact, we can invoke a web method by calling a method exposed by a JavaScript object with the same name of the Web Service.

Behind the Scenes

What happens is that ASP.NET AJAX generates a proxy of the Web Service. The proxy is just a JavaScript object with the same name of the Web Service. Its methods have the same names as the web methods. By calling the proxy, you are actually making an asynchronous call to the Web Service. Finally, the result of the call is returned back to the server, and can be processed in a callback method. This is the function that we passed to the PushpinService.GetPushpins method of the proxy. The other function is a callback that gets invoked in case something goes wrong.

If you want to take a look at the proxy's generated code, you can either

• Append /PushpinService.asmx/js to the URL of the ASP.NET page and browse it. A call is made to an ASP.NET Handler - called ScriptResourceHandler - that returns the code for the proxy, which is displayed on screen.
• Set the InlineScript attribute of the ServiceReference tag to true. This instructs the ScriptManager to render the code inline in the page's HTML.

Another interesting thing happens whenever we invoke a web method. If the web method returns instances of types defined on the server side, these instances are serialized and turned into JavaScript objects. This means that we can access Pushpin objects on the client side. Furthermore, we can also create instances of Pushpin objects in JavaScript and pass them to web methods. As result, these client instances are turned into server side instances.

Getting Pushpins from the server

After that quick peek at how Web Services calls work in ASP.NET AJAX, let's modify the Mashup.VirtualEarth client Control in order to display a group of pushpins retrieved through the Web Service you created previously.

For this purpose, you have to add some methods that take the Pushpin instances on the client side and turn them into Virtual Earth pushpins. These methods are shown in the following listing.

The previous code works in a simple manner. The client calls the set_data method, passing an array of objects that contain data for the pushpins to display. The properties of these objects are the same exposed by the Pushpin class on the server side. It follows that you have to modify the JavaScript code in the script block (that we used to test the Web Service call) in order to call the set_data method, passing the Pushpin[] array returned by the web method. This is demonstrated in the following code.

Listing 4: Retrieving pushpins from the server side

The $find method used in the previous code is rather interesting. It lets you get a reference to a client component instantiated using the $create method. You can use $find to access the client VirtualEarth Control, since it was instantiated with a call to $create by the VirtualEarth Extender.

The $find approach allows accessing JavaScript objects without declaring any global variables at all.

Figure 1 shows the mashup up and running.

Figure 1: The Virtual Earth mashup

Summary

The essence of AJAX is the possibility to make requests to the web server asynchronously, without being forced to reload the whole page each time the state of the page changes. The Microsoft Ajax Library provides a framework that takes care of doing most of the job required to interact with the XMLHttpRequest object. As a result, making asynchronous calls to the server and processing the results is easy and straightforward.

In this article we explained how to call ASP.NET Web Services from the client side. You learned how to configure a Web Service for ASP.NET AJAX and how to invoke the client proxy in order to make the asynchronous call.

In the next part of this series, we will dive deeper in the networking layer of ASP.NET AJAX.

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.

---

Discussion

Subject	Author	Date
Issue with adding eventhandlers to the map	Michael Norman	6/25/2009 11:28 PM
I'm not sure if this topic is still being watched, but I am having some issues adding a click event using your wrapper.  I can get the click event to register, and even run, but what I need is to get at the map instance to run GetShapesbyID, so I can alert (or do something else) with the pin that was clicked on. So far I have added the event handler inside the OnLoadComplete function like so: function onLoadComplete() { //this._instance.SetCenter(new VELatLong(this._initialLatitude, this._initialLongitude)); //this._instance.SetZoomLevel(this._initialZoomLevel); this._instance.SetCenterAndZoom(new VELatLong(this._initialLatitude, this._initialLongitude), this._initialZoomLevel); this._instance.HideDashboard(); this._instance.AttachEvent("onclick", this.ShapeInfo); } And then have declared a ShapeInfo function like so: ShapeInfo: function(e) { if (e.elementID != null) { alert(this._instance().GetShapebyID(e.elementID)); } }, But I always get this._instance is null when the event fires.  Any ideas? Reply | Permanent link
RE: Issue with adding eventhandlers to the map	Michael Norman	6/25/2009 11:32 PM
That's a typo above, the line should be alert(this._instance.GetShapesbyID(e.elementID));. Reply | Permanent link
Error: 'null' is null or not an object	Mike Frizzell	6/27/2009 2:17 PM
I'm getting the error in the subject during the $find call. Any ideas? I'm fairly new at this AJAX deal, so feel free to throw a manual at me. Reply | Permanent link
RE: Error: 'null' is null or not an object	Mike Frizzell	6/27/2009 3:01 PM
Further digging, find is returning null... Reply | Permanent link
RE: Error: 'null' is null or not an object	Sonu Kapoor	6/27/2009 2:41 PM
check the variable name that you are using in the $find. [MVP since 2005] [MCAD] Webmaster of DotNetSlackers Question or Suggestion? Feel free to ask my any .NET question Our Posting FAQ Reply | Permanent link
RE: RE: Error: 'null' is null or not an object	Mike Frizzell	6/27/2009 3:02 PM
var myMapObj = $find("TheMap"); <cc:VirtualEarthExtender runat="server" TargetControlID="TheMap"           InitialLatitude="48.8569" InitialLongitude="2.34122" ZoomLevel="10" /> Are these the two values (targetcontrolid) that should match up? Reply | Permanent link
RE: RE: Error: 'null' is null or not an object	Mike Frizzell	6/27/2009 3:09 PM
<asp:ScriptManager runat="server">          <Services>              <asp:ServiceReference Path="PushpinService.asmx" />          </Services>      </asp:ScriptManager>         <asp:Panel ID="TheMap" runat="server" />         <cc:VirtualEarthExtender runat="server" TargetControlID="TheMap"           InitialLatitude="48.8569" InitialLongitude="2.34122" ZoomLevel="10" />                <script type="text/javascript">          function pageLoad() {              // Invoke the GetPushpins method of the PushpinService Web Service.                PushpinService.GetPushpins(onGetComplete, onGetFailed);              // This function is called when the web method returns.              function onGetComplete() {                  alert("Call suceeded!");                  var myMapObj = $find("TheMap");                  alert("find returned!");                  alert(myMapObj);                  myMapObj.set_data(result);              }              function onGetFailed() {                  alert("Call failed!");              }          }       </script> Reply | Permanent link
RE: RE: RE: Error: 'null' is null or not an object	Mike Frizzell	6/27/2009 3:33 PM
Two changes to make it work, the first is my mistake (I forgot the "result" in the function definition below: function onGetComplete(result) { The second change, SharePoint evidently changes IDs on you: $find("ctl00_PlaceHolderMain_TheMap") Found my ID by looking at the source... Reply | Permanent link
RE: RE: RE: RE: Error: 'null' is null or not an object	Sonu Kapoor	6/27/2009 3:41 PM
Ah... Great to see that you got this working. [MVP since 2005] [MCAD] Webmaster of DotNetSlackers Question or Suggestion? Feel free to ask my any .NET question Our Posting FAQ Reply | Permanent link
RE: Error: 'null' is null or not an object	Mike Frizzell	6/27/2009 3:04 PM
Btw, I had to remove the <form> tag, as it complained of only allow one form to be "runat=server." I'm in a SharePoint world at the moment. Reply | Permanent link
How to add markers using data retrieved from a database query	Julio M	11/10/2009 2:31 PM
Hi, great article - ta very much! I haven't figured out how I can add markers to a map using data retrieved from a query. I've added a new WebMethod to the PushpinService.cs class as below: [WebMethod]         public App_Code.Pushpin AddPushpin(double latitude, double longitude, string name)         {             return new App_Code.Pushpin(latitude, longitude, name, "", "");         } and a corresponding method to the PushpinService.asmx file as below: [WebMethod] public Pushpin AddPushpin(double latitude, double longitude, string name) { return new Pushpin(latitude, longitude, name, String.Empty, String.Empty); } and I'm trying to add a marker by iterating over a datareader, pulling the coordinates and name from it as below: Dim latitude As Double Dim longitude As Double Dim name As String Dim pps As PushpinService = New PushpinService() While (tr.Read) name = CType(tr.Item(1), String) latitude = CType(tr.Item(10), Double) longitude = CType(tr.Item(11), Double) i += 1 pps.AddPushpin(latitude, longitude, name) End While But the Markers aren't showing up on the map, am I missing something out? Thanks Julio Reply | Permanent link
problem	Rav W	3/12/2008 6:56 PM
When i download the code and ran it in Visul Studio I cant see the push pins in the application is something missing in the code Reply | Permanent link
RE: problem	Alessandro Gallo	3/15/2008 11:53 AM
Hi, you're right, the code for the project that runs under .NET 2.0 is incomplete. I'll make sure it gets fixed as soon as possible. Thanks. Reply | Permanent link
RE: RE: problem	Sonu Kapoor	3/15/2008 6:35 PM
Thie code has been updated. [MVP since 2005] [MCAD] Webmaster of DotNetSlackers Question or Suggestion? Feel free to ask my any .NET question Our Posting FAQ Reply | Permanent link
RE: RE: RE: problem	Alessandro Gallo	3/15/2008 6:42 PM
Thanks Sonu. Reply | Permanent link
Problem with initial Latitude / Longitude	Walt Cygan	4/9/2008 9:29 AM
I set up a test with your sample code and everything went fine as long as the initial latitude and longitude were in Europe. When I changed the pushpins and the initial latitude and longitude to display St. Paul, Minnesota, the pushpins appeared in the right locations but the map was centered in South Dakota. After some additional testing, if the initial latitude is 51.5196 (London) and I set the initial longitude to -52.40 (off the coast of Canada), the map displayed correctly. When I changed the longitude to -52.44 or something farther west, the map displayed South Dakota (around 43.95 North, 98.59 West). Do you get the same results? Can you suggest anything that I could try? Thanks, Walt   Reply | Permanent link
RE: Problem with initial Latitude / Longitude	Alessandro Gallo	5/2/2008 5:52 AM
Hello, I'm not sure of what's happening there. One issue that I'm aware of is when you use different cultures on the server and on the client side. Depending on how the current culture parses floats, you could end up with a decimal point being replaced by a comma, and this could screw up the coordinates. Reply | Permanent link
RE: Problem with initial Latitude / Longitude	Walt Cygan	4/9/2008 9:59 AM
By the way, this was with VS2008. Reply | Permanent link
RE: Problem with initial Latitude / Longitude	Lynn Demarest	3/28/2009 10:17 PM
If you use SetCenterAndZoom, the centerpoint works. Apparently using them separately is a no no. Reply | Permanent link
3D Broken?	James Swansburg	4/11/2008 11:49 PM
Hi, switch to 3D mode and a smaller 3D map appears inside the original 2D map, about 1/2 the size. James Reply | Permanent link
RE: 3D Broken?	Gary Nicol	4/16/2008 4:36 AM
I think this is related to the order the various initialisation events fire, and how these affect the loading of the map. A quick workaround is to set the CSS positioning of the map panel to be relative, e.g. <asp:Panel ID="TheMap" runat="server" style="position:relative;" /> Gary Reply | Permanent link
Great Article	Michael Liscio	4/16/2008 1:46 PM
Great Article.  This is exactly what I needed to know Thank You :) Reply | Permanent link
How can I do the coding for MouseUp, MouseDown events in the code	Anshu Bhatia	4/22/2008 2:26 PM
It is a great article. Question, I was trying to write the code for drawing free polygons in the Map but got stuck. Any ideas as to how it can be done with this architecture Thanks Reply | Permanent link
RE: How can I do the coding for MouseUp, MouseDown events in the code	Alessandro Gallo	5/2/2008 5:56 AM
The architecture simply consists of a wrapper around the VEMap control. The role of the wrapper is to allow the setup of the client map using a server control. You could expose an innerMap property in the Mashup.VirtualEarth component. This property returns the VEMap instance encapsulated by the control. In this way, you can program against the map without doing any more wrapping. The Virtual Earth API enables you to draw polygons. Please check the Virtual Earth SDK for an API reference. Reply | Permanent link

---

Please login to rate or to leave a comment.