Recipe 17.8. Calling a Web Service

Problem

You want to access an XML Web Service across the Internet.

Solution

Sample code folder: Chapter 17\WebReference

Add a Web Reference to your project, and use the My.WebServices object to access the service.

Discussion

An XML Web Service is a function located on the Internet that your application can call. But unlike internal functions, calls to XML Web Services communicate via standard HTTP and plain text. They use defined standards, such as SOAP and WSDL, which are beyond the scope of this book.

There are a lot of XML Web Services available on the Internet, some free and some for a fee. For demonstration purposes, the following sample code calls Microsoft's TerraServer engine (http://terraserver.microsoft.com) to get a place name for any latitude and longitude around the world.

To call an XML Web Service, you must first add a Web Reference to your project. Create a new Windows Forms project, and select the Project Add Web Reference menu command. When prompted for a service path URL in the Add Web Reference dialog, enter http://terraserver.microsoft.com/TerraService.asmx to access the Terra-Server Web Service. Then click the Add Reference button. Figure 17-8 shows how the Add Web Reference dialog helps you to explore the functionality provided by a service.

Figure 17-8. The Add Web Reference dialog

To demonstrate one of the functions provided by this service, this recipe's code calls the ConvertPlaceToLonLatPt() function to do just what it says: convert a place name to a latitude and longitude location. You can also convert in the other direction, using the service's ConvertLonLatPtToNearestPlace() function.

Add two Button controls to your form named ActToPlace and ActToLatLon, and set their Text properties to Locate. Also add five TextBox controls named CityName, StateName, CountryName, Latitude, and Longitude. Add some informational labels if desired. The form should look something like Figure 17-9.

Figure 17-9. Controls for the XML Web Services sample

Now, add the following code to the form's class template:

 Private Sub ActToLatLon_Click(ByVal sender As System.Object, _       ByVal e As System.EventArgs) Handles ActToLatLon.Click    ' ----- Locate the latitude and longitude for a place.    Dim usePlace As com.microsoft.terraserver.Place    Dim foundLocation As com.microsoft.terraserver.LonLatPt    ' ----- Prepare the location details for use.    usePlace = New com.microsoft.terraserver.Place    usePlace.City = CityName.Text    usePlace.State = StateName.Text    usePlace.Country = CountryName.Text    ' ----- Call the service with the user-supplied values.    Me.Cursor = Cursors.WaitCursor    foundLocation = _       My.WebServices.TerraService.ConvertPlaceToLonLatPt( _       usePlace)    Me.Cursor = Cursors.Default    ' ----- Inform the user.    MsgBox("That place is located at:" & vbCrLf & vbCrLf & _       "Latitude: " & foundLocation.Lat.ToString & vbCrLf & _       "Longitude: " & foundLocation.Lon.ToString) End Sub Private Sub ActToPlace_Click(ByVal sender As System.Object, _       ByVal e As System.EventArgs) Handles ActToPlace.Click    ' ----- Locate the place for a latitude and longitude.    Dim useLatLon As com.microsoft.terraserver.LonLatPt    Dim foundPlace As String    ' ----- Prepare the location details for use.    useLatLon = New com.microsoft.terraserver.LonLatPt    useLatLon.Lat = CDbl(Latitude.Text)    useLatLon.Lon = CDbl(Longitude.Text)    ' ----- Call the service with the user-supplied values.    Me.Cursor = Cursors.WaitCursor    foundPlace = My.  WebServices.TerraService. _       ConvertLonLatPtToNearestPlace(useLatLon)    Me.Cursor = Cursors.Default    ' ----- Inform the user.    MsgBox("That location is at or near:" & vbCrLf & _       vbCrLf & vbTab & foundPlace) End Sub 

Figure 17-10 shows the form in action. After entering the latitude and longitude for one of our favorite (and certainly one of the most memorably named) airports, a click of the button reveals the server's place name for this location as the airport at Deadhorse, Alaska.

Figure 17-10. Converting latitude and longitude into a place name

This example shows how easy it is to use an Internet-based XML Web Service as if it were a function local to your application's source code. XML is used to make these services hardware-and software-independent, which means this same service can be called from a variety of programming languages using just about any computer and any operating system.