When you think ASP, think...
Recent Articles
All Articles
ASP.NET Articles
ASPFAQs.com
Message Board
Related Web Technologies
User Tips!
Coding Tips
Search

Sections:
Book Reviews
Sample Chapters
Commonly Asked Message Board Questions
JavaScript Tutorials
MSDN Communities Hub
Official Docs
Security
Stump the SQL Guru!
Web Hosts
XML
Information:
Advertise
Feedback
Author an Article

ASP ASP.NET ASP FAQs Message Board Feedback
 
Print this Page!
Published: Wednesday, November 5, 2003

An Extensive Examination of Web Services: Part 3

By Scott Mitchell


An Extensive Examination of Web Services Index
An Extensive Examination of Web Services is a multi-part article series spanning several months. Listed below are the current "parts," along with a very brief synopsis and the date published.
  • Part 1 - Examines the basics of Web services, what Web services are, and the technologies and standards that serve as the underpinnings of Web services. (October 8th, 2003)
  • Part 2 - Examines creating Web services using Visual Studio .NET. Looks underneath the hood of the code created by VS.NET. (October 15th, 2003)
  • Part 3 - Examines creating a client application that consumes a Web service. Discusses the purpose and structure of a WSDL document, along with creating and using proxy classes to consume a Web service. (November 5th, 2003)
  • Part 4 - Examines the utility of Web services and common scenarios where Web services make sense. A business-oriented look at Web services. (November 19th, 2003)
  • Part 5 - Takes an in-depth look at XML serialization, which is the process of converting a data type, such as an integer, array, or custom class, into its XML representation, and back again. Every time a message is passed to or from a Web service, XML serialization transpires. (December 17th, 2003)
  • Part 6 - Looks at sending metadata to a Web method through the use of SOAP headers. Examines defining and accepting a SOAP header on the Web service end, and looks at sending a populated SOAP header from the client. (December 31st, 2003)
  • Part 7 - Examines how the incoming and outgoing messages to a Web service can be programmatically modified via SOAP Extensions. (January 21st, 2004)
  • Part 8 - Learn about the Web Service Enhancements (WSE) and Microsoft's free class library for implementing the WSE standards. (June 30th, 2004)
  • Part 9 - See how to implement UsernameToken authentication using the WSE 2.0 Toolkit. (July 14, 2004)
  • Part 10 - Learn how to send large amounts of data as attachments using DIME and WS-Attachments. (September 8th, 2004)
  • Part 11 - Create (and consume) client-side script-accessible Web Services using Microsoft's ASP.NET AJAX framework. (September 26th, 2007)

Introduction


Welcome to Part 3 of An Extensive Examination of Web Services! In this part we'll examine how to consume a Web service from a client application. The client application, mind you, can be any application that can issue an HTTP request to the Web service. That is, the client can be what we typically think of as a client - say a stand-alone Windows desktop application - or it can be what we more traditionally think of as a server - such as an ASP.NET Web page on a Web server.

Recall from our discussions in Part 2 that Web services communicate via messages formatted in the SOAP standard, where the messages are transmitted over the Internet using (typically) the HTTP protocol. A Web service call begins with the client sending a request for a particular method to the Web service. The Web service then processes this request and returns the result of the method wrapped up in a SOAP message. (See this diagram for a graphical illustration of a Web service interaction.) Also, in Part 2 we briefly discussed what WSDL was. Namely, is it the means by which a Web service is formally defined. It is the WSDL document that specifically spells out how the messages that will be passed to and from the Web service must be serialized. That is, how the method to be called is specified, and how the input and output parameters are represented in XML.

In order to call a Web service from a client application, the client needs to do a couple of things:

  1. It must be able to inspect the Web service's WSDL document so that it knows how to serialize the call to the Web service.
  2. It must serialize the input messages, and wrap everything up into a SOAP message.
  3. It must make an HTTP request to the URL the Web service resides at. It then must wait for an HTTP response.
  4. Upon receiving the response, the client must deserialize the return values.

Clearly the steps required here are a tall order. Fortunately, much of the complexity of this process is abstracted away through the use of a proxy class. As we'll discuss in this article, the .NET Framework SDK ships with a tool that, given a WSDL document, will automatically generate an appropriate proxy class. Before we examine how to use this tool, we'll first discuss WSDL in more detail.

- continued -

Understanding WSDL


WSDL, or Web Service Description Language, is an XML-formatted document that formally defines the Web service. Specifically, the WSDL document spells out in precise terms:

  • The data types of the messages a Web service will accept and send (these message types are spelled out using XML Schema)
  • What message formats are accepted (SOAP, HTTP-POST, HTTP-GET, etc.)
  • For SOAP messages, the style and encoding of the SOAP message, and
  • The Web service's endpoint (the URL the Web service resides at)

You can view the WSDL document for a .NET Web service by visiting the .NET Web service endpoint through a browser. Doing so will display information about the Web service (shown below), which includes a hyperlink titled "Service Description."

Clicking the "Service Description" link will display the Web service's WSDL document. In Part 2 of this article series we created a very simple Web service with two methods: Add() and Subtract(), both of which took two integers as input and returns the sum or difference, respectively. Let's examine this Web service's WSDL document. (You can view the WSDL document in its entirety if you'd like...)

The <definitions> and <types> Elements
All WSDL documents start with a <definitions> element, which is the document's root element. This element does nothing more that serve as the root element and specify the namespaces used in the WSDL document. The first child element is <types>, which spells out the message data types used in the Web service via the XML Schema specification. Recall that there are two messages associated with each method defined in the Web service - the request message and the response message. The following snippet defines the request and response messages for the Add() method:

<definitions namespaces defined here>
  <types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://tempuri.org/">
      <s:element name="Add">
        <s:complexType>
          <s:sequence>
            <s:element minOccurs="1" maxOccurs="1" name="x" type="s:int" />
            <s:element minOccurs="1" maxOccurs="1" name="y" type="s:int" />
          </s:sequence>
        </s:complexType>
      </s:element>
      <s:element name="AddResponse">
        <s:complexType>
          <s:sequence>
            <s:element minOccurs="1" maxOccurs="1" name="AddResult" type="s:int" />
          </s:sequence>
        </s:complexType>
      </s:element>
      ...
  </types>
  ...
</definitions>

XML Schema is used to define the structure of an XML document. Therefore, the <types> element here defines the serialized XML for the request and response messages to the Add method. The first data type specifies is an XML document that contains an <Add> element with two children elements: <x> and <y>, whose text data is of type integer. Furthermore, there should be one, and exactly one, of each of these two children elements. That is, the following XML document conforms to the schema:

<Add>
  <x>4</x>
  <y>8</y>
</Add>

Similarly, another data type defined is one that contains an XML element named <AddResponse> and that has precisely one child element, <AddResult>, whose text data is of type integer. In addition to these two data types, the WSDL document contains two additional data types not shown in the above listing: Subtract and SubtractResult.

For More Information on XML Schema...
XML Schema is an XML-formatted specification for indicating the schema of an XML document. A thorough discussion of XML Schema is far beyond the scope of this article. For more information, check out the XML Schema Tutorial or O'Reilly's book XML Schema.

The <message> and <portType> Elements
Following the <types> element is the <message> element. The <message> element maps the messages the Web service provides with the data types defined in the <types> element. For example, the Add() method's two messages - named for us as AddSoapIn and AddSoapOut - are assigned the appropriate data types with the following <message> elements:

<definitions namespaces defined here>
  ...
  <message name="AddSoapIn">
    <part name="parameters" element="s0:Add" />
  </message>
  <message name="AddSoapOut">
    <part name="parameters" element="s0:AddResponse" />
  </message>
  ...
</definitions>

The next element in a WSDL document is the <portType> element, which specifies what methods the Web service provides, and the input and output messages for these methods. For our simple Web service there are two methods: Add() and Subtract(). The following shows the <portType> element for our Web service:

<definitions namespaces defined here>
  ...
  <portType name="Service1Soap">
    <operation name="Add">
      <input message="s0:AddSoapIn" />
      <output message="s0:AddSoapOut" />
    </operation>
    <operation name="Subtract">
      <input message="s0:SubtractSoapIn" />
      <output message="s0:SubtractSoapOut" />
    </operation>
  </portType>
  ...
</definitions>

The <binding> and <service> Elements
After the <portType> element comes the <binding> element, which specifies the message protocols accepted by the Web service. Typically there will only be one <binding> element, which specifies that the SOAP protocol is used. However, there are other Web service protocols such as HTTP-POST and HTTP-GET. Not only does the <binding> element specify what protocols are supported, but also the details about these protocols. For example, the SOAP protocol supports different styles and encodings of the actual SOAP message - these details need to be spelled out here.

<definitions namespaces defined here>
  ...
  <binding name="Service1Soap">
    <operation name="Add">
      <input message="s0:AddSoapIn" />
      <output message="s0:AddSoapOut" />
    </operation>
    <operation name="Subtract">
      <input message="s0:SubtractSoapIn" />
      <output message="s0:SubtractSoapOut" />
    </operation>
  </binding>
  ...
</definitions>

A thorough discussion of SOAP message styles and encodings is a bit beyond the scope of this article. Realize that in the early days of Web services there were ongoing discussions as to the best way to specify the method of the Web service to call, and how the types of the messages were defined. There are two types of styles allowed, either RPC or Document. Similarly, there are two encoding types: literal, and encoded. Realize today, and moving forward into the future, the preferred style and encoding is Document/Literal, which is the style and encoding used by default when creating Web services with Visual Studio .NET. The only time you might need to use alternative styles or encodings is if you are building a Web service that needs to interact with a legacy client. (A more thorough discussion of the style and encoding differences can be found at this FAQ.)

The final element is a WSDL document is the <service> element, which specifies the Web service's endpoint for each binding.

<definitions namespaces defined here>
  ...
  <service name="Service1">
    <port name="Service1Soap" binding="s0:Service1Soap">
      <soap:address location="URL of Web service" />
    </port>
  </service>
</definitions>

Consuming a Web Service


In order for a client to be able to consume a Web service, the client must know a bit about the Web service - namely, it must know where the Web service "lives" and how to invoke its methods (by knowing how to serialize and deserialize the messages it passes to and receives from the Web service). This information is contained wholly in the Web service's WSDL document (which is why we spent so much time discussing the WSDL document in the first place!). In addition to knowing how to invoke the Web service's methods, the client must also go through the motions involved in creating the SOAP message to send to the Web service, making the actual HTTP request, and then deserializing the HTTP response. These steps, mind you, will need to be repeated for each Web service a client wishes to consume.

Whenever you are faced with too much complexity, you should always think, "encapsulation." That is, it is likely worthwhile to build a class that provides an easy to understand interface by encapsulating all of the complexity. For example, for calling a Web service it would be nice to have a class with the same methods as the Web service itself. From our client, then, we could just call this class's methods and the class will worry about the hard work - serializing the input parameters into a SOAP message, making the HTTP request, and deserializing the response.

Fortunately, we do not have to create this class ourselves, as Microsoft provides a tool in the .NET Framework SDK that will do just this. To use this tool we just need to specify the WSDL document of the Web service - the tool will then retrieve the WSDL document and build a class that can then be used to invoke the Web service. (This class is called a proxy class because it implements the Proxy Pattern.)

Building the Proxy Class
Building the proxy class in Visual Studio .NET is quite simple. Start by opening the project from which you want to consume the Web service. Remember, this can be an ASP.NET Web page or a stand-alone Windows Form. To create the proxy class, right-click on the References folder in the Solution Explorer and choose "Add Web Reference." This will display the dialog box shown below. To create a proxy class for a specified Web service, type in the URL to the Web service's WSDL file and hit enter. This will load a description of the Web service. To create a proxy class for this Web service, simply click the Add Reference button.

Add Web Reference dialog box.

This will create a class with the same name as the Web service, with methods identical to that of the Web service. The class is placed within the namespace specified by the value in the Web Reference Name textbox in the Add Web Reference dialog box. For our sample Web service, the namespace used was localhost. The name of the Web service was Service1, so the proxy class's name is Service1. The proxy class has a number of methods, but the two that we care about are:

  • Add(int, int), and
  • Subtract(int, int)

These two methods are, not coincidentally, the two methods provided by the Web service. We can now have our client application consume the Web service by accessing the local methods of our proxy class. When our client application calls the proxy class's Add() method, the proxy class serializes the input parameters into a SOAP message, makes the HTTP request to the Web service's endpoint, receives the response, deserializes it, and returns the resulting value to the client application. This interaction is outlined in the following diagram:

The role of a proxy class.

The following code shows how to consume the Web service. Again, it's as simple as creating an instance of the proxy class and calling the corresponding method. The following code shows some VB.NET code that displaying the results of a call to the Add() method:

'Create an instance of the proxy class
Dim proxy as New localhost.Service1()

'Call the Add method
Dim result as Integer
result = proxy.Add(4, 6)

Creating a Proxy Class Without VS.NET
If you don't have Visual Studio .NET, but do have the .NET Framework SDK installed, you can still create a proxy class to consume a Web service. The downside, though, is that you have to do so through a command-line interface. The tool is called wsdl.exe. For more information on using wsdl.exe see the technical docs...

Conclusion


In this article we examined how a client can consume a Web service through the use of a proxy class. A proxy class is a class that encapsulates the complexity of calling a Web service and exposes this complexity through a simplified interface. From the client application's perspective, the Web service is simply a local component - the client doesn't have to worry about the specifics of how to serialize a SOAP message, or how to make an HTTP request.

In order to create the proxy class, it is important that you have access to the Web service's WSDL document. The WSDL document is an XML-formatted document that formally defines a Web service. It specifies the data types of the messages, what protocols are accepted, and the Web service's endpoint. Given nothing more than a Web service's WSDL, you'll find that with Visual Studio .NET the number of minutes needed to go from no code to actually calling the Web service can be counted on one hand.

Happy Programming!

  • By Scott Mitchell


    Beginner's .NET XML Web Services

    Beginner's .NET XML Web Services DVD

    Beginner's .NET XML Web Services offers nearly eight hours of training on .NET XML Web services in a video format. This two-disc DVD set, presented by author Scott Mitchell, offers a unique opportunity for learning about the fundamentals of Web services. The 14 lessons begin with an examination of the core Web service standards, and then quickly move into showing you how to create and consume Web services in Microsoft's .NET Framework. There are in-depth lessons for each of the core Web service standards - XML, SOAP, and WSDL - along with examples of the Web Service Enhancements (WSE). Scattered throughout each of these chapters are extensive demos, depicting how to build, deploy, and access Web services using Microsoft's Visual Studio .NET. The DVD also contains a thorough examination of a real-world, end-to-end Web service application.

    Scott Mitchell is the editor and founder of 4GuysFromRolla.com, author of the An Extensive Examination of the Web Services article series, and author of numerous ASP and ASP.NET books.

    [Buy this DVD]

    Why get stuck with a 600-page paperweight when you can learn about .NET Web Services through an interesting and interactive video presentation?



  • ASP.NET [1.x] [2.0] | ASPMessageboard.com | ASPFAQs.com | Advertise | Feedback | Author an Article