Creating an Access Web Service Consumer

WSR makes it easy to integrate Web services into Access applications. Following are the basic steps:

1. Design a form with controls to supply the Web method's parameter values and display the SOAP response message's content. For ASP.NET services, the test form and its response message usually provide an indication of the type of control required. Text boxes work for most services; use list boxes to display response messages containing arrays.

2. Run WSR to generate the Web service class(es) from the service's WSDL document. Services that return simple datatypes generate a single class module clsws_ServiceName, which is called a Web service proxy. Services whose request, response, or both messages contain complex datatypes generate a clsof_Factory_ServiceName class module and a struct_ClassName module for each type.

3. Add code to the form's class module to invoke the Web service proxy's Web method with the required parameter(s) and populate the response controls.

This example uses \Program Files\Seua11\Chaptr31\ZipCodeResolver\AddressCorrector.mdb, which contains a pre-built form for the ZipCodeResolver service. The form is derived from the Office XP Web Services Toolkit 2.0's ComplexTypesDemo.mdb application.

Generating the Web Service Proxy and USPSAddress Classes

The Web service proxy is an Access class module that creates an instance of the SoapClient30 object and generates a WSML document to handle complex types, if required by the service. The SoapClient30 instance uses the SoapConnectorFactory to create a SoapConnector30 instance for the WSDL documents's <port> element that specifies SOAP binding.

Following is the WSML document generated by WSR for the ZipCodeResolver service's USPSAddress type:

 <servicemapping>  <service name='ZipCodeResolver'>   <using PROGID='MSSOAP.GenericCustomTypeMapper30'    cachable='0' ID='GCTM'/>   <types>    <type name='USPSAddress'     targetNamespace='http://webservices.eraserver.net/'     uses='GCTM' targetClassName='struct_USPSAddress'/>   </types>  </service> </servicemapping> 

The MSSOAP.GenericCustomTypeMapper30 is responsible for populating the four string elements of the USPSAddress type: Street, City, State, ShortZIP, and FullZip.

Tip

Make at least one copy of AddressCorrector.mdb before you add the Web service reference. If you need to change the service name or location, it's easier to start over from scratch than to remove the existing classes from a modified version of the database.

To add the required classes to consume a Web service, using the ZipCodeResolver service as an example, do the following:

1. Open AddressCorrector.mdb, close the form, select Modules in the Database window, and click the New Module button to create a temporary Module1 and open it in the Visual Basic Editor.

2. Choose Tools, Web Service References to open the Web Services Reference Tool 2.0 dialog.

3. Select the Web Service URL option and type the URL for the Web service to return the WSDL document. (WSR doesn't require adding ?wsdl to return the WSDL document. For this example, the URL is http://webservices.eraserver.net/zipcoderesolver/zipcoderesolver.asmx.

4. Click Search to display the Web service name in the Search Result list, mark the ZipCodeResolver check box to select the service, and expand the node to display the service's Web methods.

   Tip

   If you don't receive a response with step 3's URL within a few seconds, substitute www.oakleaf.ws for webservices.eraserver.net. The OakLeaf version is derived from the EraServer service, but has several additional complex type methods.

5. Select a method to return its documentation, if present (see Figure 31.6). Clicking Test opens the Web service help page (refer to Figure 31.1).

   Figure 31.6. When you type a URL for an accessible .asmx or .wsdl file, WSR opens a tree view list with the name of the service and its Web methods. Selecting a method displays its documentation, if present.

   

6. Click Add to generate the VBA code for the Web service proxy, class factory, and type class modules (see Figure 31.7).

   Figure 31.7. WSR adds multiple classes for Web methods that return complex types. If the method returns simple types, WSR generates a single clsws_ServiceName class.

   

7. Close the database, and save the added class modules with their assigned names; don't save Module1. Then reopen the database.

8. In frmAddressCorrector, type a valid U.S. address in the text boxes or accept the default values, and click the Correct Address button to execute the service's CorrectedAddressXML method and populate the five text boxes with the data (see Figure 31.8). Code behind frmAddressCorrector separates the building name from the street address. (Very few US addresses have building names.)

   Figure 31.8. This simple form sends a U.S. address as arguments of the ZipCodeResolver's CorrectedAddressXML method and displays the address in USPS standard format.

   

Note

If the Web service or the USPS ZIP+4 Web site isn't accessible, the service times out in 30 seconds. Occasionally, attempts to consume the service might freeze the application. If you don't receive a response in a minute or two, use Task Manager to end the Access process and try again.

Following Proxy Code Execution

You can gain insight into the service consumption process by stepping through the code in the class modules. If you didn't add the classes to AddressCorrector.mdb, the completed version is CorrectAddress.mdb in your \Program Files\Seua11\Chaptr31\ZipCodeResolver\folder.

Do the following to trace execution of the CorrectedAddressXml Web method:

1. Open frmAddressCorrector's class module, navigate to the Set prxResolver = New clsws_ZipCodeResolver line, and press F9 to add a breakpoint.

2. Return to Form view and click Correct Address to open the Visual Basic Editor. Press F8 to move to the clsws_ZipCodeResolver's Class_Initialize event handler (called a constructor).

3. Step through the code that generates the WSML document. The Set sc_ZipCodeResolver = New SoapClient30 statement creates the required SoapClient30 instance. This object handles serialization and transmission of the SOAP request message, interception of the response message, and, with help from other classes, deserialization of the response message to an instance of the USPS class.

4. Step to the next line. The sc_ZipCodeResolver.MSSoapInit2 method specifies the URL for the WSDL document (the service's endpoint URL, plus the ?wsdl suffix), the local WSML document content, service name, SOAP port name (ZipCodeResolverSoap), and the service namespace (http://webservices.eraserver.net).

   Note

   The alternative MSSoapInit method only requires the URL for the WSDL document; the remaining four arguments are optional.

   Tip

   Retrieving the WSDL document from the service provider requires an extra round trip. If it's unlikely that the WSDL document will undergo frequent changes, you can save a local copy as a ServiceName.wsdl file. In this case, replace the value of the c_WSDL_URL constant with d:/Path/ServiceName.wsdl.

5. Step through the next two lines, which enable the client to communicate through a proxy server, if required. The third active statement creates an instance of the cls_of_Factory_ZipCodeResolv class for the struct_USPS class.

6. Step to return to the form class. The Set ObjUSPSAddress = New struct_USPSAddress creates an instance of the USPSClass to receive the deserialized response message values.

7. Step through the Set objUSPSAddress = prxResolver.wsm_CorrectedAddressXml(...) call to execute the wsm_CorrectedAddressXml function, which finally invokes the Web method.

8. Continue stepping until you reach the IGCTMObjectFactory_CreateObject(...) which extracts the targetClassName value (struct_USPSAddress) from the WSML document, and then creates and returns a new instance of the struct_USPSAddress object with its members populated by the response data.

9. Continue stepping until you return to the form class module, which populates the text boxes with the struct_USPSAddress instance's member values.

Finally, the clsws_ZipCodeResolver's Class_Terminate event handler (called a destructor) sets the sc_ZipCodeResolver instance to Nothing, which releases its resources.

Note

The execution process for Web services that return simple types such as strings, integers, or both is much simpler than the preceding example.