Using an XML SOAP Web Service from Visual Studio 2005, 2008 and 2010

Introduction

Here we show how to use external SOAP web services from within Microsoft Visual Studio versions 2005, 2008 and 2010.

The scope of this article extends only to XML SOAP web services which may have been created in Visual Studio (and are usually identified by the asmx extension at the end of the URL).

In order to demonstrate the use of external web services, we will use T2A's SOAP service, which was created using Visual Studio 2005.

All code examples here are in C#.

Making Life Easy

If you've never made use of an external web service from Visual Studio, you're about to discover just how easy it is. In comparison, parsing XML yourself can be quite time consuming, even using a powerful XML reader or parser. A SOAP web service allows Visual Studio to discover how its methods operate (their inputs and return formats) and using this information, allows your IDE to create code within your project, to allow your code to seamlessly use the external service, just as if it was a class in your own code.

Using a Web Service from Visual Studio 2005

In order to simply demonstrate the use of T2A's SOAP service, we created a C# console application. The IDE created an empty project.

We then "told" our project about the web service. We right clicked on the project in the solution explorer, and clicked on Add Web Reference. This can be viewed below, for our project ws_test_2005:-

A new window opened, in which we specified the location of the web service, in this case, https://t2a.co/soap. We clicked the go button:-

The IDE was able to identify the web service. We named the web service t2a. We then clicked on add reference as seen below.

The IDE then created the necessary code to allow our simple project to use the external web service. You can see the information about the added web reference in the right hand pane below:-

We then created a simple console application which uses the T2A soap service, specifically the geo_code method, which as its name suggests, returns geographical co-ordinates for a given postcode, street or place.

The example code shown below uses T2A's free test mode, during which it returns dummy data at no charge, for the benefit of developers in their initial integration stages.


using System;
using System.Collections.Generic;
using System.Text;

namespace ws_test_2005
{
    class Program
    {
        static void Main(string[] args)
        {
            string api_key = "test";

            t2a.T2A ws = new t2a.T2A();
            t2a.geo_code_res ws_res = ws.geo_code(api_key, null,"york");
            if (ws_res.status.CompareTo("ok") == 0)
            {
                 //print geo code data
                int i = 0;
                while (i < ws_res.geo_data_list.Length)
                {
                    Console.WriteLine(ws_res.geo_data_list[i].description +
                        " at (" +
                        ws_res.geo_data_list[i].latitude + "," +
                        ws_res.geo_data_list[i].longitude+")"
                        );

                    i++;
                }

            }

        }
    }
}

When the console application is executed in the debugger, we can see the class instance that the IDE has created; in this case an array of geo_data instances, this being a member of the result class geo_code_res. Note in the bottom pane the contents of the class instances, in this case, the dummy data returned by T2A in free test mode:-

Detailed Explanation of the Code Example

Normally you would use the API key associated with your T2A account; for this example we are using T2A's free test mode; this is activated by an API key "test":-

string api_key = "test";

Remember that we named the external web service t2a? The code created by the IDE is in a namespace t2a. The namespace includes the main class that contains the T2A methods; this is named T2A, or more correctly, t2a.T2A.

We now create an instance of that class.

t2a.T2A ws = new t2a.T2A();

The geo_code method returns an instance of the class t2a.geo_code_res. We now invoke the method; the third parameter is the place, street or postcode for which we want the geo co-ordinates.

t2a.geo_code_res ws_res = ws.geo_code(api_key, null,"york");

If the method has succeeded, the status is ok. If not, we normally would then read the error code.

We then display the contents of the t2a.geo_data instances held in the array t2a.geo_code_res.geo_data_list.

if (ws_res.status.CompareTo("ok") == 0)
{
   //print geo code data

   int i = 0;
   while (i < ws_res.geo_data_list.Length)
   {
      Console.WriteLine(ws_res.geo_data_list[i].description +
      " at (" +
      ws_res.geo_data_list[i].latitude + "," +
      ws_res.geo_data_list[i].longitude+")"
      );

Using a Web Service from Visual Studio 2008

We created a C# console application; it actually uses the same code as shown above. When adding the web reference, the first thing one notices is that whereas formerly beneath Add Reference there was an item Add Web Reference, this seems to be missing from Visual Studio 2008. In its place is Add Service Reference.

We clicked that instead (see below).

A new window opened, named Add Service Reference. In order to add a "legacy" web reference, we clicked the advanced button at the bottom.

Yet another new window opened, named Service Reference Settings. We hit the Add Web Reference button at the bottom.

From that point, adding the web reference is the same as above, for Visual Studio 2005. We created the reference by informing the dialog box that we wished to use https://t2a.co/soap as we had with Visual Studio 2005.

Using a Web Service from Visual Studio 2010

The procedure for adding the web reference is the virtually the same for the 2010 version as for 2008; the image below shows the default Solution Explorer pane for our console application.