Using Visual FoxPro to call .NET Web Services for Data Access

Required Tools:

• Visual FoxPro 8 or later
• Microsoft SOAP Toolkit Version 3.0 or later
• Microsoft .NET Framework 1.1 or later
• SQL Server or MSDE with the Pubs Database accessible
• Visual Studio.NET 2003

Prerequisites:

• Intermediate Visual FoxPro
• Beginning .NET
• Familiar with the SOAP Toolkit

Using Web Services from Visual FoxPro is not difficult, but dealing with Data or Complex objects is not quite as straightforward as it could be. In this article, I’ll describe how you can work with .NET Web Services and pass complex data between VFP and .NET and handle updating scenarios for Data between the two.

Accessing Web Services from Visual FoxPro is nothing new. But effectively leveraging Web Services and interacting with them especially when dealing with .NET requires a more complete understanding of the mechanics and the tools available to Visual FoxPro developers, than merely creating the service and firing off method calls

Using the SOAP Toolkit from VFP is straightforward and calling .NET Services is no different than calling any other service. But things get sticky when we’re not running simple ‘Hello World’ type examples that return little more than simple types. The issues involved here deal with the fact that the SOAP Toolkit and most other tools SOAP Tools available to Visual FoxPro are woefully under-equipped to effectively passes and translate complex types.

In this article I’ll specifically look at passing DataSets and objects between Visual FoxPro and a .NET Web Service and demonstrate how the simple call model falls apart quickly when using complex types and datasets. It’s not difficult to work around these issues, but you as the Visual FoxPro developer has to realize that there will be extra work and likely some manual XML parsing to make this happen.

In this article I’ll keep things pretty simple from an application point of view to demonstrate the Infrastructure mechanics. I’m going to skip over some architectural issues such as business object usage and defer that to the simple business object that is included in the source, but realize that these same principles also work with more complex data scenarios that involve multiple tables or hierarchical objects. To follow along with this article you’ll need Visual FoxPro 8 (or later), Microsoft .NET 1.1, Microsoft IIS and SQL Server or MSDE with the Pubs Sample Database installed.

Calling .NET Web Services from VFP

Let’s start with a quick review on how to create a .NET Web Service and call it from Visual FoxPro. I’m going to use visual Studio to do this, but you can also do this without it, but you will have to manually create the project and virtual directories and compile your Web Service and support files. You can check the .NET framework documentation on how to do this.

Start by creating a new Web Service project. I call mine FoxWebServiceInterop:

1.      Start the File | New | Project and select new Visual C# Sharp Project.

2.      Select Web Service and type in your project name and Web Server path. Figure 1 shows this dialog.

Figure 1 – The new project dialog creates a new VS.NET Solution and project and creates a virtual directory on your local IIS Web Server to host it.

The New Project then proceeds to create your solution and project by creating a virtual directory on your Web Server and copying a default web.config file and global.asax file which are application specific files that are required for any Web application – a .NET Web Service is really little more than a specialized Web application. In fact if you later choose to add ASP. Net Web Forms they can run out of this same directory as well.

The first thing I usually do to any ASP. Net or Web Service project is remove the WebService1.asmx page and instead create a new one with a proper name called FoxInteropService.asmx. In Figure 1 I also added a new folder to project and stuck into a few support classes that I will use later on to handle data access. This is optional of course, but it’s a good idea to organize your projects as soon as you start adding files to the project.

So now we’re ready to create our Web Service logic. Let’s start very simple with the mandatory Hello World example. Open the FoxInteropService.asmx page in Code View and add the following code (or modify the default commented out HelloWorld method) to:

Go ahead and compile the code. Assuming the code compiled you can now test the Web Service interactively by accessing the Web Service ASMX page through a browser with:

http://localhost/FoxWebServiceInterop/FoxInteropService.asmx

This handy test page allows you to quickly see the methods available and for the most part lets you test the Web Service functionality through a simplified non-SOAP interface. Make sure that you can test the Service through this interface first.

Next let’s access the service from Visual FoxPro. The following code requires that you have the SOAP Toolkit installed. From the command window or in a small PRG file you can type:

To which you’ll get the super exciting response:

Hello World, Rick! The time is: 4/8/2004 8:14:38 AM

And that’s all it takes for basic access of the Web Service. Note that you can make several method calls against the service, but you cannot call MSSoapInit more than once – for example to connect to a different Web Service. You’ll need a new instance of the SoapClient instead.

Note that this sort of thing will work just fine with any kind of simple parameters and return values. The Soap Toolkit will automatically convert strings, integers, floats, Booleans and dates etc. into the proper XML types and pass that data across the wire without a problem. For example, the following simple Web method:

when called with:

will return a DateTime value natively. Conversely any date time parameters you pass in are automatically marshaled to the server in the proper type. This is really one of the big benefits of using Web Services over simply firing XML at a server. It provides a simple interface both on the client and the server to have the two sides communicate with simple method-interfaces.

However, things get trickier when you’re not dealing with simple values any longer. Think about what happens when you need to pass an object to the server for example. Both client and server have to know what the object looks like and both have to agree how the object is formatted when marshaled over the wire.

Getting friendly with Data

But let’s start with a special and very common case for transferring data between .NET and Visual FoxPro. The .NET DataSet has become a very common structure both for .NET and Visual FoxPro. In .NET the DataSet is ADO.NET’s primary data container that holds data retrieved from queries. It is ADO.NET’s primary data interface that is accessed by the user interface. In Visual FoxPro DataSets are not directly supported, but Visual FoxPro 8.0 introduced the XMLADAPTER class which allows you to easily convert to and from DataSets and VFP Cursors.

To demonstrate how we can utilize a DataSet to provide offline data editing through a Web Service I’ll use a simple form based example using the trusted SQL Server Authors database. I’ll start by retrieving a DataSet from .NET into a Visual FoxPro cursor over the Web Service.

Listing 1 – Returning a DataSet from the Web Service using a Business Object

Listing 1 demonstrates what the Web Service method looks like on the .NET Server Side with C# code. Notice that I opted to use a business object here to retrieve the DataSet. The business object runs the actual SQL to retrieve the Author data and stores the resulting DataTable in the DataSet property.

Listing 2 – The Business Object method is using the business object base class

Listing 2 demonstrates the business object method, which relies on the SimpleBusObj base class to handle the actual Execution of the SQL statement. You can take a look at the included source code to check out the details of this reusable SQL code. Note that this method returns a count of records returned and adds or replaces a table called AuthorList in the internal business object DataSet. This DataSet is then returned back to the client in the actual Web Service method.

The Web Service method basically wraps the business object method, but it provides a number of modifications in the way it presents itself to the world from the underlying business method. As you can see it’s returning a DataSet instead of the count of records and throws a SoapException when an error occurs so that the client can know what went wrong with the Service call.

The main change is the DataSet result, which provides the marshalling mechanism to send the data to the client. Sending a DataSet is the easiest way to share this data with Visual FoxPro. You could also pass the entire business object, but VFP wouldn’t know what to do with this object and you’d have to manually parse it. But you can easily pass a DataSet, which can contain one, or more tables of data embedded inside of it which in most cases is sufficient for the client side application.

Ok, let’s see what it takes on the Visual FoxPro end to pick up this DataSet. This is not as simple as it was with the result value from our previous methods because in essence we are returning an object from .NET. Worse, the SOAP Toolkit has no idea how to deal with this object.

You will find that loResult returns an object. Specifically loResult will contain an XMLNodeList object that points at the SOAP result node. This seems like an odd choice, but this is how MSSOAP returns all embedded object types. Even so, you can trace backwards to retrieve the XML of the embedded Response (in this case the DataSet) XML or even the entire SOAP XML document.

You can retrieve the entire SOAP Response XML as an XML string with this code:

which is shown in Figure 3.

Listing 3 – Full XML SOAP response for a DataSet

If you look at this XML document closely you’ll see that there’s a SOAP Envelope and body which is the SOAP wrapper for the result. Within it you have the GetAuthorsResponse node which is the result value.

This is also the root node for the NodeList that is returned to you. In the above document you have two nodes in this nodelist: The xs:schema and diffgram:diffgram nodes which map to loResult.Item(0) and loResult.Item(1) respectively. If you want to retrieve the entire DataSet with root node, schema and data as an XML string you’d use:

Sounds complicated but once you’ve done this once or twice it comes easy. This mechanism does give you control since you have access to the entire SOAP packet through it.

So, now let’s see how we can retrieve this DataSet returned from .NET into a cursor we can browse. Listing 4 shows the code to do this.

Listing 4 – Retrieving the Authors DataSet in Visual FoxPro

I’ve included rudimentary error checking in this code. Remember that you are pulling data from a Web Service so it’s a very good idea to wrap every call to it in an exception block to make sure that you capture any potential errors and handle them accordingly. .NET doesn’t do a great job of firing clean exceptions so if you want to display error messages you’ll probably have to parse them somewhat to get at the meat of the message. I’ll have more on this later.

Once you’ve retrieved the DataSet we still need to convert it using the XMLAdapter object. XMLAdapter was introduced in Visual FoxPro 8 and allows you to load an XML document and among other things convert it back into a cursor. You can load XML from a URL, a DOM object or an XML string. The code above shows how to get at a DOM node or an XML string from the returned data. In this case, since a DOM node is available let’s use it and use the oXA.Attach(loDOM) method to load the DataSet Xml.

If you run the code above you should end up with a cursor for the SQL Server Authors table. But this result probably won’t satisfy you – the result you get is formatted wrong with all fields showing up as Memo fields. The problem here is that we’re retrieving generic type data from that DataSet, type data that is generated on the fly. If you look at Listing 3 again and look at the XML schema you can see that the types are reported but none of the lengths are. So any string value is returned as a Memo field, any numeric value as a generic number and so on.

To get complete type information we need to make a change to how ADO.NET retrieves our data from the Database. In our business object code I can add this directive:

This translates into ADO.NET code that tells an ADO.NET DataAdapter to retrieve data with full schema information:

This code lives in the SimpleBusObj class’ Execute() method which executes a SQL command. I made ExecuteWithSchema an optional flag on the business object, so that I can choose when to include the schema. Normally you don’t want to load Schema information because it causes extra data to be sent down from SQL Server. But in Web Service front ends like our sample WebService here, we always want the schema to be there so that disconnected clients can properly parse the DataSet into local data structures such as Visual FoxPro cursors.

Updating the Data on the Client

Now that we have the data on the client, what can we do with it? Well, it’s a VFP cursor so you can party on the data all you want! You can edit, update and add new records to your heart’s content. But remember that the data is completely disconnected. We downloaded a DataSet from the server and we turned it into a cursor, but there’s no connection between this cursor and the Web Service or the Author data source sitting on the server.

So in order to be able to work with this data offline and sync with the server we need to track the changes we’re making and then submit those changes back to the Web Server. Using the tools in Visual FoxPro 8 this involves the following steps:

1.      Setting multi-row buffering on in the table

2.      Working with the Cursor and updating the data as needed

3.      Using the XMLAdapter to generate a DiffGram DataSet of the changed data

4.      Sending the Diffgram XML back to the server

The first step after the data has been downloaded as shown in Listing 4 is to enable multi-row buffering in the new cursor so that changes can be tracked. You do this with these two simple lines of code:

At this point you’re free to make changes to the Cursor as needed. When it comes time to update the data the first step is to generate a DiffGram from this data using the XML Adapter. You’ll want to use the XML Adapter so you can return XML in a format that is similar to the DataSet’s GetChanges() method in ADO.NET. Listing 5 shows how to do this with the Authors table in the Sample application.

Listing 5 – Creating an XML Diffgram with the XMLAdapter

If you examine this XML you’ll see something like this shown in Listing 6.

Listing 6 – DiffGram Code generated by the XML Adapter

As you can see the XMLAdapter is pretty verbose in its creation of the DiffGram – it includes a full schema of the data structure and includes a full record for each change instead of just the fields. If you’ve used the XMLUPDATEGRAM() function in VFP before you might be surprised at the amount of XML generated. Unfortunately all of this is required in order for .NET to be able to create a DataSet from your data in the same format as you would get from the DataSet.GetChanges() method which also produces a ‘diffgram’ DataSet.

Passing XML DataSets back to the server

Now that we have our XML DiffGram we need to pass it back to the server. We have a few problems here with Visual FoxPro that makes this process a little less than optimal. The problem is that the MSSOAP Toolkit does not deal well with objects passed from the Client to the server in a SOAP method. There’s no problem passing simple types, but the SOAP client cannot convert a Fox (or other COM object) into something that can be turned into a SOAP representation automatically. There are ways that you can do this by creating a COM object and generating a custom WSDL file, but this is a lot of work and in most cases not worth the effort.

So with this limitation in mind you have a couple of options for passing Complex Objects and DataSets: Passing an XMLNodeList which like the return parameters is properly parsed into the SOAP document as raw XML. Or you can pass the data as a string to the server, but this requires that the Web Service includes a separate method that knows how to accept a string instead of an object.

Let me demonstrate this to in all the gory details. Let’s start by creating a Web Service method that can accept our changes.

Listing 7 -  A Web Service method that saves changes made on the client

The Web Service method is pretty simple as it once again uses the base functionality in the business object base class (shown on the bottom for completeness) to persist its changes. The base behavior is pretty straight forward using the stock DataAdapter/CommandBuilder syntax that automatically builds the appropriate update/insert/delete statements for any updated or added records in the DataTable.

If we want to call this method from Visual FoxPro over the Web Service we need to first get our DiffGram XMLADAPTER Xml returned to us, and then figure out how to to pass the DataSet as an object – not as a simple string parameter – to the Web Service.

The MSSOAP Client allows sending of raw XML in the form of an XMLNodeList, which is a collection of child nodes in the DOM. You basically need to provide the nodes underneath the Document Element node of the document, which can be retrieved by using:

This NodeList can now be passed as the parameter for a complex type or in this case a .NET DataSet. If we put all the pieces together the code looks like shown in Listing 8.

Listing 8 – Passing a DataSet object to a .NET Web Service via XML

There are a couple of important pieces in that code. First when you use the XMLAdapter always make sure that you use UTF8Encoded = .T.. The XMLAdapter by default generated Ansi-1252 XML, which will fail inside of the SOAP Envelope it gets embedded into if you have any extended characters in your data. SOAP usually encodes in UTF-8 so make sure your generated XML matches that.

You have to call ToXML() and then load the resulting XML into an XMLDOM object. From there you navigate down to the ChildNodes() of the DocumentElement which provides the NodeList parameter that the SOAPClient uses to embed the XML into the document.

Rethinking Data Access

Ok now that we have the basics down let’s think about what we’re doing here. We’re downloading data to the client side and we’re running this data in a complete offline scenario potentially making changes to many records at a time.

You might think right about now, what happens in conflict scenarios? Well, the answer it’s not pretty. Basically the stock .NET update mechanism will run updates until a failure occurs then fail and return an error. This means by default at least you’re updating some records, but not all of them, which is probably not a good way to go. ADO.NET supports the ability to see exactly what failed by using the HasErrors property on each DataRow in a DataTable as well as on the DataTable. There is also a ContinueUpdateOnError method on the DataAdapter that allows you to submit all records and mark only the failed ones instead of the default behavior that just stops (who thought that this would be useful?). I’m not going to go into detail on the complex topic of conflict resolution – I would point you to Chapter 11 of David Sceppa’s excellent ADO.NET book from Microsoft Press if you want to see a number of different ways to deal with update conflicts.

What I’m getting at is that ADO.NET has strong features for detecting and negotiating update errors, but it requires fairly complicated logic to make this work well. Now doing this sort of thing remotely over a Web Service becomes even more complex because you can’t easily pass the error information and detail data back and forth.

So what to do? First is to review whether update conflicts are really an issue in your application. In many applications update conflicts are extremely rare and when they do occur a last one wins is often not unreasonable.

The next thing is to try and make sure that you issue data updates as atomically as possible. In other words try to make sure you read data, edit it and write it back immediately instead of hanging on to it on the client. If your application is designed with always on in mind then this approach is reasonable.

Figure 2 – The Web Service Authors sample form demonstrates atomic data access.

Let’s examine what this looks like with the sample application and code I showed so far. So far, I pulled down all the customer data and then allowed the client to make changes to the data – multiple records and send the changes back up to the server. First pulling down ALL of the data in a huge batch is probably not a good idea as it takes time to pull this data down, so a better approach might be to pull down just a list of all the authors and then cause each click on an author to download the current author information one record at a time. To do this I added a couple of methods to the Web Service:

Listing 9 – Building a more atomic Data Access Service. Retrieving a list and individual authors

Note that I didn’t create a new UpdateAuthors method – the same logic used previous will still work now, because although we now will be updating a single record instead of multiples, we’re still working with a DataSet that updates the server. The update logic is identical.

On the Fox End the Authors form now includes the following Init code:

Listing 10 – Initializing the SOAP client on the Author Form

Note that I pass in the WSDL file as a parameter so that I can easily switch between test and production environments if necessary. I use a Form property to hold a reference to the SOAP Client, so we can reuse this single instance to make multiple Web Service calls. Keep in mind that the call to MSSOAPInit always retrieves the WSDL file and forces parsing of the WSDL which has some overhead. If your app calls the same Web Services frequently you’ll want to cache that reference somewhere for reuse.

Notice the use of the ConnectorProperty, which allows you to configure the HTTP Connection for the client. This method allows you set things like the Proxy Server, Authentication information Timeouts and more as well as providing the ability to modify the HTTP Header sent to the server. Using the ProxyServer property with the “” value is a good idea to make the client use the configured Proxy settings from Internet Explorer. Using this default should handle most proxy scenarios and allow you to get away without any custom configuration via code. Even so, custom configuration can be done via other properties available on the HttpConnector object. For more information on what’s available see the HTTPConnector30 topic in the MSSOAP Help file.

Once initialized we’re ready to make calls against the Web Service and this is done in two methods, LoadList() which loads the list box and LoadAuthor which loads an individual Author.

Listing 11 – Loading an AuthorList and individual author from the Web Service

This code is similar to what we saw before. The code for both of these methods is similar too as they both pull data to the client in the same way: By pulling down a dataset.

Notice also that I always use error handling around the Web Service, which is crucial. Since you have no control over the Web Service you always want to check the result from the Web Service as well as trapping any requests in an Exception block. You can retrieve server side error messages by reading the FaultString property on the SoapClient object. Note that the server must throw a SoapException in .NET in order for a clean message to be retrieved on the client side:

If a simple Exception is thrown or an unhandled error occurs on the server you will end up with a stack trace on the client instead, which is pretty much useless other than for debugging. Therefore it’s very important that your Web Service handles all exceptions itself and re-throws any internal exceptions as SoapExceptions so that the client can pick it up.

Finally the SaveAuthors method is called when the user updates a single record.

Listing 12 – Saving an Author to the Web Service

Note that the first step here is to make sure that we actually have an update to do. If you send an empty dataset to the server you will actually get an error, aside from the fact that you’re wasting bandwidth when you do this. GetDiffGram then uses the XMLAdapter to generate the XML for the changed or inserted record. We then generate the NodeList and send it up to the server with the same UpdateAuthors() method we called previously on the Web Service.

Note that once the update is done we have to call TableUpdate() to reset our internal tracking of the table buffer. Remember we’re not writing the data locally, but on the server, but we have to keep the update state in sync on the client side as well, so TableUpdate() is required here so if we make another change to another record we don’t end up with both of them sent up to the server.

The final piece is adding a new record. Adding a new record is really just as simple as inserting a new record into the Authors table as shown in Listing 13. All we have to make sure of is that the buffering is properly set in this scenario.

Listing 13 – Adding a new record inserts a local record. It’s written to the server when we save.

Other Complex DataTypes

DataSets are very useful in this scenario because they translate really well into FoxPro cursors and back. But DataSets are not an official SOAP data type – the type and format is specific to .NET and other Microsoft tools. If you return a DataSet to a Java Application for example it won’t know what to do with it, as it has no concept of a DataSet. For a Java Application this means the XML has to be manually parsed.

You can also return objects from a .NET Web Service and unlike DataSets if your objects are made of simple types you can expect most SOAP clients to be able to consume and even make sense of the objects on the client side.

For Visual FoxPro Complex types mean some problems. Specifically Visual FoxPro will not be able to automatically receive a complex object because there’s no automatic mapping mechanism available in the SOAP toolkit. Instead the SOAP Toolkit provides complex objects in the same NodeList format that the DataSet was provided. There’s no automatic parser available for this sort of object in the Visual FoxPro language.

Let’s take a look at another example and use the wwSOAP class that can provide some relief with parsing result objects. Rather than returning a customer record as a DataSet row, let’s return the record as an object. Listing 14 shows an AuthorEntity  class. To make things a little more interesting I also added an object that contains Phonenumbers to demonstrate hierarchical objects in this context.

Listing 14 – Creating an Author Entity object that maps the Author fields into an object

This is real simple implementation of an Entity class that’s based on an underlying DataRow, which is implemented in the LoadRow and SaveRow methods that read and write the data from the object generically back to the underlying DataRow using Reflection.  With this class in place we can now return an object instead from the Web Service as shown in Listing 15.

Listing 15 – Returning Author Data as an object is more light weight

Note that the object passed is not the business object itself, but rather an entity object that serves as a Data Container. The reason for this is that the business object is pretty heavy weight in what it contains. So we really just want to pass down the data graph of this object, which in this case is the entity object (which could also be part of the business object itself).

This is also consistent with .NET’s client side Web Service model. Any objects that are accessed on the client are treated as Proxy objects, which are mere generated copies of the full objects returned from the Web Service. In other words, a .NET Web Service Client receives an object of type AuthorEntity, but it contains only the properties and fields of the object – none of the methods, events or other logic.

The advantage of using an object return over a DataSet is that this is much more lightweight than sending down a complete DataSet to the client. Objects are persisted into the SOAP package without schemas as the schema is provided in the WSDL document. In theory at least the client application should be able to parse the object based on this WSDL description.

To pick up this object in the SOAP Toolkit we can now use trusted code using the SOAP Toolkit:

With the SOAP Toolkit alone this as far as it will take you. It provides no easy mechanism to take this object XML and provide you a real object reference from it unless you create a custom type mapper, which is more of a hassle than parsing the XML in the first place. So, from here you have to manually parse the XML to do anything useful with it.

However, there are a couple of alternatives you can use by using the free wwSOAP and wwXML classes from West Wind Technologies. With the XML returned you can use wwXML to parse the XML to an object as long as you have an object that has a matching structure:

Listing 16 – Calling a Web Service and retrieving an object with wwXML

wwXML includes a number of parsing methods that can create XML from an object and vice versa. Here one of the low level methods ParseXmlToObject() is used to turn XML into an object that has been provided. wwXML’s object parsing can work without a Schema as long an object is provided as input – the input object serves as the Schema in this case. wwXML parses through the object properties and looks for the corresponding XML elements to find a match. It retrieves the string value and converts it to the proper type.

Note that the last .T. flag in the call specifies that the parsing is to occur case insensitively. VFP property names are never case sensitive (they’re always lower case), but of course XML nodes are. This poses a big problem, as it’s difficult to match up a VFP object’s properties with those of a .NET object that uses common CamelCase for property names. I REALLY wish VFP would support proper casing for objects internally! Anyway, the workaround is to use the llParseCaseInsensitive flag which is more time consuming as wwXML loops through all elements for each property to find a match – XPATH has no way to do case-insensitive searches. Bad as it sounds this parsing is relatively fast because objects property lists tend to be fairly small. On single objects this certainly won’t be a problem, but it might get slow if you’re parsing many objects in a loop.

Making Life easier for Object Parsing with wwSOAP

If you want to get an object created for you on the fly rather than precreating one you can use the wwSOAP class in many cases. wwSOAP includes a method called ParseObject() which can take a DOM element as input and parse an object based on the WSDL description.

You first call ParseServiceWsdl to parse the WSDL file, which creates an internal structure that describes the methods and object types available. The ParseObject method then is called with a type name as the second parameter. If the type is found wwSOAP creates the type based on the WSDL structure and updates the values from the XML structure.

If you want to take this one step further you can skip using the MSSOAP client altogether and use the wwSOAP class and a few helper classes to return data to you directly. Let’s call this same Web Service one more time with wwSOAP as shown in Listing 17.

Listing 17 – Using wwSOAP to handle object return values automatically

This is lot easier – this mechanism automatically creates the underlying object. The lParseReturnedObject property determines whether any objects are parsed on return, which makes wwSOAP try to parse the returned object. It does this by looking at the WSDL description, creating an object on the fly and reading values in one at a time. This works with plain or nested objects, but it doesn’t work with collections or arrays at this time. If there are any arrays or collections in the object returned these won’t be parsed properly.

If lParseReturnedObject is set to .F. or wwSOAP can’t find a matching object structure in the WSDL file it returns an XMLDOMNode. Unlike MSSOAP wwSOAP returns the top level node object of the Return value (to get the same value as MSSOAP returns you can use loNode.ChildNodes()), since this makes much more sense for further parsing if you’re using tools like wwXML or you’re manually walking through the XML.

wwSOAP also handles exceptions internally – you can check the lError and cErrorMsg properties instead to retrieve error information. In addition wwSOAP also makes it easy to retrieve the Request and Response Xml via a simple property for easier debugging.

Updating the Business object with an Object parameter

Ok, this solves one part of the problem – retrieving parameters. But what about sending them to the server? Sadly wwSOAP doesn’t offer any solutions here. Mapping Visual FoxPro objects to WSDL structures is a mess because VFP doesn’t support mixed case property values. With wwSOAP you can pass an XMLDOM nodelist to create XML manually and send that up to the server. To reiterate the DataSet example from earlier on with wwSOAP here’s what you have to use:

This is pretty much the same strategy you use with the MSSOAP client. You also pass a NodeList with the detail of the Data to send (as the SOAP headers require that the root node has the name of the parameter).

Let’s look at another example that uses an AuthorEntity object to update the Authors from the client. Listing 19 shows the UpdateAuthorEntity method, which receives the same AuthorEntity object shown in Listing 14 as a parameter.

Listing 19 – Updating the Author from an Object Parameter passed to the Web Service

This code loads the business object based on the Author’s Id. If not found a new Author record is created. Once our author record is loaded – existing or new – we update the data with the data retrieved from the Web Service parameter by saving the contents to the business object’s DataRow member. SaveRow copies the Entity properties to the DataRow fields thus updating the business object. The Business object then can simply save the order.

On the FoxPro end we have more work to call this Web Service method. As previously mentioned there’s no built-in mechanism to create an object graph into XML that matches. wwXML does support a method called ObjectToXml but it can only generate element names in lower case since VFP doesn’t support mixed case in property names. So, we’re stuck with manually generating XML in some way. The XML to generate must look as shown in Listing 20.

Listing 20 – Object XML to send to the UpdateAuthorData Web Service Method

To make the Web Service call is shown in Listing 21.

Listing 21 – Passing an object to the .NET Web Service using both MSSOAP and wwSOAP

I showed both wwSOAP and MSSOAP in this example. Notice that with wwSOAP you have more options for displaying the XML that was sent and retrieved, so in many cases it’s much easier to debug any problems you might have.

Error Handling in Web Services

I’ve been mentioning error handling off an on throughout this document and it should be fairly obvious that dealing with data that comes from a Web Service is very different than data that comes from a local source. You pretty much should ALWAYS check for errors after a Web Service call. The MSSOAP toolkit is pretty messy in this regard as it throws an exception. Luckily in VFP 8 and later this has gotten a lot easier to deal with by simply using a TRY/CATCH block around the code. To review Listing 22 shows typical MSSOAP error handling.

Listing 22 – Error Handling with MSSOAP requires Exception blocks

But that’s still a lot of code you have to deal with. wwSOAP makes this a bit easier as it handles any Web Service errors internally and simply sets a flag you can check. With wwSOAP error handling is a little simpler as shown in Listing 23.

Listing 23 – Error Handling with wwSoap involves checking properties

Using Wrapper Classes to provide Web Service logic

When using Web Services you should treat them like you treat business objects. They aren’t business objects, but they are abstracting a remote application that happens to be accessed over  a Web Service. Because you probably will call the Web Service from many locations in your application you probably should create a wrapper that abstracts the usage of the Web Service to a large degree.

In particular you should isolate the underlying logic that controls how the Web Service is accessed out of your front-end code, just like a the front-end should never talk to the database directly in good business object design application, the front end should never talk directly to the SOAP proxy. There’s no reason you should ever have a reference to the MSSOAP or wwSOAP object directly in your front-end application code. Instead create a class that wrappers the Web Service and then use that class instead.

To help with this process I’ve created a Web Service Proxy generator that creates a class consisting of all the methods of the Web Service. Figure 3 shows this tool in action.

Figure 3 – Generating a Visual FoxPro Proxy class that wraps the SOAP client provides Intellisense and abstracts calling the Web Service.

This utility creates a wrapper class for the Web Service, a loader and a small block of test code you can run. Once you have created this wrapper class you can very easily call your Web Service like this:

In this case I’m using wwSOAP and it automatically parses the object into return value. If you type the above you’ll also notice that because this is a full Visual FoxPro class you get real Intellisense on it (instead of the hokey Web Service Intellisense through the Web Service Wizard).

You can also switch transparently between using wwSOAP and MSSOAP by setting the client mode, which is passed with the Init. Setting the value to 1 uses MSSOAP instead. The code will work the same except that in the example above MSSOAP will return an XML Nodelist instead of the actual result object.

The code generated for each method looks is shown in Listing 23.

Listing 23 – The generated client proxy code works with both wwSOAP and MSSOAP

The generated code also contains a section where you can store code that you’ve changed. If you make changes to a specific method you can move the method to this protected area. Then when you regenerate the class the generator preserves the changes – however, it will also generate another copy of your overridden method, which you have to delete. Still this goes a long way to let you modify this file.

I personally prefer another approach though, which is to create yet another wrapper class for the Web Service. In this subclass I usually perform additional tasks that make it easier to call my Web Service. For example, consider the GetAuthors() method described earlier. This method retrieves a result as a DataSet, but this value is returned to as an XML DOM item rather than the cursor that we really would like to use. So a wrapper class could address this scenario nicely. Listing 24 demonstrates the wrapper method for GetAuthors().

Listing 24 – A high level wrapper class should handle things like input and return type conversions

So now we can call this method much more easily in any front-end code:

The FoxInterop Client now behaves like any other business component in a typical application. Through this approach we’ve accomplished a lot of functionality:

·          Encapsulation
All logic related to the Web Service is now centralized in 1 top level class.

·          Abstraction
We’re never talking to the underlying SOAP protocol directly. If we need to update or switch SOAP clients later we can make changes in one place.

·          Error Handling
The error handling is provided internal to the class so you don’t have to deal with the same few lines of code over and over again.

·          Type conversion
The wrapper can provide a clean data interface to your application. You’re not passing around XML strings or DOM nodes but rather can input or output cursors or pass or return objects.

Ready for Service

Wow – a lot of information in this article. Armed with this information you should be ready to tackle your .NET Web Services from Visual FoxPro. Web Services are relatively easy to use and powerful, but it’s important to keep in mind that although they mimic local method calls, they are fundamentally different. The disconnected nature means that data passed over the wire is only a transport and not real objects or cursors. Conversion is required in almost all situations. But armed with good understanding you can pass data in a large variety of ways between the client and server.

Which approach is best? Object or DataSet or even arrays or collections of objects? It depends on your application. For Visual FoxPro application I think that using DataSets and XMLAdapters provide the easiest path of sharing data between the two platforms as this makes it easy for VFP to consume the data in cursor format. The fact that the synchronization mechanism is built into ADO.NET and VFP both (via Table Buffering) makes it easy to pass changed data back and forth. DataSets are expensive in terms of content being shipped over the wire, but for the functionality they provide this may be well worth it.

Objects are more lightweight but they are a little more difficult to work with and if you do things like update multiple records in tables to send up to the server you will have to manage your own update logic. This maybe OK – it’s essentially more low level. It’s a good idea to be consistent with your approach, but at the same time remember that you can mix and match when necessary. Use whatever works best for the situation. Until next time see if you can be of Service…

As always if you have comments or questions, please post them on the West Wind Message Board (www.west-wind.com/wwThreads/) in the White Paper section.