This article contains references to a WSDL document and web service that is no longer available. This piece is offered AS IS for informational purposes. There are no plans to update the WSDL document or web service.

The XML Files

A Survey of Publicly Available Web Services at Microsoft

Aaron Skonnard

Code download available at:XMLFiles0312.exe(284 KB)

Contents

Microsoft.com Web Service 1.0
TerraService
MapPoint
.NET Alerts
The State of Web Services

Now that the dust has settled on the XML Web Services front, it seems like the right time to survey some of the mainstream Web Services available, with a focus on those offered by Microsoft. Microsoft offers several Web Services to the general public including the Microsoft.com Web Service, TerraService, MapPoint® Web Service, and .NET Alerts. Developers can use all of these services to introduce valuable functionality and content into their applications. This column will provide an overview of these Web Services along with instructions on how to get started with each one.

Microsoft.com Web Service 1.0

Microsoft.com Web Service 1.0 is the newest addition to the Microsoft repertoire of XML Web Services. This service makes it possible to programmatically obtain information about downloads available on the various Microsoft.com Web sites including MSDN®, TechNet, Microsoft Support, and others. Microsoft.com Web Service 1.0 allows developers to retrieve a summary of the most recent or most popular downloads, as well as complete details for any particular download.

This version of the service is not a supported Microsoft product, but rather a vehicle for validating the underlying architecture of the Web Service. Future versions will build on this architecture to provide richer content and functionality. Microsoft hopes that developers experimenting with version 1.0 of the Microsoft.com Web service will provide plenty of feedback to help shape future releases. A newsgroup has been created for this purpose at microsoft.public.mscom.webservices.general.

To start using the Web Service, you must first get a developer's token by browsing to https://ws.microsoft.com/MsComWs/apply.aspx and filling out the form. Interestingly, you don't have to provide any personal information like name, e-mail, or phone to get a token. You simply provide a password (also referred to as a PIN), accept a user agreement, verify the text in an image, and you get a token (something like CqK7XYuJVc0CsXH3Qinukvwzus1KnZUP) that you supply every time you interact with the service.

It's important to note that requiring a token doesn't imply a secure service. The service does not implement security today, instead packaging the token in the SOAP Header according to the WS-Security specification. The token allows Microsoft to track usage and regulate access, and nothing more. For example, Microsoft limits each token to 10 requests per second. If you exceed this limit, your token will become temporarily disabled. Also, since the service was provided primarily for evaluation purposes, the tokens automatically expire 120 days after issuance. To check the status of your token, you can use the form found at https://ws.microsoft.com/MsComWs/account.aspx.

Once you have a developer's token, you can begin using the various operations exposed by the service (see Figure 1 for details). You can call GetCultures to access a list of cultures supported by the GetTopDownloads and GetDownloadDetail operations. GetTopDownloads returns a summary of the current top downloads, sorted either by most recent or most popular. Once you've identified a download of interest, you can use the GetDownloadDetail operation to retrieve the details of the particular download. The last operation, GetVersion, simply returns the descriptive name and the related version number of the current version of the Microsoft.com Web Service.

Figure 1 Microsoft.com Web Service 1.0 Operations

You can browse to the basic documentation page for the service at https://ws.microsoft.com/mscomservice/mscom.asmx and access the official Web Services Description Language (WSDL) document at https://ws.microsoft.com/mscomservice/mscom.asmx?wsdl. Microsoft provides an SDK that includes help files integrated with both Visual Studio® .NET 2002 and Visual Studio .NET 2003. After you install the SDK, you'll find the help files in the Visual Studio .NET Help | Contents window. The SDK also contains various sample applications (in C#, Visual Basic® .NET, J#, and C++) that illustrate how the Web Service may be used in both Web Forms and Windows® Forms applications. The SDK contains helpful figures including some forms that illustrate the typical flow of using the service.

To start using this Web Service, all you need to do is reference the WSDL file and generate classes for accessing the various operations. If you have the Microsoft® .NET Framework installed, you can do this by either running wsdl.exe on the command line or by using the Add Web Reference command in Visual Studio .NET. For example, this is how you use the command-line version:

c:> wsdl.exe https://ws.microsoft.com/mscomservice/mscom.asmx?wsdl Writing file 'c:\temp\mscomservice.cs'

Once you reference the WSDL file, mscomservice.cs contains all the classes necessary to interact with the Web Service. There will be one class that contains all of the operations modeled as methods—in this case it's called MsComServices—along with a bunch of other classes that model the different types of information exposed by the service like Downloads, Download, DownloadSummary, DownloadRelease, Culture, Cultures, and so forth. The complete object model generated from the WSDL document can be seen at Microsoft.com Web Services Object Model.

The hardest part about using the Web Service is sending your PIN and developer's token along with each request. These bits of information are not sent as parameters to the operations. Instead you're expected to send them within the WS-Security header using a UsernameToken structure, as shown in Figure 2.

Figure 2 Sending Your PIN and Token

<soap:Envelope xmlns:soap=...> <soap:Header> <wsse:Security soap:mustUnderstand="1" xmlns:wsse="https://schemas.xmlsoap.org/ws/2002/07/secext" > <wsse:UsernameToken xmlns:wsu="https://schemas.xmlsoap.org/ws/2002/07/utility" wsu:Id="SecurityToken-9cda5cb3-f5c6-4ddf-b9fa-30ff0bcc97f5"> <wsse:Username>PZh3EOz8/GWV+PQel2OaZtrNv2x3/dBk</wsse:Username> <wsse:Password Type="wsse:PasswordDigest" > aDmrV1Ek7pHKnFGiuc/WLQJMoiY=</wsse:Password> <wsse:Nonce>rXl+0wUmcdMNbeMFmqGDiw==</wsse:Nonce> <wsu:Created>2003-07-23T19:51:24Z</wsu:Created> </wsse:UsernameToken> </wsse:Security> •••

You supply your developer's token in the Username element and a digest of your password in the Password element. You must send this header with each message sent to the service. The easiest way to generate this header is to use Web Services Enhancements (WSE), available for download from https://msdn.microsoft.com/webservices.

With WSE, you simply create a UsernameToken object using your token and password and then add it to the security headers collection before invoking any of the operations. If you're not using WSE, you'll have to manually construct the appropriate security header using the available APIs, which is much more tedious. The code in Figure 3 creates the header using WSE.

Figure 3 Security Header Using WSE

// read token and password from config file string Token = ConfigurationSettings.AppSettings["MsComServicesToken"]; string Pin = ConfigurationSettings.AppSettings["MsComServicesPin"]; // Initialize the Web Service and add the credentials to it. MsCom_ws = new MsComServices(); UsernameToken ut = new UsernameToken(Token, Pin, PasswordOption.SendHashed); MsCom_ws.RequestSoapContext.Security.Tokens.Add(ut); // Get the TopDownloads Downloads dls = MsCom_ws.GetTopDownloads(DesiredTopType, NumDownloads, CultureID); •••

The Web application shown in Figure 4 shows the Microsoft.com Web Service in action. The Web page displays a list of the 25 most popular downloads on the left and displays the details of the selected download on the right.

Figure 4 Microsoft.com Web Service in Action

TerraService

Back in 1998, a group of researchers at Microsoft set up a massive SQL database for storing aerial, satellite, and topographic images of the earth. Microsoft made this database available to the public over the Internet and called it TerraServer (see https://terraservice.net).

Users can easily access the images in TerraServer using any Web browser like Microsoft Internet Explorer or Netscape. The HTML-based interface of TerraServer, however, has one major limitation: it doesn't facilitate application integration without resorting to brittle screen-scraping techniques. With the advent of Web Services, the researchers realized that the new Web Services platform would provide the right framework for dealing with application integration scenarios. Hence, they implemented a Web Services interface to their imagery database and called it TerraService (see https://terraservice.net/webservices.aspx).

TerraService essentially provides the same functionality as TerraServer using XML Web Services technologies including XML 1.0, XML Schema, SOAP, and WSDL. The images found in TerraServer are in the public domain so there are no restrictions on how they're used as long as you place an acknowledgment next to the image referencing that it is a United States Geological Survey (USGS) image and that it comes from TerraServer. The bottom line is you don't have to register or get any type of license key to begin using this public service.

TerraServer contains a plethora of small 200×200 pixel images, each with a specific scale and resolution. A 1-meter resolution covers a 200×200 meter area, while a 2-meter resolution covers a 400×400 meter area, and so on. These images are referred to as tiles. TerraServer is interesting because there are enough tiles to stitch together a "seamless mosaic of the entire earth" as described by the TerraService team.

TerraService exposes several operations designed for searching geographic and image coordinates by place name, converting coordinates from one projection plane to another, and fetching tile metadata and the actual tile images. All of the operations are described in Figure 5 and grouped by category. The descriptions should help you get a feel for each operation. More information can be found in the online TerraService documentation.

Figure 5 TerraService Operations

To begin using TerraService, you simply need to generate code from the WSDL file and start using it. The service endpoint for imagery data is at https://terraserver-usa.com/TerraService.asmx. You'll notice the typical ASMX-generated documentation page illustrating that TerraService itself was implemented using the .NET Framework. You can browse to any of the operations to see the sample SOAP messages used by the operation. If you press the Service Description link, you'll see the WSDL file (you can browse directly to the WSDL file using https://terraserver-usa.com/TerraService.asmx?wsdl).

You can generate code from the WSDL file using the Visual Studio .NET Add Web Reference command or wsdl.exe on the command line. Once you've generated the classes, you can begin writing code to interact with TerraService. To illustrate this process, I've provided a small sample application that fetches tiles for a specified place (see Figure 6). The sample allows you to specify the type of image (photo versus topographical map) and the image scale you want. The code in Figure 7 runs when you press the GetTile button on the Windows Form.

Figure 7 Getting the Tile Image

TerraService ts = new TerraService(); // specify place Place place = new Place(); place.City = textBox1.Text; place.State = textBox2.Text; place.Country = textBox3.Text; // get place facts PlaceFacts pfacts = ts.GetPlaceFacts(place); // get tile metadata for place, read them/scale from form TileMeta tm = ts.GetTileMetaFromLonLatPt(pfacts.Center, theme, scale); // get tile image Byte[] imageBytes = ts.GetTile(tm.Id); MemoryStream ms = new MemoryStream(imageBytes); pictureBox1.Image = new Bitmap(ms);

Figure 6** Photo versus Topographical Map **

TerraService is a powerful Web Service that offers valuable data and functionality to geography-oriented applications. TerraService is an excellent place to begin experimenting with Web Services in general if you're just starting down that path. The researchers involved with TerraService put together a thorough white paper that provides a good introduction to Web Services along with an in-depth description of the architecture and design considerations they followed (see TerraService.NET: An Introduction to Web Services).

MapPoint

The Microsoft MapPoint Web Service allows developers to integrate powerful mapping functionality including street maps, driving directions, and proximity searches into their applications. The MapPoint Web Service exposes locations in 19 countries throughout North America and Europe. It also provides business listings, points of interest, and other types of related data that can be used in conjunction with mapping.

The MapPoint Web Service was one of the first commercial Web Services available and Microsoft's first stab at making money with a service-oriented software model. According to the Web site, the MapPoint Web Service comes with two primary licensing models: per transaction and per user. The MapPoint Web Service currently serves more than 10 million transactions daily.

You can begin experimenting with the MapPoint Web Service by requesting an evaluation account from MapPoint Web Service Developer Account. You'll receive an account ID and a password to authenticate with the service. Unlike TerraService, you must have a user account and password in order to access any of the service's operations.

The MapPoint Web Service is logically organized into four subservices: one for common operations and utility functions and others for finding locations, rendering maps, and generating routes and directions. Figure 8 describes the functionality provided by each of these different services. You will typically use operations from multiple services to build a complete mapping-oriented application.

Figure 8 MapPoint Services

All of the operations exposed by these subservices are listed and defined in Figure 9. The brief descriptions should give you a good feel for the overall functionality exposed by the MapPoint Web Service. Using these operations you can find addresses and nonaddressable places such as cities, rivers, postal codes, or airports. There are operations for address parsing, reverse geocoding, and finding points of interest and nearby locations. And there are operations for generating maps, routes, and driving instructions.

Figure 9 MapPoint Web Service Operations (grouped by service)

As with the other services I described, all you need to begin programming against the service is the WSDL file from which you can generate code. The MapPoint Web Service WSDL files are available online. Staging files can be found at https://staging.mappoint.net/standard-30/mappoint.wsdl and https://staging.mappoint.net/secure-30/mappoint.wsdl. Production files can be found at https://service.mappoint.net/standard-30/mappoint.wsdl and https://service.mappoint.net/secure-30/mappoint.wsdl. By choosing one of these WSDL files, you're also choosing between the staging and production environments provided by Microsoft.

Each WSDL file points to a different server endpoint, one designed for testing and another for production use. The staging environment is identical to the production environment, but it's not scaled for the same volume and throughput. You should use the staging environment during the development and testing phases and move to the production environment once your application is ready to go live. This is as easy as swapping out the WSDL files in your project.

I've provided a few sample applications that illustrate how to get the MapPoint Web Service up and running. The first sample illustrates how to retrieve a map for an address, using a red pushpin to illustrate the identified location (see Figure 10). Notice that the app allows the user to enter their address on a single line using the standard U.S. address syntax and the service takes care of parsing it into the constituent fields.

Figure 10** Retrieving a Map for an Address **

The code for this service uses a combination of the ParseAddress, FindAddress, and GetMap operations (from the Find and Render services). The source code in Figure 11 executes when the user presses the GetMap button on the form.

Figure 11 GetMap Sample

NetworkCredential cred = new NetworkCredential("user", "password"); FindServiceSoap fs = new FindServiceSoap(); fs.Credentials = cred; // parse address Address address = fs.ParseAddress(textBox1.Text, comboBox1.Text); // find address FindAddressSpecification spec = new FindAddressSpecification(); spec.InputAddress = address; spec.DataSourceName = "MapPoint.NA"; FindResults results; results = fs.FindAddress(spec); RenderServiceSoap rs = new RenderServiceSoap(); rs.Credentials = cred; // define map views ViewByHeightWidth[] views = new ViewByHeightWidth[1] = { results.Results[0].FoundLocation.BestMapView.ByHeightWidth}; // define map specification MapSpecification mapSpec = new MapSpecification(); mapSpec.DataSourceName = "MapPoint.NA"; mapSpec.Views = views; mapSpec.Options = new MapOptions(); mapSpec.Options.Format = new ImageFormat(); mapSpec.Options.Format.Height = 350; mapSpec.Options.Format.Width = 450; // define pushpin Pushpin pin = new Pushpin(); pin.IconDataSource = "MapPoint.Icons"; pin.IconName = "1"; pin.LatLong = results.Results[0].FoundLocation.LatLong; mapSpec.Pushpins = new Pushpin[1] { pin }; // get map and display MapImage[] mapImages = rs.GetMap(mapSpec); if (mapImages.Length > 0) { MemoryStream ms = new MemoryStream(mapImages[0].MimeData.Bits); pictureBox1.Image = new Bitmap(ms); }

I've provided another sample that shows how to calculate a route between two locations (see Figure 12). The sample displays a map with start and end locations, identified with pushpins, and a highlighted route. The driving instructions are displayed in the textbox under the map.

Figure 12** Calculating a Route between Two Locations **

Adding the route functionality involved using the CalculateSimpleRoute operation of the Route service along with the ParseAddress, FindAddress, and GetMap operations that I used in the previous example. If you supply the calculated route to the GetMap function, MapPoint automatically takes care of highlighting the map, as illustrated in Figure 12. You can then layer pushpins on top of the map to highlight the start and end locations. Figure 13 contains the complete source code for the GetMap button handler.

Figure 13 GetMap Button Handler

NetworkCredential cred = new NetworkCredential("user", "password"); FindServiceSoap fs = new FindServiceSoap(); fs.Credentials = cred; // parse addresses Address address1 = fs.ParseAddress(textBox1.Text, comboBox1.Text); Address address2 = fs.ParseAddress(textBox2.Text, comboBox2.Text); // find addresses FindAddressSpecification spec = new FindAddressSpecification(); spec.InputAddress = address1; spec.DataSourceName = "MapPoint.NA"; FindResults results1; results1 = fs.FindAddress(spec); spec.InputAddress = address2; FindResults results2; results2 = fs.FindAddress(spec); // calculate route using RouteService RouteServiceSoap routesvc = new RouteServiceSoap(); routesvc.Credentials = cred; LatLong[] points = new LatLong[2] { results1.Results[0].FoundLocation.LatLong, results2.Results[0].FoundLocation.LatLong }; Route route = routesvc.CalculateSimpleRoute( points, "MapPoint.NA", SegmentPreference.Quickest); // display driving directions for(int i = 0; i < route.Itinerary.Segments[0].Directions.Length ; i++) textBox3.Text += route.Itinerary.Segments[0].Directions[i].Instruction + "\r\n"; // render map with route RenderServiceSoap rs = new RenderServiceSoap(); rs.Credentials = cred; // define map spec MapSpecification mapSpec = new MapSpecification(); mapSpec.DataSourceName = "MapPoint.NA"; mapSpec.Route = route; mapSpec.Options = new MapOptions(); mapSpec.Options.Format = new ImageFormat(); mapSpec.Options.Format.Height = 350; mapSpec.Options.Format.Width = 450; // define pushpins Pushpin startpin = new Pushpin(); startpin.IconDataSource = "MapPoint.Icons"; startpin.IconName = "28"; startpin.LatLong = results1.Results[0].FoundLocation.LatLong; Pushpin stoppin = new Pushpin(); stoppin.IconDataSource = "MapPoint.Icons"; stoppin.IconName = "29"; stoppin.LatLong = results2.Results[0].FoundLocation.LatLong; mapSpec.Pushpins = new Pushpin[2] { startpin, stoppin }; // get map and display MapImage[] mapImages = rs.GetMap(mapSpec); if (mapImages.Length > 0) { MemoryStream ms = new MemoryStream(mapImages[0].MimeData.Bits); pictureBox1.Image = new Bitmap(ms); }

Although these samples illustrate how to use the MapPoint Web Service in a traditional Windows-based app, it's also possible (and probably more likely) that it will be used from within a Web app. MapPoint provides an image cache for this case so you don't have to worry about saving the retrieved images on your Web server's file system. MapPoint will save the image and provide a URL that can be referenced in the HTML page sent to the client.

There are several other MapPoint Web Service samples available at https://demo.mappoint.net. MSDN also offers a wealth of resources on the MapPoint Web Service at MapPoint Web Service Overview, both in the form of articles and sample code.

.NET Alerts

.NET Alerts is the fourth major Web Service that Microsoft offers today. It provides a powerful communication and notification system for reaching customers or members of an organization. Individuals use the service to subscribe to certain types of notifications and applications use the service to send notifications to all subscribed users.

An alert is any message that you might want to send to a user who has subscribed to receive it. Alerts can be received via e-mail, on mobile devices like PDAs and phones, and through MSN® Messenger. Alerts can be used for a variety of purposes that are valuable to both the individual user and organizations at large.

Like the MapPoint Web Service, .NET Alerts is a commercial Web Service that requires a service agreement before you can begin using it. The service is divided into three subservices including the Alerts Notification Service (accepts your alerts and delivers them to your subscribers), the Alerts Subscription Management Service (provides the ability to create, delete, and update users' subscriptions to your alerts), and the Alerts Topic Management Service (provides the ability to create, update, and enumerate topics).

You can download the .NET Alerts 6.0 SDK and other related resources from MSDN at Microsoft Alerts for Developers. The SDK comes with documentation, sample code, and tools that facilitate the development process. The SDK contains emulators for the .NET Alerts notification and subscription components. The emulators allow you to test your application before going live. Microsoft even requires an official compliance test before your site can go live using the service.

.NET Alerts is a bit more involved than the other services I've discussed in this column, and since I'm out of space, I won't be able to go into the details further. However, there are plenty of good .NET Alerts resources online if you're serious about using it. The Adventure Works 2.0 sample is a great starting point for mastering the details of .NET Alerts.

The State of Web Services

Microsoft provides several interesting Web Services that developers can use to integrate valuable data and functionality into their applications today. Other major organizations like Amazon.com and Google.com have also exposed some of their data and functionality through Web Services interfaces. To begin using any of these services, all you need is a WSDL file and a good Web Services toolkit like Visual Studio .NET 2003.

Send your questions and comments for Aaron to  xmlfiles@microsoft.com.

Aaron Skonnard teaches at Northface University in Salt Lake City, where he's helping establish one of the finest universities in the world for software developers. Aaron coauthored Essential XML Quick Reference (Addison Wesley, 2001) and Essential XML (Addison Wesley, 2000).