Chapter 13: An Example Web Service Client

Transcription

1 page 1 Chapter 13: An Example Web Service Client In this chapter, we are going to build a client web application that uses a free web service called Terraserver. Terraserver is a site run by Microsoft and the United States Geographical Service to supply mapping and aerial photo imagery of the USA. From our perspective, Terraserver has the advantage of being free to the user - not suprisingly, a lot of web service owners are trying to make money from their intellectual property so it can be difficult to find examples of actual services that can be used freely in examples without a lot of trouble. You can find the Terraserver example in various forms in various places on the internet and elsewhere: for example in Jeff Prosise's text Programming Microsoft.NET (which I believe is the original source), \ Microsoft's web site and the Terraserver web site among others. I'm not linking to them because several of the versions you can find use.net 1.1 and Terraserver version 1, both of which are now out of date and will not work. (We are using the current version - version 2.) This used to be an impressive example - until Google Earth... However, it is still quite good - especially considering that there is very little code. You can download the code using the links below - note that because they were copied straight from Visual Studio, you may need to edit them a bit to get them to work! Note: At the time of writing (early March 2010) TerraServer had changed the name of it's webservice to MSRMaps. The old name is currently working, in that you can link to and compile applications as described below CityView.aspx CityView.aspx.cs Class.ashx Terraserver You can find Terraserver at The actual site provides much more than just the web service, but is the starting point for us, and links to extensive documentation - both on the methods supported and the data structures used. To get a list of the methods supported, you can also go to And of course you can view the WSDL file by adding `?wsdl' to the end, which - if you are prepared to read it - will also tell you about the methods and data structures. Much easier to read the documentation though Basic Terraserver Concepts Terraserver deals with image tiles which are 200 pixel square chunks. To construct a map, or image, you normally need to retrieve more than one tile and assemble them. The basic method for retrieving tile data is GetTile - however, before you call this you need to work out which tile, or tiles you need. This could involve a number of steps, depending on the type of application - in our case, the following is necessary. Convert Place Data to Lat Lon Data. Our web application will require users to select a place, the state it is in, and a scale. We must first call ConvertPlaceToLonLatPt to get the latitute and longitude of the point. Of course, we may have entered a place that does not exist. ConvertPlaceToLonLatPt needs a Place data structure as a parameter, which we construct from the place and state information. There is quite an extensive database of places and their locations - certainly all the 'common' ones you try should work (though be aware of spelling issues). Get the Bounding Box. We will now have a LatLonPt structure, telling where the place is - but we need to get data for an area, not a point - and the size of the area depends on the scale. Calling GetAreaFromPt will return an AreaBoundingBox object. Iteratively Get Tiles. Finally, we need to actually retrieve the data we need by repeatedly calling GetTile. This needs a pair of nested loops to get the tiles in two dimensions The Web Form You can see the inteface in Fig 1.

2 page 2 Fig.1. The Terraserver Client Window The actual code for this is below, with non-helpful stuff omitted. <form id="form1" runat="server"> <table cellpadding="8" style="width: 785px; HEIGHT: 237px"> <tr> <td>place </td> <td><asp:textbox id="place" runat="server" Width="296px"></ asp:textbox></td> <td>state</td> <td> <asp:dropdownlist id="state" runat="server" Width="153px"> <asp:listitem Text="AL"/> <asp:listitem Text="AK" /> <asp:listitem Text="AR"/>... <asp:listitem Text="WV"/> <asp:listitem Text="WY"/> </asp:dropdownlist></td> <td>theme</td> <td> <asp:dropdownlist ID="ThemeList" runat="server" Width="96px"> <asp:listitem Text="Photo"/> <asp:listitem Text="Topo"/> <asp:listitem Text="Relief"/> </asp:dropdownlist></td>

3 page 3 </tr> <tr> <td><asp:requiredfieldvalidator id="requiredfieldvalidator1" runat="server" ForeColor="red" Display="static" ErrorMessage="*" ControlToValidate="Place" Width="152px"></ asp:requiredfieldvalidator></td> <td> <fieldset><legend>scale</legend><asp:radiobuttonlist id="scalebuttons" runat="server" RepeatDirection="Horizontal" RepeatColumns="2"> <asp:listitem Text="1 meter"/> <asp:listitem Text="2 meters"/> <asp:listitem Text="4 meters"/> <asp:listitem Text="8 meters" Selected="true"/> <asp:listitem Text="16 meters"/> <asp:listitem Text="32 meters"/> </asp:radiobuttonlist></fieldset> </td> <td></td> </tr> <tr> <td></td> <td><asp:button id="button1" runat="server" Width="100%" Text="Show Image" onclick="button1_click"></asp:button></td> <td></td> </tr> </table> </form> <asp:image id="myimage" RunAt="server"></asp:image> </body> </html> There are only really a couple of things of interest here that we have not seen. The first is the required field validator to ensure the place field is not empty. The second is that the image: <asp:image id="myimage" RunAt="server"></asp:image> Does not apparently contain any data. That is because our application is going to programmatically supply this later. The rest of it should be pretty obvious - a couple of dropdown lists (one for the state, another for the type of data - most of which I've deleted because it's very long) and one for the theme (you can retrieve topographic and relief images as well as just photos); a set of radio buttons (for scale); and a textbox for the placename The Code At the top of the code file you will find a load of using statements: using System; using System.Configuration; using System.Data; using System.Linq; using System.Web; using System.Web.Security; using System.Web.UI; using System.Web.UI.HtmlControls; using System.Web.UI.WebControls; using System.Web.UI.WebControls.WebParts; using System.Xml.Linq;

4 page 4 using System.Collections; using System.ComponentModel; using System.Drawing; using System.Web.SessionState; using System.Drawing.Imaging; using System.IO; using com.terraserverusa.www; Most of these are obviously to do with web controls and graphics - but using com.terraserverusa is the web service namespace. We'll talk about this later. As usual, the business logic for this application is in a separate file - and this is what is called when you click the button on the form: protected void Button1_Click(object sender, EventArgs e) string place = Place.Text; string state = State.SelectedItem.Text; int theme; switch (ThemeList.SelectedIndex) default: case 0: theme = 1; case 1: theme = 1; case 2: theme = 3; ProcessImageRequest(place, state, ScaleButtons.SelectedIndex, theme); MyImage.ImageUrl = "Class1.ashx"; Data is read from the form elements, manipulated as necessary, and then we call ProcessImageRequest which is going to do the work - the last line: MyImage.ImageUrl = "Class1.ashx"; looks a bit wierd though. Class1.ashx is a HTTP Handler that will generate HTTP formatted data, and which is something we haven't seen yet. In this case we are using it to wrap the image data to be displayed in HTTP, and telling the (initially empty) image to source its data from their. We will get back to this later. public void ProcessImageRequest(string place, string state, int scale, int theme) if (place!= null && state!= null) // Determine the scale Scale res = Scale.Scale8m; switch (scale) case 0: res = Scale.Scale1m;

5 page 5 case 1: res = Scale.Scale2m; // Rest deleted 600); // Generate the requested image ImageFormat format = ImageFormat.Jpeg; Bitmap bitmap = GetTiledImage(place, state, theme, res, 900, // If GetTiledImage failed, generate an error bitmap if (bitmap == null) bitmap = GetErrorImage(); //type = "image/gif"; format = ImageFormat.Gif;//Might not be needed // Write the image to the HTTP response bitmap.save("c:\\temp\\testimage.jpg"); // Clean up and return bitmap.dispose(); ProcessImageRequest creates a bitmap image by calling a further method GetTiledImage. It is possible that the image construction failed (for example, if you entered a place that does not exist, or the service is down). In that case, we return an image containing the text `Error'. (You can download that here.) Finally, we save the image in a temporary file as a JPEG and get rid of the bitmap object. Most of the work is done in GetTiledImage, which looks bad (though you don't need to worry about the details): scale, Bitmap GetTiledImage(string City, string State, int theme, Scale int cx, int cy) Bitmap bitmap = null; Graphics g = null; try // Instantiate the TerraService proxy TerraService ts = new TerraService(); // Get the latitude and longitude of the requested place Place place = new Place(); place.city = City; place.state = State; place.country = "USA"; LonLatPt point = ts.convertplacetolonlatpt(place);

6 page 6 // Compute the parameters for a bounding box AreaBoundingBox abb = ts.getareafrompt(point, theme, scale, cx, cy); // Create an image to fit the bounding box bitmap = new Bitmap(cx, cy, PixelFormat.Format32bppRgb); g = Graphics.FromImage(bitmap); int x1 = abb.northwest.tilemeta.id.x; int y1 = abb.northwest.tilemeta.id.y; int x2 = abb.northeast.tilemeta.id.x; int y2 = abb.southwest.tilemeta.id.y; for (int x = x1; x <= x2; x++) for (int y = y1; y >= y2; y--) TileId tid = abb.northwest.tilemeta.id; tid.x = x; tid.y = y; System.Drawing.Image tile = System.Drawing.Image.FromStream (new MemoryStream(ts.GetTile(tid))); g.drawimage(tile, (x - x1) * tile.width - (int)abb.northwest.offset.xoffset, (y1 - y) * tile.height - (int)abb.northwest.offset.yoffset, tile.width, tile.height); tile.dispose(); // Return the image return bitmap; catch (Exception) if (bitmap!= null) bitmap.dispose(); return null; finally if (g!= null) g.dispose(); This method: instantiates the web service proxy; converts the place data to latitude-longitude data; gets the bounding box of the map or photo we want; and then fetches all the necessary tiles, assembling them into a bitmap, using a pair of nested loops. The precise details are not particularly important to us here - we're more interested in the actual web service infrastructure. The only remaining method returns the error image file, which we will omit The HTTP Handler

7 page 7 At this point we have saved the image data in a file but we have not managed to put in on the page. There are a few ways to do this and we are going to use an HTTP Handler. HTTP Handlers generated HTTP formatted data, so they can be used in pages where you might put, say, an image URL dynamically - which is what we want in this case. HTTP Handlers are definable in a couple of ways - one is to register them by editing the web.config file. The other, which we will use, is to create a.ashx file with a line like this: <%@ WebHandler Language="C#" Class="Handler" %> using System; using System.Drawing; using System.Drawing.Imaging; using System.Web; using System.IO; public class Handler : IHttpHandler public void ProcessRequest (HttpContext context) Bitmap bitmap = new Bitmap("C:\\Temp\\testImage.jpg"); context.response.contenttype = "image/jpeg"; ImageFormat format = ImageFormat.Jpeg; bitmap.save(context.response.outputstream, format); bitmap.dispose(); public bool IsReusable get return false; HTTP Handlers must implement the IHttpHander interface, which has two members: ProcessRequest and IsReusable. IsReusable is a property that controls whether another request could use the same handler - in our case it is yes though it does not in practice here make any difference (it will still work with false). ProcessRequest actually generates the output, and will be called when the web browser viewing the page requests the image. The image is read from the file. Then we set the mime type of the HTTP response to `image/jpeg', create a format object to tell Bitmap's save method how to save the data, and send it all via an OutputStream to the requesting browser. We've linked the (initially empty) image where the result is going to appear to the HTTP Handler - so the handler basically 'inserts' the appropriate image data onto the web page Adding the Web Reference Unlike our previous examples, we need to direct our application to a web service running on a remote host. To do this, when we add the web reference by actually entering the URL of the service. In this case: or the new name Once you've done this, Visual Studio will helpfully tell you that the namespace you need to use is: com.terraserverusa or, if using the new name com.msrmaps The actual name is mirrored by the folder structure in the Web References directory of the web site project that Visual Studio uses. So if you forget, you can navigate to this directory (either in Visual Studio or just in the file system) and you should find a folder called com and within that a folder called terraserverusa which

8 contains the actual WSDL file. From this folder structure, you can infer the namespace you need to use in your code. page 8