Microsoft & Web Services (SOAP)

Microsoft & Web Services (SOAP)

A review of Web Services support in various Microsoft products

Author: Darshan Singh (Managing Editor, PerfectXML)

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.

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="
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 Q189633or 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 SOAPAPI (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 1that 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 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 thencall the Web service exposed methods directly usingthe SOAPClientinstance.

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 _
"
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 SubDocument_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.