perfectxml.com
 Basic Search  Advanced Search   
Topics Resources Free Library Software XML News About Us
  You are here: home Info Bank Articles » Microsoft and Web Services (SOAP) Saturday, 23 February 2008
 

Back to Articles Page      

        

Microsoft & Web Services (SOAP)

A review of Web Services support in various Microsoft products

http://www.perfectxml.com

Author: Darshan Singh (Managing Editor, PerfectXML)

Last Updated on: March 26, 2002 (Added text on Visual FoxPro 7 and Web Services)

 

In this article:

Abstract:

About seven years ago, Microsoft started adding support for COM (Component Object Model) in all their products. The developer tools from Microsoft facilitated easy creation and consumption of COM objects; various APIs were upgraded from standard Windows calls to COM object methods; the Microsoft Office Suite (Word, Excel, etc.) and Internet Explorer browser were made automation enabled; to that end that even SQL Server supported COM (remember sp_OACreate and SQL DMO?).

 

We are seeing the same era once again, but this time the focus is XML and Web services, instead of COM. The Microsoft .NET framework and languages, Office XP, and SQL Server 2000 all have support for SOAP and Web services. In addition, Microsoft has made additional APIs to work with XML (such as Microsoft XML Core Services or MSXML) and Web services (such as Microsoft SOAP Toolkit).

 

In this article, we'll look at SOAP and Web services support in various Microsoft products. We'll create Web services using .NET Framework, SOAP Toolkit, and SQLXML 3.0. Next, we'll look at writing Web services clients using C#, Microsoft SOAP Toolkit, Office XP Web Services Toolkit, and MSXML. At the end, we'll also learn about the Web Services support in FoxPro 7.0.

 

This article assumes some familiarity with SOAP, WSDL, .NET Framework, SQLXML, and Web services.

Writing Web Services

The Microsoft .NET Framework has excellent support for XML and Web services. The various namespaces provides classes that truly simplify and expedite the development of XML applications and Web services.

 

Let's start by looking at Web services support in .NET, and then we'll move to SOAP Toolkit and then finally to SQLXML 3.0.

Machine Info Web Service

The following Web service is written using C# syntax and it provides three methods, namely GetNetBIOSName, GetOSVersion, and GetDomainName; and these methods are precisely named after the kind of information they return.

 

Start Notepad and type (or copy-paste) the following lines of code:

 

<%@ WebService Language="C#" class="MachineInfo"%>

using System;

using System.Web.Services;

 

[WebService(Namespace="http://SomeNameSpace")]

public class MachineInfo: WebService

{

[WebMethod (Description="Returns the machine (NetBIOS) Name")]

public string GetNetBIOSName()

{

return Environment.MachineName;

}

 

[WebMethod (Description="Returns the OS Version")]

public string GetOSVersion()

{

return Environment.OSVersion.ToString();

}

 

[WebMethod (Description="Returns the Network Domain Name")]

public string GetDomainName()

{

return Environment.UserDomainName;

}

 

}

 

Save the above code as MachineInfo.asmx under any IIS virtual directory. Start Internet Explorer (or any browser) and type the URL for the above .asmx file and you should see a screen similar to:

 

Figure 1 MachineInfo Web service written as an .asmx file using C#

 

If you append the ?WSDL at the end of the above URL, or click on the Service Description link on the above page, you'll be able to see the WSDL (Web Services Description Language) document for the MachineInfo Web service.

 

To create the above Web service, we simply created an .asmx page that contained a C# class that derived from System.Web.Services.WebService. This class has public methods having WebMethod attribute, and the methods use the System.Environment class to return the respective machine information values.

 

In summary, we were able to create a Web service by just using Notepad and .NET Framework. But this is for very simple services such as above. For complex Web services, and to get the tool benefits such as to aid while debugging, context sensitive help, auto completion, and many such features, Microsoft offers Visual Studio .NET that has great support for creating and deploying Web services. Almost all Web services books and many .NET articles floating around, explain how to use .NET to create Web services. So, we'll not go into details of this. We encourage you to spend some time playing around with Visual Studio .NET and create Web services using it. Simply choose a new project of type ASP.NET Web service and (may be) copy the above methods and run the Web service.

 

In order to get maximum flexibility (and improved performance in some situations), another alternative would be to implement IHTTPHandler interface and use System.Xml classes to receive SOAP request, process it, build response payload and send it to the caller.

SOAP-enabling COM Objects

The previous section described how to create XML Web services from scratch. In this and the following section, we'll see how to enable the existing code as Web services methods. This section will focus on upgrading COM objects to Web services and in the next section, we'll see how to use SQL Server 2000 stored procedures as Web service methods.

 

The Microsoft SOAP Toolkit is freely available for download at MSDN download area. The current version 2.0 SP2 provides a low level and high level API to write Web services client; a server-side component to map Web service operations to COM object methods; components to work with SOAP messages; a tool to generate WSDL/WSML files from a COM DLL; and an API to process XML documents.

Windows NT Service Details

Let's say we have a COM object that has just one method named GetNTServiceDetails. This method returns the complete details about a Windows NT Service, given the name of the service as input parameter. To learn more about how to get the NT Service details, follow the KB Article Q189633 or download the code supplied with this article and review it. The code supplied with this article is the modified version of code sample from the KB article. We slightly updated the code to return the service details as an XML string instead of writing it to the list box form control.

 

Let's now use Microsoft SOAP Toolkit 2.0 SP2 to enable the above COM object as a Web service. Click Start | Programs | Microsoft SOAP Toolkit | WSDL Generator to start the SOAP Toolkit 2.0 Wizard. Click Next once, type the name of the service as NTServiceDetails and select the ActiveX DLL:

Figure 2 SOAP enabling our COM DLL that contains just one method, to return the Windows NT Service details, given the service name as parameter.

 

Our COM DLL has just one object having a single method. Select this single object to be exposed as a Web service:

Figure 3 Exposing the COM Object as a Web service

 

Click Next, and the following screen allows to chose the type of SOAP listener we want, the virtual directory where it will listen, and the XSD Schema namespace to use. Update the URI box to point to an existing IIS virtual directory, change the listener type to ASP, and click Next.

Figure 4 For simplicity, we'll choose ASP as the listener type. This will create an ASP page that uses SOAP Toolkit API to wrap the selected COM object methods.

 

The next screen allows selecting the WSDL file character set and the location where the files will be created. We'll keep the default settings (UTF-8) and click Next.

Figure 5 Selecting the WSDL Character set and location where new files will be created.

 

Click Finish on the next screen.

 

The above process creates three files; a .WSDL, .WSML, and an .asp page. The .WSDL file is the RPC-Encoded style description of the Web service that wraps our COM object. The WSDL file can be used by any client to bind to our Web service, and get more information about the services and methods offered.

 

The .WSML file is Microsoft proprietary format to map service operations to COM object methods, and is used only by the SOAP toolkit.

 

The generated .asp page contains the VBScript code that uses high-level SOAP API (the SoapServer and SoapSerializer classes) to process the SOAP request, call the COM object method, and generate the SOAP response.

Figure 6 the .WSDL file generates by the SOAP Toolkit

 

We'll soon see an example of a client application that accesses above Web service. For now, let's move on to a very interesting feature of SQLXML (XML for SQL Server 2000) 3.0.

 

Stored Procedures to Web service methods, in seconds!

Microsoft recently announced SQLXML 3.0 Beta 1 that introduces the Web services (SOAP) support in SQL Server 2000. It allows the stored procedures or user defined functions (UDFs) or XML templates to be readily exposed as Web service methods.

 

Let's assume that we already have a SQLXML virtual directory (named NorthwindVirDir) configured using SQLXML "Configure IIS Support" (also known as IIS Virtual Directory Management for SQLXML) tool; and this virtual directory is pointing to Northwind database.

 

To enable any stored procedure present in the Northwind database, here is the procedure that we'll follow:

 

*      Open the NorthwindVirDir properties window and click on Virtual Names tab. Create a new virtual name of type soap:

Figure 7 Creating a new SQLXML virtual name of type soap

 

*      Once you save the above virtual name, the Configure button will be enabled, click on this button to select the stored procedures or UDFs that we want to publish as Web service methods.

Figure 8 First click on the ellipses next to the SP/Template box and select any stored procedure that you wish to expose as a Web service method.

 

Click on the Save button and then on OK button twice to close the virtual directory property dialog box.

 

The above steps create two files; a document-literal encoded .wsdl file and an .ssc file that contains the soap virtual name configuration details.

Figure 9 The .wsdl file created by SQLXML3.0 soap virtual name configuration tool.

Once again, any Web service client can now bind to the above WSDL file and use the http://ServerName/NorthwindVirDir/WebSvcs URI to post the SOAP messages, which in turn will call the SQL Server stored procedure and return the results as an XML string.

 

Writing Web Service Clients

So far we just look at how to create the Web services, let's now spend some time looking at how to consume these Web services. We'll start with a very simple example of using Microsoft Visual Studio .NET and create a Web service client to our NTServiceDetails Web service (created earlier using SOAP Toolkit).

Using Visual Studio .NET

To allow writing COM clients (using early binding), Visual Basic provided an ability to add reference (Project | References) to the ActiveX DLL. Similarly, Visual Basic .NET (and C#) provides ability to add reference to .NET Framework assemblies and also to COM DLLs. In addition to this, they also support adding a Web Reference and early binding to a Web service. Adding a Web reference involves pointing to a .wsdl file, and it generates a proxy code based on the .wsdl file that then allows us to use the Web service as any other class.

 

Let's write a tiny Visual Basic .NET console application that uses the NTServiceDetails Web service that we created earlier:

 

  1. Start Visual Studio .NET, create a new project of type Visual Basic .NET console application.
  2. Click on Project | Add Web Reference and type the WSDL URL pointing to NTServiceDetails Web service:

Figure 10 Adding Web Reference to the NTServiceDetails Web service.

  1. Click on Add Reference. Adding a Web reference creates a proxy class derived from System.Web.Services.Protocols.SoapHttpClientProtocol. We'll rename the namespace from localhost to SvcDetails:

Figure 11 Renaming the namespace from localhost to SvcDetails.

 

  1. Write the imports statement at the top of Module1.vb:

Imports NTSvcDetailsWebSvcClient.SvcDetails

 

  1. Write the following code under Sub Main()

Sub Main()

Dim SvcDetailsObj As New NTServiceDetails()

Console.WriteLine( _

SvcDetailsObj.GetNTServiceDetails("MSSQLServer"))

Console.WriteLine(vbNewLine)

Console.WriteLine( _

SvcDetailsObj.GetNTServiceDetails("W3SVC"))

Console.WriteLine("Press ENTER to continue...")

Console.ReadLine()

End Sub

 

  1. Here is the output produced by the above Web service client code:

Figure 12 The output produced by NTServiceDetails Web service client application.

 

Once we add the Web reference, the generated proxy class allows us to use Web service as any other .NET framework class simply instantiate an object of the class and call methods on it, without worrying about packaging and un-packaging SOAP payloads.

 

In summary, the .NET Framework is very well designed to permit creating and using the Web services in a simplest possible manner.

 

Let's now see how to use SOAP Toolkit to write the Web service client applications.

 

Using SOAP Toolkit to Invoke Web Service Methods

The SOAP Toolkit provides high-level and low-level API to consume Web services. The use of high-level API simply involves instantiating the MSSOAP.SoapClient.1 object and calling the mssoapinit method on it passing the .wsdl URL. Once this is done, we can then call the Web service exposed methods directly using the SOAPClient instance.

 

Let's write a Web service client application using SOAP Toolkit; we'll use the MachineInfo Web service that we created (using C# .NET) at the beginning of this article.

 

Start Visual Basic 6.0, create a standard EXE project, add reference (Project | References) to Microsoft SOAP Type Library (MSSOAP1.dll), double click on the form and write following code under the Form_Load method:

 

Dim objSOAPClient As New soapClient

 

On Error Resume Next

 

objSOAPClient.mssoapinit _

"http://localhost/mywebsvcs/machineinfo.asmx?wsdl"

 

If Err <> 0 Then

Debug.Print "Initialization Failed: " & Err.Description

End If

 

Debug.Print objSOAPClient.GetNetBIOSName()

Debug.Print objSOAPClient.GetOSVersion()

Debug.Print objSOAPClient.GetDomainName()

 

The above code lines first create an instance of SOAPClient class and then call mssoapinit method on it passing the MachineInfo Web service WSDL URL. This initialization logic prepares the SOAPClient instance using the WSDL, so that we can then directly call the Web service methods using the SOAPClient instance. That's what we do next, and call GetNetBIOSName, GetOSVersion, and GetDomainName Web service methods.

Using Office XP Web Services Toolkit

Recently Microsoft released the Office XP Web Services Toolkit. The important part of this toolkit is the Web Services Reference tool that can be used from within the VBA (Visual Basic for Applications) Editor and point to a Web service using either directly typing the WSDL URL or using the UDDI (Universal Description, Discovery, and Integration Business Registry).

 

Once you install the toolkit, it allows you to add a reference to any Web service and then use that Web service from within your Office XP VBA code. For instance, you may write a Word document or an excel file that whenever opened, talks to a Web service, gets some data and fills (or updates) some part of the document or worksheet.

 

Install the Office XP Web Services Toolkit and now open either Word or Excel and press Alt+F11 to start the Visual Basic Editor. Click on Tools and you should see a new item added there titled Web Services Reference.

 

Figure 13 The new Web Service Reference menu item added by the Office XP Web Services Toolkit allows referring to WSDL URL or using UDDI and point to a Web service, and then write the Web service client code in VBA.

 

The Web Service Reference dialog box allows searching for a Web service using UDDI, either via keyword search or searching based on any business name. Or simply, we can directly point it to a WSDL document and it will list the services and methods offered. We'll once again use the MachineInfo Web service here. So, select the Web Service URL radio button and type the WSDL location URL and click Search. It will populate the Search Results as shown below, select the MachineInfo check box on right and click on Add button.

 

Figure 14 Adding a Web Service Reference to our MachineInfo Web service

 

By adding the Web Reference, It creates a new class module named clsws_MachineInfo that simply uses the SOAP Toolkit to call the Web service methods. Now we can use this clsws_MachineInfo class in our VBA applications and call Web service methods.

 

For instance, if we write the following code in the Document_Open method:

Private Sub Document_Open()

Dim WSObj As New clsws_MachineInfo

MsgBox WSObj.wsm_GetNetBIOSName()

MsgBox WSObj.wsm_GetOSVersion()

MsgBox WSObj.wsm_GetDomainName()

End Sub

 

Every time now we open this Word document, it will call the Web service methods and display the results in a message box.

 

In summary, the Office XP Web Services Toolkit simplifies calling the Web services from VBA code inside XP documents.

Using MSXML 4.0 to call Web Services

MSXML (now known as Microsoft XML Core Services) contains two classes that allow HTTP access: XMLHTTP and ServerXMLHTTP. XMLHTTP, based on WinInet is designed for client side HTTP access, while ServerXMLHTTP is designed based on WinHTTP, and is well suited for server-side HTTP access.

 

On the client side, we can use WinHTTP to call Web services; and on the server side, we may use ServerXMLHTTP to invoke Web service methods. We'll not present any example of this and leave it as an exercise for you. The recently published book, XML Application Development with MSXML 4.0 shows couple of examples on using XMLHTTP and ServerXMLHTTP to call Web services.

Visual FoxPro 7 and Web Services

Earlier in this article, we saw that the Web Services support in Microsoft Excel 2002 was made possible by using the Microsoft SOAP Toolkit. Similarly, Microsoft Visual FoxPro 7.0 provides a set of extensions to the Microsoft SOAP Toolkit 2.0 to simplify use of Web Services in our applications. These extensions are available through a set of foundation classes(_webservices.vcx).

The Web Services support in Visual FoxPro 7.0 allows you to:

  • Create and publish Web Services based on the COM objects (classes built as OLEPUBLIC). Creating and publishing Web services requires IIS 5.0 or above.
  • Writing the Web Service Clients

We'll not discuss creating the COM Server and wrapping them as Web Services in Visual FoxPro.
Click here to learn more about creating and publishing Web Services using FoxPro.

Let's now look at how to consume the Web Services in FoxPro. In this example, we'll connect to the SalesRankNPrice Web service.

The first step in writing the client is to register the Web service with the IntelliSense Manager. This allows declaring the strongly typed variables of types from the Web Service and also provides the IntelliSense support when we access the registered Web Service.

Start Visual FoxPro 7.0, click on Tools | IntelliSense Manager, Click on Types tab and then click on the Web Service... button:



This brings up the Visual FoxPro Web Services Registration dialog box. Let's give SRNP (for SalesRankNPrice) as the the Web Service Name and type http://www.PerfectXML.net/WebServices/SalesRankNPrice/BookService.asmx?wsdl as the WSDL URL Location.



Next Type, Modify Command in the FoxPro Command Window to write a new program. In the code editor window, type LOCAL WSObj As.

As soon as you type the above variable declaration text, the IntelliSense will bring the list of types, which will also include the type SRNP, select that.



Once you select SRNP as the variable type, this inserts the following code in the editor:

LOCAL WSObj as SRNP

LOCAL loWS

loWS = NEWOBJECT("Wsclient",HOME()+"ffc\_webservices.vcx")

loWS.cWSName = "SRNP"

WSObj = loWS.SetupClient ;
  ("http://www.PerfectXML.net/WebServices/SalesRankNPrice/BookService.asmx?wsdl", ;
  "SalesRankNPrice", ;
  "SalesRankNPriceSoap")
Note that we have added the line spacings and semicolon line continuation characters in the above code for better readability.

The above code makes use of the _webservices.vcx class library (and hence SOAP Toolkit). Now as we type WSObj. in the code editor, the IntelliSense will list all the Web methods that the Web Service supports. Let's try a method (GetAll) that returns a IXMLDOMNodeList (list of nodes).

Declare a variable named RetData of type Object after the WSObj declaration line and write the following lines at the end:

RetData = WSObj.GetAll("186100589X")

?"Amazon SalesRank is: " + RetData.Item(0).nodeTypedValue
?"Amazon Price is: " + RetData.Item(1).nodeTypedValue
?"B&N SalesRank is: " + RetData.Item(2).nodeTypedValue
?"B&N Price is: " + RetData.Item(3).nodeTypedValue
So the complete code looks like:

Run the program and you should see the results in the output window. For more information visit MSDN FoxPro site.

Summary

In this article, we talked about Web services support in various Microsoft products. We started with a brief introduction, and then created Web services using .NET Framework, SOAP Toolkit and SQLXML 3.0. The second part then focused on writing Web services clients. We saw an example each of writing Web service client using .NET Framework, SOAP Toolkit, Office XP Web Services Toolkit and MSXML 4.0. And finally, we looked at the Web Services support in Microsoft FoxPro 7.0.

Send any questions/comments to author of this article, Darshan Singh at darshan@perfectxml.com.


This article in PDF format This article as a Microsoft Word Document Source Code for this article

  

Back to Articles Page      

  Contact Us | E-mail Us | Site Guide | About PerfectXML | Advertise ©2004 perfectxml.com. All rights reserved. | Privacy