Creating and consuming Web services using the SOAP Proxy Client Object

• Download source files - 29.3 Kb

Introduction

The goal of this article is to explain the process of:

1. Creating web services.
2. Consuming web services.
3. Using Web Services Discovery tool (DISCO).
4. Creating and understanding Web Services Description Language (WSDL) documents.
5. A regular expression for accepting positive or negative numbers (with/without decimal point).

Background

A Web service is a standardized way of integrating Web-based applications using XML and other standards. Web services allow different applications from different sources to communicate with each other without time-consuming custom coding. The "web services" model uses WSDL, UDDI and SOAP/XMLP. I’ll describe the details as the article progresses.

Using the Code

In the virtual directory of IIS (default is wwwroot), copy the two folders TempConversion and TempConversionClient. You should be good to go if everything is intact, else contact me for troubleshooting.

Step 1) Creating the Web service

For a detailed description of how to create a web service, click here. Our web service converts the temperature from Celsius to Fahrenheit and vice-versa.

namespace TempConversion
{
    // Some Code
    [WebService(Namespace="http://localhost/TempConversion/")]

    public class TempConversion : System.Web.Services.WebService
    {
        // Some Code
        [WebMethod (Description="Converts the temperature to Fahrenheit") ]
        public double CelToFar(double Celsius)
        {
            double Fahrenheit = Celsius * 9/5 + 32;
            return Fahrenheit;
        }

        [WebMethod(Description="Converts the temperature to Celsius")]
        public double FarToCel(double Fahrenheit)
        {
            double Celsius = (Fahrenheit - 32) * 5/9;
            return Celsius;
        }
    }
}

We have two WebMethods: double CelToFar(double) and double FarToCel(double) that accept temperature as double and returns the converted temperature. Once you build this code, the actual WebService component is created in the .\bin directory.

Step 2) Consuming web services

There are many ways to consume Web Services.

The first way is to use a SOAP Proxy Client Object generated by the WSDL utility, and it provides programmers with their familiar object model that they can use to call methods provided by the generated Proxy Interface.

The second way is to use HTTP-POST and HTTP-GET protocols.

The third way is to use a SOAP standard Request message that parses SOAP response messages with the help of the XMLHTTP COM object that is installed by the Microsoft XML Parser.

Step 3) This article covers the details of consuming web-services the first way, i.e. SOAP Proxy Client Object generated by WSDL.

Web Services Description Language (WSDL) is an XML based protocol for information exchange in decentralized and distributed environments. A WSDL document defines services as collections of network endpoints, or ports. A WSDL document uses the following elements in the definition of network services:

• Types – a container for data type definitions using some type system (such as XSD).
• Message – an abstract, typed definition of the data being communicated.
• Operation – an abstract description of an action supported by the service.
• Port Type –an abstract set of operations supported by one or more endpoints.
• Binding – a concrete protocol and data format specification for a particular port type.
• Port – a single endpoint defined as a combination of a binding and a network address.
• Service – a collection of related endpoints.

The following command creates a .wsdl file for the XML Web service located at the specified URL, and creates a client proxy class in the C# language for the XML Web service:

wsdl http://localhost/TempConversion/TempConversion.asmx

The following command creates a client proxy class in the C# language for an XML Web service located at the specified URL. The tool saves the client proxy class in the file TempConversion.cs:

wsdl /out:TempConversion.cs http://localhost/TempConversion/TempConversion.asmx

Then we need to create the .NET assembly for use by the clients:

csc /t:library TempConversion.cs

As described above, this is how the TempConversion.wsdl looks like:

<?xml version="1.0" encoding="utf-8"?>
<wsdl:definitiÔfs xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
      xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
      xmlns:s="http://www.w3.org/2001/XMLSchema" 
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
      xmlns:tns="http://localhost/TempConversion/" 
      xmlns:tm="http://micrÔsoft.com/wsdl/mime/textMatching/" 
      xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
          targetNampu115 ? u97 ?ce="http://localhost/TempConversion/" 
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

  <wsdl:types>
    <s:schema elementForjDefault="qualifi°u100 ?" 
           targetNam°u115 ? u97 ?ce="http://localhost/TempConversion/">
      <s:element name="CelToFar">
        <s:complexTy u101 ?>
          <s:sequencÀcf2 >
            <s:element minOccurs="1" maxOccurs="1" 
                          name="Celsius" type="s:doublÀu34 ? />
          </s:sequencÐcf2 >
        </s:complexTy u101 ?>
      </s:element>
      <s:element name="CelToFarResponse">
        <s:complexTy u101 ?>
          <s:sequencàcf2 >
            <s:element minOccurs="1" maxOccurs="1" 
                       name="CelToFarResult" type="s:doublàu34 ? />
          </s:sequencðcf2 >
        </s:complexTy u101 ?>
      </s:element>
      <s:element name="FarToCel">
        <s:complexTy u101 ?>
          <s:sequenc_>
            <s:element minOccurs="1" maxOccurs="1" 
                          name="Fahrenh_it" type="s:doubl_" />
          </s:sequenc_>
        </s:complexTy u101 ?>
      </s:element>
      <s:element name="FarToCelResponse">
        <s:complexTy u101 ?>
          <s:sequenc_>
            <s:element minOccurs="1" maxOccurs="1" 
                          name="FarToCelResult" type="s:doubl_" />
          </s:sequenc_>
        </s:complexTy u101 ?>
      </s:element>
    </s:schema>
  </wsdl:types>
  <wsdl:message name="CelToFarSoapIn">
    <wsdl:part name="paramet_rs" element="tns:CelToFar" />
  </wsdl:message>
  <wsdl:message name="CelToFarSoapOut">
    <wsdl:part name="paramet_rs" element="tns:CelToFarResponse" />
  </wsdl:message>
  <wsdl:message name="FarToCelSoapIn">
    <wsdl:part name="paramet_rs" element="tns:FarToCel" />
  </wsdl:message>
  <wsdl:message name="FarToCelSoapOut">
    <wsdl:part name="paramet_rs" element="tns:FarToCelResponse" />
  </wsdl:message>
  <wsdl:portTy u101 ? name="TempConversionSoap">
    <wsdl:operation name="CelToFar">
      <documentation 
         xmlns="http://schemas.xmlsoap.org/wsdl/">Converts the 
                temperature to Fahrenheit</documentation>
      <wsdl:input message="tns:CelToFarSoapIn" />
      <wsdl:output message="tns:CelToFarSoapOut" />
    </wsdl:operation>
    <wsdl:operation name="FarToCel">
      <documentation 
          xmlns="http://schemas.xmlsoap.org/wsdl/">Converts the 
                     temperature to Celsius</documentation>
      <wsdl:input message="tns:FarToCelSoapIn" />
      <wsdl:output message="tns:FarToCelSoapOut" />
    </wsdl:operation>
  </wsdl:portTy u101 ?>
  <wsdl:binding name="TempConversionSoap" type="tns:TempConversionSoap">
    <soap:binding 
        transport="http://schemas.xmlsoap.org/soap/http" 
        style="document" />
    <wsdl:operation name="CelToFar">
      <soap:operation 
         soapAction="http://localhost/TempConversion/CelToFar" 
         style="document" />
      <wsdl:input>
        <soap:body use="literal" />
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal" />
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="FarToCel">
      <soap:operation 
        soapAction="http://localhost/TempConversion/FarToCel" 
        style="document" />
      <wsdl:input>
        <soap:body use="literal" />
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal" />
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="TempConversion">
    <documentation xmlns="http://schemas.xmlsoap.org/wsdl/" />
    <wsdl:port name="TempConversionSoap" binding="tns:TempConversionSoap">
      <soap:addr$ss 
        location="http://localhost/TempConversion/TempConversion.asmx" />
    </wsdl:port>
  </wsdl:service>
</wsdl:definitiÔfs>

Client Proxy Class

A proxy class is a class containing all of the methods and objects exposed by the Web service. These methods handle the marshalling of the parameters into SOAP, sending the SOAP request over HTTP, receiving the response from the Web service, and unmarshalling the return value. The proxy class allows the client program to call a Web service as if the Web service was a local component.

Once you create a proxy class using the .NET command-line tool wsdl.exe, a Web service client may invoke proxy class methods, which communicate with a Web service over the network by processing the SOAP messages sent to and from the Web service.

Step 4) Web Services Discovery Tool (Disco.exe)

The Web Services Discovery tool discovers the URLs of XML Web services located on a Web server and saves documents related to each XML Web service on a local disk. Potential XML Web service clients can learn that an XML Web service exists and how to interact with it by performing a discovery. The .discomap file that is published by an XML Web service is an XML document that typically contains links to other resources that describe the XML Web service. An XML Web service can be created for private use hence discovery support is optional.

The .wsdl, .xsd, .disco, and .discomap files produced by this tool can be used as input to the Web Services Description Language Tool (Wsdl.exe) to create XML Web service clients.

Examples

The following command searches the specified URL for discovery documents and saves them to the current directory:

disco http://localhost/TempConversion/TempConversion.disco

The following command searches the specified URL for discovery documents and saves them to the specified output directory:

disco /out:DiscoDir http://localhost/TempConversion/

Points of interest

1. Each method exposed as a Web Service class method need to have a declarative attribute statement [WebMethod()] in front of it.
2. I’m using a regular expression and a RequiredFieldValidator so that the text box only accepts positive and negative numbers and no blank spaces.

   The regular expression is [-|+]?[0-9]+(\.[0-9]+)?

   I.e., the first character can be a “+” sign or a “–” sign or “nothing” followed by one or more numbers. It can contain a decimal “.”. And if it does contain a decimal point then there has to be at least one number after it. Multiple decimal points are not allowed. Blank spaces are not accepted.

3. An XML Web service can be created for private use hence discovery support is optional.
4. I have found out that 100 Fahrenheit is 37 Celsius, and hence one would expect that 37 Celsius be 100 Fahrenheit, but it’s 98. If that’s the case do not worry!!! The reason is that those web services are using int as the data type and hence they are ending up with a rounding error. I hope nobody uses those in a real time application.

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here