Migrating from the SOAP Toolkit to Web Services

  • Article

 

Peter Vogel
PH&V Information services

January 2002

Summary: How to access a Web service from both Microsoft Visual Basic 6.0 and Visual Basic .NET, and how to convert your existing SOAP applications to the Microsoft .NET platform. (10 printed pages)

Objectives

  • Learn about the SOAP tools in Microsoft® Visual Studio® .NET.
  • Review accessing COM/COM+ components with SOAP and Microsoft Visual Basic® 6.0.
  • Access Web services from Microsoft Visual Basic .NET.
  • Migrate SOAP Toolkit applications to Web services.

Assumptions

  • You understand what a Web service is.
  • You are experienced with and have access to Visual Basic 6.0 and SOAP, and you know how to create a Microsoft ActiveX® DLL project
  • You are familiar with some basics about Visual Studio .NET.

Contents

Web Services, SOAP, and Your Tools
Web Service Description Tools
SOAP Toolkit 2.0 Overview
Visual Basic .NET Walkthrough
Creating the ClientConverting from the SOAP Toolkit to Visual Studio .NET
Summary

Web Services, SOAP, and Your Tools

A Web service provides functionality that you can access over the Internet—you call a Web service and get a result in return. What's new about Web services is that you are now connecting to services over the world's largest network—the Internet. However, as a Visual Basic programmer the ugly details of working over the Internet are taken care of for you.

In this document, you'll see how to access a Web service using Visual Studio .NET. You'll review the process for creating a Web service with Visual Basic 6.0 and the SOAP Toolkit, version 2.0. You'll also see how to convert your existing SOAP Toolkit applications to use Web services in the .NET Framework.

The Web service used in this document has a very simple function called createCustomer. It accepts a customer's first and last name, and returns a customer identifier. The functionality of the Web service is not necessary to the discussion here; you can concentrate on how to create and access the Web service using either Visual Basic 6.0 or Visual Basic .NET.

Visual Basic and SOAP

You communicate with a Web service by sending and receiving SOAP documents. In Visual Basic 6.0, there are two ways to create a SOAP document:

  1. Assemble the document by concatenating strings
  2. Use SoapClient from SOAP Toolkit version 2.0

SoapClient will not only create a SOAP document to communicate with a Web service, but will also send the document to the Web service for processing.

At the Web service end of the transmission, you need a SOAP listener to catch and process the document sent by a client. The SOAP Toolkit version 2.0 includes SoapServer, which you use in a listener application to process SOAP documents. The listener is a separate application that you create independent of the component that implemented the Web service.

With Visual Studio .NET, creating and accessing Web services is simplified. In Visual Studio .NET, creating a Web service doesn't require you to build a separate listener application. When accessing a Web service, proxies are automatically created for you that make working with a Web service look just like accessing any other object.

Web Service Description Tools

The Web Service Description Language (WSDL) is an XML language specifically designed for describing Web services. WSDL has been presented to the W3C, along with SOAP, as part of the process of making Web services an open standard. A WSDL description of a service can include a wsdlSpec tModel that provides all the information necessary to create and send a SOAP document for the Service. Here's what the wsdlSpec tModel file to support the createCustomer function might look like:

<?xml version='1.0' encoding='UTF-8' ?> 
 <!-- Generated 06/25/01 by Microsoft SOAP Toolkit WSDL 
      File Generator, Version 1.00.623.1 --> 
<definitions  name ='cust'   
    targetNamespace = 'http://tempuri.org/wsdl/'
    xmlns:wsdlns='http://tempuri.org/wsdl/' 
    xmlns:typens='http://tempuri.org/type' 
    xmlns:soap='https://schemas.xmlsoap.org/wsdl/soap/' 
    xmlns:xsd='http://www.w3.org/2001/XMLSchema' 
    xmlns:stk=
'https://schemas.microsoft.com/soap-toolkit/wsdl-extension'
    xmlns='https://schemas.xmlsoap.org/wsdl/'> 
  <types>
    <schema targetNamespace='http://tempuri.org/type'
      xmlns='http://www.w3.org/2001/XMLSchema'
      xmlns:SOAP-ENC=
         'https://schemas.xmlsoap.org/soap/encoding/'
      xmlns:wsdl='https://schemas.xmlsoap.org/wsdl/'
      elementFormDefault='qualified'>
    </schema>
  </types>
  <message name='Custservices.createCustomer'>
    <part name='First' type='xsd:string'/>
    <part name='Last' type='xsd:string'/>
  </message>
  <message name='Custservices.createCustomerResponse'>
    <part name='Result' type='xsd:string'/>
  </message>
  <portType name='CustservicesSoapPort'>
    <operation name='createCustomer' 
      parameterOrder='First Last'>
      <input message=
         'wsdlns:Custservices.createCustomer' />
      <output 
   message='wsdlns:Custservices.createCustomerResponse' />
    </operation>
  </portType>
  <binding name='CustservicesSoapBinding' 
           type='wsdlns:CustservicesSoapPort' >
    <stk:binding preferredEncoding='UTF-8'/>
    <soap:binding style='rpc' 
      transport='https://schemas.xmlsoap.org/soap/http' />
    <operation name='Add' >
      <soap:operation soapAction=
         'http://tempuri.org/action/Custservices.Add' />
      <input>
        <soap:body use='encoded' 
         namespace='http://tempuri.org/message/'
         encodingStyle=
         'https://schemas.xmlsoap.org/soap/encoding/' />
      </input>
      <output>
        <soap:body use='encoded' 
         namespace='http://tempuri.org/message/'
        encodingStyle=
         'https://schemas.xmlsoap.org/soap/encoding/' />
      </output>
    </operation>
  </binding>
  <service name='cust' >
    <port name='CustservicesSoapPort' 
      binding='wsdlns:CustservicesSoapBinding' >
      <soap:address 
      location='https://localhost/customer/cust.ASP' />
    </port>
  </service>
</definitions>

The <service> tag at the end of the wsdlSpec tModel specifies which SOAP listener to send the request to, in this case, the page https://localhost/cust/cust.asp. The previous parts of the file described the messages that can be used with the service.

Note The tempuri.org namespace used in the SOAP document is a temporary namespace that's only to be used during development ("temporary uri"). You should alter your WSDL file to use a unique URI (for example, the URL for your company's Web site) before releasing the service into production.

The SOAP Toolkit objects and the Visual Studio .NET IDE both read WSDL files. SoapClient uses the information in the WSDL file to enable it to act as a proxy for the Web service. Visual Studio .NET uses the same information to generate proxy classes for the Web service. As a result, you can:

  • Call the methods of the Web service as if they were methods of these proxies.
  • Have your calls validated against the WSDL description of the Web service before the message is sent.
  • Interact with the proxy without having to be familiar with either the WSDL file's contents or the SOAP document that is being generated.

Figure 1 shows the relationships between the various components, including the Web Services Meta Language (WSML) file, which is required only with Visual Basic 6.0 and is described in that walkthrough.

Figure 1. Schematic of a Web service and client

In the SOAP world, the SOAP Toolkit and the Visual Studio .NET IDE perform analogous functions. However, the SOAP Toolkit objects can't provide the complete support that Visual Basic developers expect. In Figure 2, you can see the kind of IntelliSense® support that a Visual Basic programmer takes for granted. The IntelliSense drop-down list automatically shows the createCustomer method for the Customerservices COM object.

Figure 2. IntelliSense support for COM/DCOM/COM+ objects

In Figure 3, you can see the IntelliSense support provided for a Web service by SoapClient. All of SoapClient's methods are listed, but the methods of the service for which SoapClient is acting as a proxy for don't appear (that is, createCustomer).

Figure 3. IntelliSense support using SoapClient

With Visual Studio .NET, the proxy classes generated by the IDE do a better job of representing the Web service than the SOAPClient. In Figure 4, you can see the IntelliSense support for accessing a Web service. The createCustomer method appears as one of the methods of the object used to interact with the Web service.

Figure 4. IntelliSense support in Visual Studio .NET for Web services

SOAP Toolkit 2.0 Overview

This section provides a quick review of the process for creating the Web service described in the earlier section Web Services, SOAP, and Your Tools.

Creating and Accessing a Web Service with the SOAP Toolkit

  1. In Visual Basic 6.0, create a new Visual Basic ActiveX DLL project named CustCP and a Class module named Customerservices with the code for the Web service:

    Public Function createCustomer(ByVal First As String, _
      ByVal Last As String) As String

createCustomer = "A" & CStr(Len(First)) & _
                        CStr(Len(Last))
End Function

  2. Generate the WSDL and WSML files using the SOAP Toolkit's WSDL Wizard (the WSML file contains the information used by SOAPServer to map from the Web service to the ActiveX COM object).

  3. Create the SOAP listener as an ASP page that uses SOAPServer:

    <%@ LANGUAGE=VBScript %>
<%Option Explicit

  Dim ss
  Dim WSDL
  Dim WSML

  Response.ContentType = "text/xml"

  WSDL = Server.MapPath("cust.wsdl")
  WSML = Server.MapPath("cust.wsml")

  Set ss = Server.CreateObject("MSSOAP.SoapServer")
  ss.Init WSDL, WSML
  ss.SOAPInvoke Request, Response, ""%>

  4. Create the client to call the Web service that uses the SOAPClient:

    Private Sub cmdCreate_Click()
Dim sc As MSSOAPLib.SoapClient

Set sc = New SoapClient
sc.mssoapinit "http://vogel2/cust/cust.wsdl"
Me.txtCustId.text = _
      sc.createCustomer(Me.txtFirstName.text, _
                     Me.txtLastName.text)
End Sub

Visual Basic .NET Walkthrough

In this section you'll see how to:

  • Create a Web service in Visual Studio .NET.
  • Access the Web service from a Visual Basic .NET application.

When you build your Web service in Visual Studio .NET, a discovery file is automatically generated for the Web service. A discovery file is used to add a reference, including the WSDL description, of your Web service to other Visual Studio .NET applications.

Note The file type for the discovery file is .vsdisco for Visual Basic and C# projects, .disco for C projects.

Creating the Web Service in Visual Studio .NET

  1. From the File menu, select New to display the New Project dialog as seen in Figure 5.

    Figure 5. Visual Studio .NET New Project dialog box

  2. From the Visual Basic Projects section, select ASP.NET Web service.

  3. Give the project a name in the Name box (MigratetoDotNetService).

  4. Enter the URL for the Web site of your Web service (localhost/customer).

  5. Click OK to create your project. By default, the project will contain a module called Service1.asmx.

  6. Right-click the Service1.asmx module and select View Code from the menu.

  7. Add this code to the Public Class Service1 statement at the top of the module as follows:

    <WebService(Namespace:="http://phvis.com/customer/", _
         Description:="Customer management") _
Public Class Service1

    As discussed in the Converting from the SOAP Toolkit to Visual Studio .NET section, you can generate the skeleton of your Web service routines from an existing WSDL file by using the Wsdl.exe utility. Copy the createCustomer function from the Visual Basic 6.0 example, but add the <WebMethod> attribute to the function's declaration to give this:

    <WebMethod(Description:= _
   "Passed first name and last name, return an id")> _
Public Function createCustomer( _
      ByVal First As String, _
      ByVal Last As String) As String

  8. There is only one change required to convert the Visual Basic 6.0 code to Visual Basic .NET syntax. Replace createCustomer = in the function with Return to give this:

       Return "A" & CStr(Len(First)) & _
                        CStr(Len(Last))
End Function

  9. From the Build menu, select Build to create your Web service. Check the Output window for any errors in the build. The discovery file for your application is generated as part of the build.

Creating the Client

You don't need to create a .NET client—your Visual Basic 6.0 application, created with the SOAP Toolkit, will be able to access your XML Web service. These steps will show you how to create a .NET client for your Web service, regardless of whether the Web service is written in Visual Basic 6.0 or Visual Basic .NET:

  1. From the File menu, select New, and then select Project to display the Add Project dialog box.

  2. From the Visual Basic Projects section, select Windows Application.

  3. Give the project a name in the Name box (MigratetoWebClient) and click OK to create your project.

  4. Right-click the project in Solution Explorer and select Add Web Reference. The Add Web Reference dialog will appear as you see in Figure 6.

    Figure 6. The Add Web Reference dialog

  5. Enter the URL for the .vsdisco file from the Web service project into the Address box—for example, http://localserver/customers/MigratetoNetService.vsdisco. Click on the arrow at the end of the Address box to pick up your reference.

    Note You can also get the URL for the .vsdisco file from your Web service project by dragging your .vsdisco file from Solution Explorer into a code module. This will add the URL for the file to the code module. Then, cut the URL from the module and paste it into the Address box of the Add Web Reference dialog.

  6. Click the Add Reference button to return to your project. A reference to your Web service will appear in Solution Explorer, as shown in Figure 7.

    Figure 7. A Visual Basic Windows Application with a reference to a Web service

  7. To the form, add text boxes called txtFirstName and txtLastName to hold the customer's first and last name, and a button for the code that will call your Web service.

  8. Add the code to declare the variable to reference the proxy class that will handle your Web service (the class's default name is formed from the name of the server and the name of the Web service):

    Private Sub cmdCreate_Click()
Dim cc As localhost.service1

  9. Add the code to instantiate the proxy class and call the Web service's methods:

    Set cc = New localhost.service1
Me.txtCustId.text = _
       cc.createCustomer(Me.txtFirstName.Text, _
                     Me.txtLastName.Text)
End Sub

  10. Press F5 to run your client and access your Web service.

Converting from the SOAP Toolkit to Visual Studio .NET

Applications built with the SOAP Toolkit or XML Web services are built according to the SOAP specification. With SOAP-based applications, the connection between a client and a Web service is defined exclusively by the WSDL file. A Web service built with the SOAP Toolkit can be used with a Web service built with .NET and vice versa. This allows you to migrate from the SOAP Toolkit to .NET in stages by holding the WSDL definition of the service constant. For instance, the clients that access your Web service can continue to use the SOAP Toolkit's SOAPClient while your Web service is converted to .NET.

The simplest way to hold the WSDL file for your Web service constant is to generate the skeleton for your Web service from the WSDL file created by the SOAP Toolkit. The .NET Wsdl.exe utility will generate the Visual Basic .NET skeleton for a Web service if you pass the utility the:

  • /l parameter: Controls the language of the generated code. The default is C#. Passing /l:VB causes the utility to generate Visual Basic.
  • /server parameter: Indicates that you want the utility to generate the Web service’s server-side code. The default is for the utility to generate the client-side proxies.
  • The name of the WSDL file.

To generate the code for our sample Web service from the Cust.wsdl file, you would use:

wsdl.exe /l:VB /server cust.wsdl

The resulting skeleton code would be placed in a file called Cust.vb. You can copy the code from there into your ASMX module and then copy your Visual Basic 6.0 code into the equivalent routines in the ASMX module. You’ll need to convert your Visual Basic 6.0 code to .NET syntax, as described in other papers in this series. If you want to create a completely new .NET version of your Web service, the WSDL file from your SOAP Toolkit version can be used to generate the skeleton code for your Web service.

On the client side, the different client applications that access a Web service can be converted from the SOAP Toolkit to .NET on an individual basis. Even rolling out the .NET versions of a single client can be staged because of the interoperability that the SOAP specification provides. To convert from the SOAP Toolkit to Visual Studio .NET within the client, you must replace the references to SOAPClient with references to the Web service proxies.

Summary

You've seen how to access a Web service from both Visual Basic 6.0 and Visual Basic .NET. You've also seen what you need to do to convert your existing SOAP applications to the .NET platform.

Key points to remember:

  • A WSDL file is used to describe the SOAP documents that can be sent to the Web service. In Visual Basic 6.0, you can use the SOAP Toolkit's WSDL Generator to create this file. In Visual Studio .NET, the file will be generated for you automatically.
  • A Microsoft WSML file and separate ASP listener page are required when creating a Web service in Visual Basic 6.0. Neither is required when creating an XML Web service in Visual Studio .NET.
  • You can freely intermix clients and services, regardless of platform. You can call a Visual Basic .NET Service from either a Visual Basic 6.0 client or an ASP page using SoapClient. And your Visual Basic 6.0 Web service can use SoapServer to process requests from Visual Studio .NET clients.
  • The Wsdl.exe utility will let you generate the skeleton for the .NET version of your Web service from the WSDL file used by your SOAP application.

About the Author

Peter Vogel (MBA, MCSD) is a principal in PH&V Information services. PH&V specializes in system design and development for COM/COM+ based systems. Peter has designed, built, and installed intranet and component-based systems for Bayer AG, Exxon, Christie Digital, and the Canadian Imperial Bank of Commerce. He is also the editor of the Smart Access and XML Developer newsletters, wrote The Visual Basic Object and Component Handbook (Prentice Hall), and is currently working on a book on User Interface Design (APress). Peter teaches for Learning Tree International. His articles have appeared in every major magazine devoted to Visual Basic-based development and in the Microsoft Developer Network® (MSDN) Library. Peter also presents at conferences in North America, Australia, and Europe.

About Informant Communications Group

Informant Communications Group, Inc. (www.informant.com) is a diversified media company focused on the information technology sector. Specializing in software development publications, conferences, catalog publishing and Web sites, ICG was founded in 1990. With offices in the United States and the United Kingdom, ICG has served as a respected media and marketing content integrator, satisfying the burgeoning appetite of IT professionals for quality technical information.

Copyright © 2002 Informant Communications Group and Microsoft Corporation

Technical Editing by PDSA and KNG Consulting, Inc.