|
Figure 1 – The Microsoft Toolkit relies on a Service Description to provide type information both to the client and the server applications accessing the 'Web Service'. Based on the type information SOAP messages are created and passed over the wire. The SDL is implementation specific, but is not required as long as the server receives a valid SOAP request from the client and the client receives a valid SOAP response from the server. Here's how it works: The process is started by creating a Web Service on the server. To help with this process an SDL Wizard is provided which can create a Web Service template from an existing COM object. Let's say we have a COM DLL SoapDemo with a SoapServer class and a HelloWorld method to match Figure 1. The Wizard generates the SDL file as well as a wrapper ASP page that calls the COM component. The ASP page references a library ASP page that knows how to process the SOAP request and pass the call on to the method in the generated ASP file. The actual method does nothing more than a CreateObject followed by a call to the method with the parameters and returning that value back to the listener. The client application initiates a Web Service request by downloading the SDL file. The SDL file is then passed to the Proxy object, which uses it to create the SOAP package that is put onto the wire and transferred to the server. The ROPE.DLL provides both the SOAP encoding/decoding functionality (SOAPPackager methods) as well as the ability to make HTTP calls to the server (WireTransfer component). The SOAP request is then sent to the server for processing. Note that the actual SOAP request is the key piece here – the server won't care how the SOAP package was created as long as it is in the right format. So, you can manually create the appropriate XML via code, or you could have a non-Windows client create that message. The server doesn't care and happily processes the message. The code on the server fires the ASP file the Wizard generated which has the name of the class – SoapServer.asp. The ASP page includes Listener.asp which is a library file that contains the code that uses ROPE.DLL to process the incoming SOAP message, route the request to the function in SoapServer.asp, and then package up the result value into a response SOAP package. The server also uses the SDL file to validate the parameters the client passed as well as the result value that the listener function returns. The call to the function is made, The actual function merely instantiates the COM object, calls the method and returns the value to the listener code. The listener, checks the return value and if it doesn't match the type in the SDL file, creates an error response package. If it does match a Result SOAP package is sent back to the client. The client now picks up the SOAP message as part of the Proxy's operation to make the SOAP call. Behind the scenes the Proxy object is making an HTTP POST request against the server using the WireTransfer component posting the SOAP request and retrieving the SOAP response in a single HTTP operation. Once the result comes back the result is unbundled in a value that's properly typed and returned to the client application. The SOAP toolkit supports both high level and low-level methods for calling server side code, with the high-level methods taking about 10 lines, while the low level takes about 25. It's relatively easy to get up and running as we'll see in a minute. The MS SOAP toolkit doesn't support all of the supported SOAP datatypes. In fact you're limited to the following types as parameters and return values:
Notably you can't return objects, which makes sense in this context. (Note: .Net's Web Services can return persisted objects). Note that date values are also not explicitly supported – you can pass and return dates only as strings. There are few additional restrictions on the these types: They must be XML compliant to the point that they can live in a regular element tag. If strings contain other XML (especially XML containing CDATA content) or extended ANSI characters the SOAP call will fail. You'll get 'Bad SOAP return' errors. I'll talk about some workarounds for this later. Installation of the ToolkitThe toolkit comes with an install program, but the install program
doesn't set you up for running any of the demos as it simply copies the
files to the directory specified. Once installed you need to do the
following to run the samples:
A few tips if you have problems: Read the help file's trouble shooting section! It's quite good. Additionally the server side code generates an error log file in c:\webservices by default, which contains the error log file. The messages there aren't always clear, but they will most likely point you in the right direction. Once you've configured the server pieces you can run the sample VB program in the samples/client directory. The sample calls server side code in a variety of different ways which is useful to see the different ways you can handle the SOAP messaging. If you don't like looking at VB code – or even if you do – read on for VFP examples. |
