+41 31 950 6050         info@futureit.ch            
    FutureTech

Building Soap services with Visual C++ .NET

Introduction
This article gives a quick introduction to SOAP and its fundamentals. Further it guides how to develop and test a SOAP based Web service in Visual Studio .Net.

SOAP
Simple Object Access Protocol (SOAP) is a new way to exchange information among different applications. It enables to build services that could be called by any other application regardless of their platform and language used. A simple example could be to develop a set of functions, which provide some business logic, expose those functions through SOAP and let the rest of applications or your clients to use the functionality of those services.

Why SOAP?
There are a number of technologies being used for distributed computing. These include DCOM, CORBA, etc., which use Remote Procedure Calls (RPC) for communications. RPC does not work well across Internet, especially when there is a firewall involved. On the other hand, communication through SOAP can take place over different protocols (like HTTP, SMTP, TCP, and others.) The information being communicated is eXtensible Markup Language (XML) based. The use of XML and support of different protocols also make possible to use SOAP services from behind the firewall. This also opens new ways including that clients can use SOAP services over the Internet.

How this works?
As we discussed earlier, SOAP communication can take place over different protocols and information being exchanged is in XML form. The whole mechanism has following parts, which play different roles:
  • SOAP Service
  • Web Service Description Language (WSDL)
  • SOAP Server
  • SOAP Message
SOAP Service: It is the main service which client will call to get functionality. This can be developed in Visual C++, Visual BASIC, Java, etc. Different toolkits are available which provide a number of utility classes to build and use SOAP services. For example, Microsoft is providing SOAP Toolkit 2.0, which can be downloaded form Microsoft official web site (http://www.microsoft.com).

Web Service Description Language (WSDL): WSDL is an XML document which describes the operations provided by a SOAP service (Web Service). It tells about input and output for each operation. WSDL document is used by client of a web service, so that it can know which operations that particular web service is providing. Client will first request WSDL from SOAP server. From the WSDL, it will form a SOAP request and will send it to SOAP server.

SOAP Server: It is the part where SOAP service will be deployed. For example for Microsoft Windows NT/2K/XP users, this can part can be Internet Information Server (IIS). SOAP server is required to handle transport between the SOAP service and the client. To make a call to SOAP service, client requests WSDL for that service. From WSDL, it forms SOAP request and send it to SOAP server. SOAP server forwards the request to relevant deployed service, the service processes the SOAP request and returns response to SOAP Server. SOAP server sends this response back to the SOAP client.

SOAP Message: This is the request sent by SOAP client to SOAP server. Its contents include name of SOAP service, operation to be invoked, and parameter values. This message is processed by SOAP service. A response message is generated by service and is sent back to client. Response message can also contain information about any errors (known as fault code and fault description).

Quickly building a SOAP Service using Visual C++ .Net
We will create a simple calculator web service, which will provide a method to add two numbers and return the result. (Some experience of ATL COM is assumed for these steps. Also it's assumed that Microsoft SOAP Toolkit 2.0 has been installed.)
  • Create a new Visual C++ Project
  • Select ATL Server Web Service from the project type list and name the project as "CalcService".
  • Click Ok
  • On project setting page, select deployment support and specify virtual root. For this example it will be "CalcService". (Note that IIS services must be installed on your machine for this step to work properly. Otherwise you will have to create virtual root on IIS manually and place the required files there)
  • Click Finish
It will create two projects "CalcService" and "CalcServiceIsapi".

"CalcService" is the main project, which will contain your web service methods. It will contain a "HellowWorld" method that is generated in default. Now we will add one more method "Add" ot this web service.
  • Open "CalcService.h" file
  • Modify the following part of code (Comments generated by Visual Studio have been removed to concentrate on the code only)
 __interface ICalcServiceService
 {
     [id(1)] HRESULT HelloWorld([in] BSTR bstrInput, [out, retval] BSTR *bstrOutput);
 };

Modified code is as following (note the bold lines)

 __interface IcalcServiceService
 {
     [id(1)] HRESULT HelloWorld([in] BSTR bstrInput, [out, retval] BSTR *bstrOutput);

     //Our Method
     [id(2)] HRESULT Add([in] long lVal1, [in] long lVal2, [out, retval] long* lResult);

 };

Add the following code under the public section of class "CCalcServiceService"

 [ soap_method ]
 HRESULT Add(long lVal1, long lVal2, long* lResult)
 {
     *lResult = lVal1 + lVal2;
     return S_OK;
 }
  • Now compile the project. It will generate all necessary files and deploy them to the virtual root (earlier specified in the project creation steps). The generated files will include CalcService.dll (the service), CalcServiceIsapi.dll (ISAPI extension), CalcService.disco (web service discovery file), and CalcService.htm (Welcome page).
  • Now open the following file in browser http://localhost/CalcService/CalcService.htm and click on "Service Description" Link. You will see WSDL generated for your Web service.
(Note: this source has been tested with Visual Studio .Net Beta 2. There is a problem that when you click on "Service Description" you receive Internal Server Error. It's due to wrong URL generation by Visual Studio .Net Beta2. You can correct the URL manually as following:

Open CalcService.htm file and change

<a href="http://localhost/CalcService/CalcService.dll?Handler=GenCalcServiceServiceWSDL" >

to

<a href="http://localhost/CalcService/CalcService.dll?Handler=GenCalcServiceWSDL" >

and Save the file and now you should get WSDL by clicking on the link.)


Following is a short description of different elements of the WSDL.

<message>: It defines the inputs and outputs for a method. Following is the part of WSDL for our "CalcService" service and it defines the parameters passed, and result returned.

 <message name="AddIn">
 <part name="lVal1" type="s:int" />
 <part name="lVal2" type="s:int" />
 </message>

 <message name="AddOut">
 <part name="return" type="s:int" />
 </message>

<portType>: The <portType> element identifies a set of operations and the messages involved with each of the operations. Following is a part of WSDL generated for our "CalcService" service, which shows the method "Add" and associated input and output messages.

 <portType name="CalcServiceServiceSoap">
 .....
 <operation name="Add">
 <input message="s0:AddIn" />
 <output message="s0:AddOut" />
 </operation>
 </portType>

<binding>: The <binding> element specifies the protocol details for various operations defined in the <portType> element. Each <binding> element has name and type attributes. The name attribute provides a unique name for this binding. The type attribute identifies the port type that it binds (defined earlier in the <portType> element)

 <binding name="CalcServiceServiceSoap" type="s0:CalcServiceServiceSoap">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc" />
 <operation name="Add"><soap:operation soapAction="#Add" style="rpc" />
 <input>
 <soap:body use="encoded" namespace="urn:CalcServiceService"
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
 </input>
 <output>
 <soap:body use="encoded" namespace="urn:CalcServiceService"
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
 </output>
 </operation>
 </binding>

<service>: The <service> element identifies a service (a group of related ports). Ports are grouped by using <port> element identifying each defined port. The <port> child element has two attributes and one child element. The name attribute provides a unique name to the port among all other defined ports in the WSDL document. The binding attribute refers to the binding specified earlier in the WSDL file. The <soap:address> element provides the address of the server-side Simple Object Access Protocol (SOAP) request handler. Following is the part of WSDL generated for our "CalcService" service.

 <service name="CalcServiceService">  <port name="CalcServiceServiceSoap" binding= "s0:CalcServiceServiceSoap">  
 <soap:addresslocation="http://localhost/CalcService/CalcService.dll?Handler=Default" />  </port>  </service>

(Note: Save this WSDL as "CalcService.wsdl" in the virtual root for "CalcSerivice" service. You will need this when calling "Add" method from our SOAP client.)

Creating a VB Script Client to test our service
  • Install Microsft SOAP Toolkit 2.0 or higher (downloadable from http://www.microsoft.com)
  • Create a new text file in notepad and write the following code in it.

 Option Explicit
 Dim soapClient
 'Create Soap Client
 set soapclient = CreateObject("MSSOAP.SoapClient")

 'Setup Error Handler
 On Error Resume Next

 'Initialize SOAP client by telling about WSDL file
 Call soapclient.mssoapinit("http://localhost/CalcService/CalcService.WSDL")

 if err <> 0 then
wscript.echo "initialization failed " + err.description
 end if

 'Call Method
 wscript.echo soapclient.Add(20, 30)

 if err <> 0 then
wscript.echo err.description
wscript.echo "faultcode=" + soapclient.faultcode
wscript.echo "faultstring=" + soapclient.faultstring
wscript.echo "faultactor=" + soapclient.faultactor
wscript.echo "detail=" + soapclient.detail
 end if
  • Save the file as "CalcService.vbs"
  • Run the file, result of the addition should be displayed in the message box.
Conclusion
SOAP is a new technology and building new standards for distributed computing. It also increases loose coupling as each web service is independently deployed and configured. This article discussed only web services deployed in web server like IIS, but web services can also be used within an application only by providing some SOAP request transport mechanism over some protocol like TCP, HTTP, etc.

Web Resources
Following link are resources of rich information about SOAP standards and helping material.
  • http://www.w3c.org
  • http://msdn.microsoft.com/soap
    Business Integration!
Web Services development is an effective solution towards business integration.

To know how your business can benefit from this, click here to contact us.
Company | Contact Us | Send Feedback
© 1998 - 2013 Future IT GmbH, All rights reserved.