VFP8

XML Web Services Sample for Visual FoxPro and Visual Basic .NET

Introduction
Setting Up the Samples
    Prerequisites
    Installing the Samples
    Verifying Database Connection Strings
    Configuring the Visual FoxPro Web Service to Use Local Data
    Specifying a Different Virtual Directory
Testing the Samples
Running the Client Form
    Updating Data
    Inserting Data
    Deleting Data
    Middle-Tier Validation Messages
    Database Error Messages
CursorAdapter with XMLAdapter on the Client
Visual FoxPro Client and Visual FoxPro XML Web Service Diagram
Visual FoxPro Client and Visual Basic .NET XML Web Service Diagram

Introduction

This sample shows different architectures for exchanging data between a Visual FoxPro client and a middle tier written in Visual FoxPro and Visual Basic .NET using XML Web Services. This sample uses two Visual FoxPro classes, XMLAdapter and CursorAdapter. You can use the XMLAdapter class to create cursors from hierarchical DataSets generated from other Visual FoxPro XMLAdapter objects or from ADO.NET. You can use the CursorAdapter class in the client to bind to Visual FoxPro cursors that are created from XML DataSets or in the middle tier to customize updates to different data sources. This sample also uses the SQL Server or MSDE Northwind database as its data store.

Setting Up the Samples

Prerequisites:

Windows 2000 Service Pack 3 or later (Windows XP recommended) with Internet Information Services (IIS) 5.0 or later installed.
SQL Server or MSDE with Northwind database installed. If you do not have the Northwind SQL Server or MSDE database, you can still run the Visual FoxPro Web service described in the section, "Configuring a Visual FoxPro Web Service to Use Local Data".
Visual FoxPro with SOAP Toolkit 3.0, installed by default with Visual FoxPro
Visual Studio .NET version 1.0 or later for building and running the Visual Basic .NET Web service. If you do not have Visual Studio .NET installed, you can still run the Visual FoxPro Web service.

Installing the Samples:

To install source code, components, and IIS Virtual Directory, in the Visual FoxPro directory ..\Samples\WebServices\Northwind, open the setup program NorthwindWebservice_Setup.msi.

It is recommended that you use the default name for the Virtual Directory (NorthwindWebService). Otherwise, you need to update the Web Services Description Language (WSDL) file, client form, and project files. For more information about the files you need to update, see the section, "Specifying a Different Virtual Directory".

After the installation completes, configure SOAP 3.0 for the virtual directory. Open a command line window and browse to the directory ..\Program Files\MSSOAP\Binaries. On the command line, run the batch file SoapDir.cmd as shown:

C:\Program Files\MSSOAP\Binaries> SOAPVDIR UPDATE NorthwindWebService

Running the batch file sets up the virtual directory's Application Mappings.

To verify the setup, open IIS, right-click the NorthwindWebService virtual directory, and select Properties. Click the configuration button to open Mappings. Scroll to the bottom to see the .wsdl extension.

The executable path is the path to your SOAP 3.0 Application Extension, which is located in the following directory:

C:\Program Files\Common Files\MSSoap\Binaries\SOAPIS30.dll

Verifying Database Connection Strings:

Before running the sample, you need to modify and verify the connection strings to your SQL Server.

To modify the Visual FoxPro code, open the project NorthwindWebService_VFP.pjx in the directory ..\InetPub\wwwRoot\NorthwindWebService\VFPSource.
In the project, open and edit the DataAccessLayer.prg file and modify the connection strings in the class definitions so they are valid and secure.

For example, the SQL Server access information appears in the connection string of the SQLNorthwind class:
cConnectionstring = "Driver={SQL Server};Server=localhost;Uid=myUsername;Pwd=myPassword;Database=northwind"
Change the default values of Uid and Pwd to a more secure user name and password.

If you do not have SQL Server or MSDE Northwind database installed, you can still run the Visual FoxPro Web service with local data. For more information, see "Configuring the Visual FoxPro Web service to Use Local Data".

Recompile the NorthwindWebService_VFP project as a Multi-threaded COM Server (DLL). Note: If you accidentally ran the component as a Web service before modifying the connection string, close IIS before recompiling by typing iisreset on the command line.
To modify the Visual Basic .NET source code, double-click the Visual Basic .NET project NorthwindWebService.vbproj in the directory ..\Inetpub\wwwroot\NorthwindWebService. Visual Studio .NET opens.
In Solution Explorer, expand the VBSource folder and double-click the DataAccessLayer.vb file to display the code in the editor window.
Modify the connection strings at the top of this class as appropriate.

If you use Integrated Security, you can enter a valid username and password in the impersonation section of the Web.config file. Instead of running the Web service on the local ASPNET account, you can run it under the account you specify. Remove the comments from the impersonation section in the Web.config file and enter the user name and password. For example:
<system.web>

<identity impersonate="true" 
userName="DOMAIN/myusername"
password="mypassword"/>

To recompile, press CTRL+F5. You will be prompted to save the Solution first before recompiling the Web service. If you are prompted to set an initial start page before it runs, in Solution Explorer, right-click the GetNorthwindData.asmx file. On the shortcut menu, select "Set as Start Page". You can test the Visual Basic .NET Web service through the default Web page access Visual Studio .NET provides.

Configuring the Visual FoxPro Web service to Use Local Data

To modify the Visual FoxPro code to use local data, open the project NorthwindWebService_VFP.pjx from the directory ..\InetPub\wwwRoot\NorthwindWebService\VFPSource. To verify that the Datasource property of the VFPNorthwind class is the correct absolute path to the Visual FoxPro sample database, Northwind.dbc in the ..\ Samples\Northwind folder, open the program file, DataAccessLayer.prg from the project.

DataSource = "C:\PROGRAM FILES\MICROSOFT VISUAL FOXPRO 8\SAMPLES\Northwind\Northwind.dbc"

In the DataAccessLayer.prg, modify the class definitions of the data source classes to inherit from the VFPNorthwind CursorAdapter class. There are five concrete data source classes you need to change: CustomerDataSource, SupplierDataSource, ProductDataSource, OrderDataSource, and OrderDetailDataSource.

DEFINE CLASS CustomerDataSource as VFPNorthwind

Recompile the NorthwindWebService_VFP project as a Multi-threaded COM Server (DLL). Note: If you accidentally ran the component as a Web service, you need to shutdown IIS before recompiling. From a command prompt, type iisreset.

Specifying a Different Virtual Directory

If you changed the name of the Virtual Directory when setting up Web services, you need to update the following files:

Using a text editor, update the following files to point to the correct virtual directory:

Intepub\wwwroot\MyVirtualDirectory\Northwind.wsdl
Intepub\wwwroot\MyVirtualDirectory\NorthwindWebService.webinfo

In the Visual FoxPro Form Designer, open the following forms:

Samples\WebServices\Northwind\frmcustomersws.scx
Samples\WebServices\Northwind\frmcustomersca.scx

In the top left area of the form, update wsdl property for the oVFPWS and oVBWS Web service objects by changing it in the Properties window to the correct location of the WSDL files. For example, the property value for the oVFPWS object is the following:

http://localhost/NorthwindWebService/Northwind.wsdl

You should change the property to the following:

http://localhost/MyVirtualDirectory/Northwind.wsdl

Testing the Samples

Before running the client application, test it to make sure the Web services and components are running properly.

To test the Visual Basic .NET Web service, open your browser to http://localhost/NorthwindWebService/GetNorthwindData.asmx.
Select the GetCustomerByID method.
Type "ALFKI" for the cID parameter value, and click Invoke.

A window opens with the contents of the customer DataSet.

Test Visual FoxPro code through COM to make sure it works before accessing it through SOAP. You should always test your Visual FoxPro components through COM before accessing them through SOAP.

In the Visual FoxPro Command window or a program (.prg) file, type the following:

o = Createobject("NorthwindWebService_VFP.Northwind")
? o.GetCustomerByID("ALFKI")
o = null
The customer XML DataSet should display on your screen.

To test this as a Visual FoxPro Web service through SOAP, on the Visual FoxPro Tools menu, open the Toolbox.
Click My XML Web Services and double-click Register to open the Web Services Registration dialog box.
Type the location of the Visual FoxPro Web service WSDL file as "http://localhost/NorthwindWebService/Northwind.wsdl", and click Done to generate IntelliSense scripts.

The Northwind Web service appears in the Toolbox.

Open a new Visual FoxPro program (.prg) file.
To insert the appropriate SOAP client code for calling the Northwind Web service, drag the Northwind Web service from the Toolbox to the editing window.
In the TRY block, type a call to the GetCustomerByID method:

...

TRY

  loWSHandler = NEWOBJECT("WSHandler",IIF(VERSION(2)=0,"",HOME()+"FFC\")+"_ws3client.vcx")

  loNorthwind = loWSHandler.SetupClient("http://localhost/NorthwindWebService/Northwind.wsdl", "Northwind", "NorthwindSoapPort")

  * Type your XML Web service code here:

  * ex: leResult = loNorthwind.somemethod()

  ? loNorthwind.GetCustomerByID("ALFKI")

CATCH TO loException

....

Save and run the program.

The customer XML DataSet displays on the screen.

If you have problems running Web services, the components might not have installed correctly. Follow the steps in the section "Verifying Database Connection Strings" to recompile and register the necessary files. Make sure you have updated SOAPVDIR on the virtual directory in the section "Installing the Samples".

Running the Client Form

The client form demonstrates working with multiple disconnected records returned from the Northwind database through Web services. It also generates XML DiffGrams that are sent to the Web services to update, insert and delete records form the Northwind database. The Visual FoxPro Web service uses the XMLAdapter class to reconstruct the changed cursor in the middle-tier and attaches it to a CursorAdapter object, which performs simple data validation using the BeforeCursorUpdate event. This event occurs before data is sent to the database. You can use CursorAdapter events to customize your table update operations. If you want design-time data binding and know the table schemas, you can also use the CursorAdapter on the client.

To run the client form

In the Visual FoxPro Command window, run the frmCustomersWS form from the Visual FoxPro directory ..\Samples\WebServices\Northwind by typing DO FORM frmCustomersWS.
Select the Access method from the drop-down list located in the upper right location of the form. It defaults to Visual FoxPro Web Service.
At the top of the form, click Find Customers. This returns an XML DataSet, which displays as a cursor in the grid that appears on the form.
To view the DataSet, at the bottom of the form, click Show Dataset.

Updating Data:

Make changes in a record and click Save.
To view the DiffGram sent to the Web service, at the bottom of the for, click Show DiffGram.
To retrieve the data and verify changes, click Find Customers.

Inserting Data:

To add a new record in the grid, scroll to the last record and press the DOWN arrow.
Type an ID and a company name and click Save to insert the record.
To view the DiffGram sent to the Web service, at the bottom of the for, click Show DiffGram.
To retrieve the data and verify changes, click Find Customers.

Deleting Data:

To delete the record you just added, click the delete mark and click Save.
To view the DiffGram sent to the Web service, at the bottom of the for, click Show DiffGram.
To retrieve the data and verify changes, click Find Customers.

Middle-Tier Validation Messages:

Validation and error messages are sent to the client through a reference parameter when calling the UpdateSingleTable method of the Web service. To view this, open the form's Save method. You can test the validation message by inserting or updating a record without specifying a value for Company Name. The validation message appears in a message box.

Database Error Messages:

Database messages are sent to the client through the same referenced parameter. You can test database database messages by inserting or updating a record without specifying a value for CustomerID. You can also try deleting a customer who has orders or inserting a duplicate value for CustomerID. The database message appears in a message box on your screen.

CursorAdapter with XMLAdapter on the Client

This sample also includes a second client form that uses a CursorAdapter class with the XMLAdapter class called frmCustomersCA.scx. This client form makes it possible for you to design forms and use data binding in the same manner as when working with local tables. You can drag fields from the CursorAdapter object to the form, which sets the ControlSource property automatically to the CursorAdapter fields that you added.

To run the client form

In the Visual FoxPro Command window, run the rmCustomersCA form from the Visual FoxPro directory ..\Samples\WebServices\Northwind by typing DO FORM rmCustomersCA.
Select the Access method from the drop-down list located in the upper right location of the form. It defaults to Visual FoxPro Web Service.
At the top of the form, click Find Customers. This returns an XML DataSet. This DataSet is attached to a CursorAdapter in the form's DataEnvironment and is bound to the grid and text boxes on the form.
To view the DataSet, at the bottom of the form, click Show Dataset.