This article may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. To maintain the flow of the article, we've left these URLs in the text, but disabled the links.
.gif)
Develop a Web Service: Up and Running with the SOAP Toolkit for Visual Studio |
||||
| Rob Caron | ||||
|
||||
he new Simple Object Access Protocol (SOAP) Toolkit for Visual Studio® 6.0 gives developers the infrastructure and tools they need to integrate SOAP-based Web services into their client and server applications. In this article, I'll demonstrate these tools with a sample Web service for consumption by SOAP-compliant Web service clients. Tools for Web Services DevelopmentThe Microsoft® SOAP Toolkit complies with most of the SOAP version 1.1 specification, and the SOAP Toolkit team is working to bring the toolkit into full compliance. While the SOAP Toolkit greatly simplifies developing and consuming Web services using standards-based programming guidelines, the next version of Visual Studio will further ease the process. Microsoft is very committed to supporting the SOAP standard in its future technologies and developer tools. The SOAP Toolkit includes the Remote Object Proxy Engine (ROPE), the Service Description and Code Generation Wizard, and code for two reference implementations of a SOAP listener.ROPE is a DLL that provides the core functionality and infrastructure for Web service development and implementation using a familiar programming paradigm. I'll describe the ROPE object model later. The Service Description and Code Generation Wizard automatically generates everything needed on the server, including the service description files (defined later) which provide functionality that's both specific to the Web service being created and generic to any Web service. Additional required files are also included with the SOAP Toolkit and are copied to the appropriate directory when you use the wizard. Two implementations of a SOAP listener, including source code, are provided in the SOAP Toolkit. One implementation is written as an ASP script, while the other is a custom-built ISAPI extension. The SOAP listener provides a point of entry for clients to access the Web service. I'll demonstrate the use of both implementations in this article. The ROPE Object ModelThe ROPE object model (see Figure 1) consists of two primary objects that programmers can use to implement and use SOAP Web services: Proxy and SOAPPackager. The sample app will show how these objects can be used.The Proxy object allows a client to access a Web service as if it were a local COM object, which lets any COM-enabled language easily access the Web service. Once the Proxy has been educated about a particular Web service by loading the service description file, all of the published methods of that Web service are made available to the client application. While the Proxy object enables a late-bound programming model (since the service description was loaded at runtime), it is technically possible to load the service description at design time and generate wrapper classes that encapsulate the Proxy object to provide an early-bound programming model. However, the SOAP Toolkit only provides the late-bound model. Using this object alone, a developer can construct a SOAP Web service client. The SOAPPackager object offers a lower-level programming model for handling SOAP messages. Typically, the SOAPPackager object is used on the server side and under the covers on the client sideâ€"although you might occasionally use the SOAPPackager object on the client side, for example, to access SOAP message headers. This object may also be used on the client side as a programming model for processing incoming and outgoing SOAP messages. Its methods enable fine control of the packaging and unpackaging of SOAP messages at the expense of some added complexity. However, this level of control allows you to work programmatically with the individual pieces of a SOAP message. Incidentally, the Proxy object uses the SOAPPackager object to handle its SOAP message processing. The SOAPPackager object extends the ROPE object model with four additional objects: ServiceDescriptors, SDEndPointInfo, SDMethodInfo, and SDParameterInfo. The ServiceDescriptors collection object gives you programmatic access to the individual elements of the service description, such as the SOAP listener locations, methods, and method parameters. ServiceDescriptors can contain a collection of either SDMethodInfo or SDEndPointInfo objects, depending upon which was requested from the SOAPPackager object when the collection object was created. The service description must be loaded by the SOAPPackager object to supply the information contained in these objects. SDMethodInfo objects are used to map SOAP messages to object method calls, which can then provide RPC functionality on top of SOAP messages. An SDMethodInfo object exposes the parameters of the method for which it is providing information using a SAFEARRAY. The elements in the SAFEARRAY can represent the order of parameters in a method signature if that is what you request. In this case, ROPE will use the parameter order specified in the service description, or if the parameter order is not specified, ROPE will place them in an order following an algorithm specified in the ROPE API. Each parameter is accessed using an SDParameterInfo object, which only describes the characteristics of the parameter such as the direction (in only, out only, or both), data type, and parameter nameâ€"not the value of the parameter. SDEndPointInfo objects expose a single property that returns the URI of their associated SOAP endpoint. The ROPE object model is supplemented by a WireTransfer utility object. WireTransfer is a helper object that can execute HTTP POST and GET actions for SOAP Web services. This object is built on top of Winsock and is designed to be highly scalable. The Service Description and Code Generation WizardThe Service Description and Code Generation Wizard generates several customized files to simplify Web service development. Creating these files using the SOAP Toolkit wizard instead of authoring them by hand ensures that the resulting files will comply with the SOAP 1.1 specification.The key file that is generated is a description of the Web service. It contains XML elements that contain information such as the URL of the service, references to schemas that define the format of messages, and the capabilities of the service. A Web service uses this file to advertise its features. This file is used in turn by consumers of the service to understand how to interact with it. However, the service description does not reveal how the service is actually implemented. You'll see an example of a service description in my sample later on. The wizard is designed to generate files for COM components. Other service implementations, such as ASP scripts, require the schema to be written by hand to describe the service. The SOAP listener is the SOAP message processor. It provides the SOAP functionality for the Web service. Its address is the one referred to in the service description for calling the Web service. Using the wizard, the SOAP listener can be implemented as an ASP file, an ISAPI extension, or a custom-built listener. The ASP file generated by the wizard contains methods that act as interfaces to the COM component providing the Web service. Implementing the endpoint as an ISAPI extension solution is discussed later. Implementation OptionsThe easiest way to implement and test a SOAP listener for a Web service is to use ASP to interact with an existing application, such as making a method call to a COM object. This solution allows you a great deal of freedom in writing code that is executed both before and after the method in the COM object is called. Later, if you want better performance for services based on a COM component, you can use the toolkit's ISAPI SOAP listener solution. Once the Web service has been implemented via ISAPI, calls to the Web service will be sent directly to the target COM component. You can't insert custom code before or after the component is called. If you need to add custom code, one option is to write another COM object that the ISAPI listener will invoke so that the COM object can call the original COM object as well as execute custom codeâ€"or you can write your own custom ISAPI extension using the source code for the toolkit's ISAPI extension, which is included. With ROPE, you can develop custom SOAP listener implementations, or simply modify the ones provided to suit your requirements.Since the provided SOAP listener implementations were designed to handle a broad set of circumstances, you may want to replace these pieces with code that has been optimized for your own Web service. Developing a Web ServiceIt is possible to develop a Web service from scratch and write all the code necessary to process SOAP messages without using the SOAP Toolkit, but the time it would take would be better invested in developing the actual service functionality. The SOAP Toolkit provides the infrastructure to support SOAP-compliant Web services in much the same way that Microsoft Internet Information Services (IIS) and ASP provide the infrastructure for building Web applications.To build a SOAP-compliant Web service, you need some functionality that constitutes the service, a service description that defines how to use the service, and an infrastructure to support sending, receiving, and processing SOAP messages. I'm going to build a sample Web service on top of a sample COM component that calculates sales tax for an e-commerce site. This Web service is for illustration purposes only; a real sales tax Web service would have to take into consideration factors such as local sales tax as determined by ZIP code. The core functionality of the code is a COM component called SalesTaxRates that was written in Microsoft Visual Basic® 6.0. The functions implemented in the rates.cls file are shown in Figure 2. For simplicity, this component references data that is stored in an ActiveX® Data Objects (ADO) recordset, which has been persisted as a static XML file, StateTaxRatesRS.xml. The SalesTaxRates component implements three public functions on the USStateRates interface: GetTaxRateForState, GetStateTaxAmt, and GetStateTaxRates. GetTaxRateForState returns the current tax rate for a given state; GetStateTaxAmt calculates the sales tax for a given state and a given taxable sale amount; and GetStateTaxRates function returns an ADO 2.5 recordset that has been persisted as XML and that contains the state tax rates for all 50 states.
To simplify deployment and minimize recompilation, the full path to the XML file is passed to the component upon activation as a constructor string. This is accomplished by creating a COM+ application from the DLL in Windows® 2000 Component Services (see Figure 3). The constructor string assigns the file's physical path to a parameter named XMLFilePath. Whenever this object is created, the constructor string is parsed to determine the location of the XML file. Running the WizardNext, I'll need a SOAP listener to process service requests and a service description to define what the service does. To expose the functionality of this DLL as a Web service, I'll use the wizard provided in the SOAP Toolkit to generate files. These files will be used in conjunction with files provided in the SOAP Toolkit to implement the common SOAP functionality.Walking through the steps of the wizard, I must first indicate the COM DLL from which to generate the needed files. The wizard will then interrogate the type library to determine which methods are available on the exposed interfaces. The next step is to select which methods of the DLL I'd like to expose as part of the Web service. If you run the wizard, you'll see that one method, GetStateTaxAmt, is displayed in red. The SOAP Toolkit only supports a subset of those data types shown in Figure 4 that are supported by XML Data Reduced (XDR), which correspond to the namespace URI https://www.w3.org/1999/XMLSchema.dtd/datatypes. This method appears in red because the data type of one of its parameters and of the returned value is the Visual Basic currency data type, which is not supported. By default, the wizard will change all unsupported data types to strings in the files it generates. However, the service description can be edited, as you will see later, to change the specified data type to one of the other data types supported by the SOAP Toolkit. Any methods that have not been selected will not be exposed in the service description. After selecting the methods to expose as a Web service, I then need to tell the wizard what the address of the endpoint URI will be. This location is a directory on a Web site to which the service will be deployed. Should this location change, it is a simple matter of editing two lines of code to relocate the service: the address of the endpoint URI in the service description file and the address of the service description file in the endpoint URI. Later, I'll implement the service as an ISAPI solution, but for now I'll go with the default solution, ASP. The final step of the wizard is to select the location to which the newly generated files will be saved. This is just a working directory in which these files can be placed. Later, I'll upload these files to the appropriate Web server. After completing the wizard, the files are generated and saved to the location I specified. The wizard automatically copies the additional required toolkit files to the same location as the generated files. The Wizard-generated FilesThe XML file that was automatically generated, USStateRates.xml (see Figure 5), is a schema that describes key information about the Web service. The SOAP element of the schema defines which methods are available from the Web service and the address of the SOAP endpoint to which SOAP request messages for these services should be directed. At the bottom of the file is a schema that further defines the syntax of a SOAP message for both requests and their responses as they apply to my service. Both the Web service server and the Web service client use this XML file to understand the expected flow and content of SOAP messages.The ASP file that was automatically generated, USStateRates.asp (see Figure 6), contains functions in the ASP script with signatures similar to the methods that were chosen in the wizard. In addition, the wizard has inserted code in each of these functions that will create an instance of the SalesTaxRates component and call the prescribed function with the provided parameters. I should make two modifications to this service before it's ready for consumption. First, as I pointed out earlier, the GetStateTaxAmt function as defined in the service description file has been decremented to accept a string value from the SOAP client in lieu of the unsupported currency value that the actual DLL function is expecting. To compensate for this I could add some custom code in the ASP script to test the string to see if it is a valid currency value. If the test fails, I could then return an error message to the calling Web service client. Or, since this parameter is passed by value to the method in the DLL, I could rely on the scripting engine to perform this conversion. For the purpose of the sample, I'll just go with the latter. Second, the GetStateTaxRates function returns an ADO 2.5 recordset that has been persisted as an XML string. Since a SOAP message is constructed using XML, I should place this function's return data inside a CDATA section to make sure the SOAPPackager object does not attempt to parse this XML. This avoids the problem of invalid XML causing an XML parsing error in the SOAPPackager object. The SOAPPackager object provides a simple function to accomplish this task, CDATAize. Now that all the files have been assembled, the final step in developing this Web service is to deploy it to my Web server. The following six files need to be deployed:
Consuming a Web ServiceSince the decentralized nature of SOAP enables both the sender and receiver of a SOAP message to function as autonomous units, there are countless ways to consume a Web service. For example, a call to a Web service can be included in an ASP script or called from within a middleware component. No matter what form the SOAP client may take, all that's needed to call a SOAP-compliant Web service is to send a SOAP request message that conforms to the published service description. Here, I accessed the Web service from ASP scripts.I created three ASP files that are called from a simple HTML page, index.htm (see Figure 7), to exercise each of the methods of the service. The sample ASP files employ different methods to consume the Web service to demonstrate ROPE's capabilities. GetTaxRateForState.asp (see Figure 8) and GetStateTaxRates.asp (see Figure 9) use the simple programming model of the Proxy object. GetStateTaxAmt.asp (see Figure 10) uses the more complex programming model of the SOAPPackager object. With ROPE handling the details, consuming a Web service is rather trivial using the Proxy object. The following is a step-by-step demonstration of what happens when the client requests the state sales tax rate for the state of Washington (WA) using the Proxy object as illustrated in Figure 11. The process starts with the Web service client:
An ISAPI SolutionAfter testing the Web service and making sure it works properly, you may want to improve its performance by implementing the SOAP listener as an ISAPI solution. To do so, simply run the wizard once more and select ISAPI instead of ASP. The wizard generates the two files again. Instead of the ASP file that was previously generated, an SOD file will be created. This is a file that contains a simple XML document having a single XML element with two attributes, ProgID and SchemaLoc. ProgID, as you'd expect, is the ProgID of the Web service component. SchemaLoc is the physical path to the service description file.Just like the service description in the ASP solution described earlier, this service description will have an element called location with an attribute named URL that will point to the location of the SOAP listener. This time, the address of the SOAP listener points to an SOD file instead of an ASP file. The ISAPI extension that comes with the SOAP Toolkit will intercept calls to the Web server for files with an extension of .sod, and will recognize these calls as SOAP Web service requests. The ISAPI extension will then reference the SOD file and the service description for information pertaining to the Web service. The following six files need to be deployed to the Web server:
ConclusionThe sample here and the additional tools, code, documentation, and samples in the new SOAP Toolkit allow you to focus your efforts on developing and consuming SOAP-compliant Web services rather than on developing the SOAP infrastructure underneath. |
||||
| For related articles see: "A Young Person's Guide to the Simple Object Access Protocol" https://www.w3.org/TR/SOAP Professional XML, "Chapter 18 - Case Study 4â€"SOAP"by Jonathan Pinnock et. al. (Wrox Press, 2000) |
||||
| Rob Caron is a programmer/writer working on the Visual Studio team at Microsoft. A former nuclear engineer, he now limits his physics projects to testing the laws of gravity by skydiving. He can be reached at robcaron@microsoft.com. |
||||
.gif){kind=small}
.gif)
From the August 2000 issue of MSDN Magazine.