Microsoft and Web Services (SOAP)

Microsoft & Web Services (SOAP)
A review of Web Services support in various Microsoft products
http://www.PerfectXML.com
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:
http://www.PerfectXML.com
1
<%@ 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.
http://www.PerfectXML.com
2
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:
http://www.PerfectXML.com
3
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.
http://www.PerfectXML.com
4
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.
http://www.PerfectXML.com
5
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:
http://www.PerfectXML.com
6
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.
http://www.PerfectXML.com
7
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:
http://www.PerfectXML.com
8
Figure 10 – Adding Web Reference to the NTServiceDetails Web service.
3. 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.
4. Write the imports statement at the top of Module1.vb:
Imports NTSvcDetailsWebSvcClient.SvcDetails
5. Write the following code under Sub Main()
Sub Main()
Dim SvcDetailsObj As New NTServiceDetails()
Console.WriteLine( _
SvcDetailsObj.GetNTServiceDetails("MSSQLServer"))
Console.WriteLine(vbNewLine)
Console.WriteLine( _
http://www.PerfectXML.com
9
SvcDetailsObj.GetNTServiceDetails("W3SVC"))
Console.WriteLine("Press ENTER to continue...")
Console.ReadLine()
End Sub
6. 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:
http://www.PerfectXML.com
10
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.
http://www.PerfectXML.com
11
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.
http://www.PerfectXML.com
12
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.
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.
http://www.PerfectXML.com
13