Microsoft SOAP Toolkit 2.0 XML

You learned about SOAP in "Introduction to SOAP." SOAP is a protocol used to create distributed applications. To enable you to create distributed applications by using SOAP, several SOAP toolkits are available from different vendors. These toolkits include Microsoft's SOAP Toolkit, Apache SOAP Toolkit, Paul Kulchenko's SOAP::Lite, and so on.

Microsoft's SOAP toolkit is an easy-to-use toolkit especially for a developer who uses traditional Microsoft technologies and programming languages, such as COM, Visual Basic, and Visual C++. The first version of the toolkit had certain limitations. One of the main 94 problems with Microsoft SOAP Toolkit Version 1.0 was that it did not implement all required sections of the SOAP specification. In addition, the earlier version of the SOAP Toolkit was an MSDN demo and not a product. However, with Version 2.0 of the toolkit, Microsoft fixed the major bugs and also changed the architecture to make it simpler and intuitive. Also, the new version of the toolkit is a Microsoft product instead of just a demo.

The Microsoft SOAP Toolkit 2.0 allows you to create Web services that expose the functionality of existing COM components. It also allows you to create Web service clients using tools like Visual Basic 6.0. The Microsoft SOAP Toolkit 2.0 includes the following:

  • A client-side component that allows a client application to invoke methods of a Web service based on the description of the Web service from a WSDL document.
  • A server-side component that is used to create a WSDL document, a WSML file, and an ASP or ISAPI endpoint for a Web service from an existing COM component. All these put together can be used to expose the functionality of an existing component as a Web service. The WSDL document describes a Web service, the ASP or ISAPI endpoint provides a port where client applications can call the Web service, and the WSML document maps the Web service operations to the methods of the component.

Microsoft SOAP Toolkit Version 2.0 provides high-level and low-level interaction APIs. To access the high-level interface, you can use a SOAP toolkit object called SoapClient. This object contains several methods and properties, some of which are included in the following list:

  • mssoapinit() method.This method initializes the SoapClient object by using the WSDL file as an input.
  • Client property. This property sets and gets various properties of the SoapClient object.
  • ConnectorProperty property. This property initializes and retrieves the transport protocol-specific parameters.
  • detail property. This is a read-only property that retrieves the value of the <detail> element of the <Fault> node in a SOAP message.
  • faultactor property.This is a read-only property that retrieves the URI of the generated fault.
  • faultcode property. This is a read-only property that provides the value of the <faultcode> element of the <Fault> node in a SOAP message.
  • faultstring property. This is a read-only property that provides the value of the <faultstring> element of the <Fault> node in a SOAP message.

To understand the methods and properties associated with the SoapClient object, consider the following example. You can use the code to connect to a Web service, which adds two numbers, from a Visual Basic client.

As you see in the preceding code, you can call a Web service method as if it were a member of the SoapClient object. This simplifies the development of the client applications.

The SOAP toolkit retrieves information about how to interpret and use a Web service from the WSDL document of the Web service. In addition, the toolkit provides a tool, called the WSDL generator, to SOAP-enable existing COM components. The WSDL generator accepts the path for a COM component as input, analyzes its type library, and creates a Web service consisting of a WSDL file, a WSML file, and an ASP file.

Note?/td>
You learned about WSDL files in "Introduction to WSDL." The WSML file is not a standard file. It is a Web Services Meta Language file that is specific to the Microsoft toolkit. WSML is an XML file that maps SOAP messages to the original COM interfaces.

When a COM component method is called and the method returns a value, the value is serialized into SOAP format and passed on to the SoapClient object, which further deserializes the SOAP response and returns the appropriate COM data type. This serialization and deserialization happens automatically when the value passed is compatible to one of the XSD types. When the value is a custom data type or an object, such as an ADODB recordset, then the SOAP toolkit allows the creation of custom type mappers. You will learn to create a custom type mapper in the section "Handling Recordsets and Other Custom Data Types in SOAP Messages."

The SOAP toolkit allows you to create both ASP-based and ISAPI-based Web services. Having discussed the SOAP toolkit in general, we will now move on to creating the Web service from an existing COM component by using the Microsoft SOAP toolkit.

Creating a Web Service by Using the Soap Toolkit 2.0

In this section, you will learn to create a Web service from a COM component.

Before creating the application, it is important to discuss the working of the Web service. The existing COM component contains methods that allow applications to query a database and returns data as an ADODB recordset. The Web service needs to convert this data into SOAP format because the ADODB recordset is not an XSDdefined data type. The requesting application then processes the SOAP message to retrieve and display the data.

The first step in the creation of a Web service is to reuse the existing COM component. The COM component is called GetData.dll. The DLL file for the COM component has several classes. You can use these classes to query the CNS database. This chapter will concentrate on the ExecSP class. The ExecSP class has two methods: getAll() and getByCategory(). The signature of these methods is as follows:

Note?/td>
To get the implementation details of these methods

As you see, the ExecSP.getAll() method does not accept a parameter, but it returns an ADODB Recordset object that contains information on the products in the CNS database. The second method accepts the name of a category as a parameter and returns data of all products in this category.

We will now create the Web service that reuses the preceding component. To create a Web service that reuses any COM component, you need to use the Microsoft SOAP Toolkit 2.0.

To create a Web service by using the Microsoft SOAP Toolkit 2.0, follow these steps:

  1. Start the WSDL Generator of the Soap Toolkit 2.0.
  2. Figure shows the Start page of the Soap Toolkit 2.0 WSDL Generator Wizard.

    Soap Toolkit 2.0 WSDL Generator Wizard

    Soap Toolkit 2.0 WSDL Generator Wizard

  3. Click on the Next button. This will display the Soap Toolkit 2.0 Wizard dialog box.
  4. In the dialog box, enter the name of the Web service as Product Summary. The wizard creates the WSDL and WSML files with this name.
  5. Click on the Select COM object button and browse for the path for the GetData.dll file (see Figure).
  6. Naming the Web Service

    Naming the Web Service

  7. Click on the Next button.
  8. Figure shows a tree view of the classes and methods that are contained in the COM component

    The Component Classes and Methods

    The Component Classes and Methods

  9. Select the classes and methods that you need to include in your Web service. With the GetData.dll component, select the getByCategory() and getAll() methods.
  10. Note?/td>
    When you select the getByCategory() and getAll() methods, a note displays on the screen. The note states that if any method that you select returns a value of a data type that the Soap Toolkit does not recognize, the data type will be written as ??????? in the WSDL file that is generated.

  11. Click on the Next button.
  12. The Soap Listener Information screen is displayed.

    In the first text box of the Soap Listener Information screen, type the URL where you want to host the Web service. In this case, you can host the Web service at the http://ServerName/ProductSummary URL.

  13. To create an ASP-based Web service, select the listener type as ASP and the XSD type as 2001
  14. The SOAP Listener Information Screen

    The SOAP Listener Information Screen

  15. Click on the Next button. The wizard displays the screen shown in Figure.
  16. Specifying the Folder for the WSDL and WSML Files

    Specifying the Folder for the WSDL and WSML Files

    As you can see, UTF-8 is selected by default. You also need to specify the folder where the files that the wizard generates will be saved.

  17. After specifying the path, click on the Next button.
  18. Clicking on the Next button starts the file generation process. After the files are generated, you will get a warning message, as shown in Figure. The message indicates that some of the methods had data types that the Soap toolkit didn't understand; therefore, the data types are replaced by ?????? in the WSDL file.

    The Data Type Error Message

    The Data Type Error Message

  19. Click on the OK button.
  20. Click on the Finish button. The wizard creates the following files:
  • ProductSummary.wsdl
  • ProductSummary.wsml
  • ProductSummary.asp

The ProductSummary.wsdl File

The ProductSummary.wsdl file is the Web service description file that contains information about the Web service and the operations that it supports. The operations supported by a Web service are contained in the <message> elemen of the WSDL file. We will now discuss the content of the WSDL file in detail.

The WSDL file contains the declarations for the SOAP messages that interact with the getAll() method of the component. The syntax of the SOAP messages as generated by the wizard is as follows:

As discussed earlier, the getByCategory() method accepts a string as a parameter and returns a recordset. Therefore, to interact with the getByCategory () method, you need to declare a pair of SOAP messages as shown here:

As you can see, the preceding code snippet contains the type='xsd: ???????'/> declarations. This is because the return type of the methods in the COM component is ADODB. Recordset, which is not a data type that the SOAP toolkit recognizes.

After declaring the pair of SOAP messages, you need to bind the operations (getAll and getByCategory) to the corresponding messages. You can accomplish this by using <portType> declarations. For example, the operation getAll has an input message, getAll, and an output message, getAllResponse. The following code snippet shows the <portType> declarations:

After binding the operations to corresponding messages, you need to bind the operations to corresponding ports. To do this, you use the <bindings> section as shown in the following code snippet:

Next, the WSDL file contains the <service> section that identifies the name of the Web service and its location. The <service> section is shown in the following code:

The ProductSummary.wsml File

Next, consider the WSML file that the wizard creates. This file is used to map the Web service and its operation to the COM component and its methods. The WSML file is an XML document as shown:

The ProductSummary.asp File

The ASP file provides an interface for external applications to communicate with the Web service. The content of the ASP file is as shown:

The wizard has created a basic Web service for you. However, you will not be able to use this Web service because the WSDL file still has the ?????? declarations for the values returned by two of the SOAP messages. You will fix this in the next section.

Handling Recordsets and Other Custom Data Types in SOAP Messages

To handle custom data types that the SOAP toolkit does not support, you need to modify the declarations in the WSDL file. Follow these steps to modify the declarations:

  1. Modify the WSDL file that the wizard created.
  2. Create a handler for the data type.

Open the WSDL file in a text editor. Consider the <types> node in the WSDL file.

The ComplexType declaration in the preceding code depends on the data type for which you need to create a custom mapper. For example, consider a method that returns an object of the type Distributor. The following code is the declaration for the Distributor class:

You can create a <complexType> declaration for the Distributor class as follows:

After declaring the complex type for the recordset, you need to replace the ??????? in the data type declarations of the WSDL file with the complex type that you created:

Now, the WSDL file is created. The next step is to create a component that will do the custom type mapping. To do so, perform the following steps:

  1. Start Visual Basic 6.0 from the Programs menu.
  2. Create a new COM component.
  3. Rename the project as CustomMapp.
  4. In the Project, References menu, add a reference for the following:
  • Microsoft ActiveX Data Objects 2.5 library
  • Microsoft XML type library
  • Microsoft SOAP type library

The project contains a default class Class1. This class handles the type mapping; therefore, this class should implement the SoapTypeMapper interface. To do this, you need to add the following code to the class:Implements MSSOAPLib.ISoapTypeMapper

In addition to the SoapTypeMapper interface, the class should implement the methods of the interface. Therefore, you need to add the following code to the class:

The preceding code contains the ISoapTypeMApper_Write() function, which is used to perform the actual type mapping. Therefore, the contents of the recordset are converted into a data stream object, and the string containing the XML data is passed to the SoapSerialized object.

After writing the code, you need to compile it into a DLL file. This creates a custom type mapper DLL that you need to bind to the Web service. To bind the mapper DLL to the Web service, perform the following steps:

  1. Open the WSML file.
  2. The file currently contains a reference to the GetData.dll COM component, as shown here:

  3. Add a reference to the CustomMapp.dll file, as shown in the following code:
  4. Link CustomMapp.Class1 to the RecordSetXML complex type that you have declared in the WSDL file by adding the following <types> declaration in the WSML file:
  5. Save the file.

The Web service for CNS is now created. After creating the Web service, you need to test it before deploying it at the client site.

Testing the Web Service

To access the Web service, you need to create a proxy component that consumes the Web service. The clients, in turn, will use this component to access the Web service. To create a proxy component, perform the following steps:

  1. Start Visual Basic 6.0 from the Programs menu. Name the project ClientProxy.
  2. Create a new project of the type ActiveX DLL.
  3. In the Project, Reference menu, add a reference to the Microsoft SOAP type library and the Microsoft XML type library.
  4. The project contains a default class: Class1.
  5. Add the following code to Class1:

As you can see, both getAll() and getByCategory() function in a similar way. Both initialize the SoapClient object by calling the mssoapinit() method. Then the code calls the Web service method, getAll(), which returns the XML data that is converted to a string value.

Compile the project and create the DLL file.

Next, you will create a client application in Visual Basic 6.0. his application connects to the Web service, calls one of its methods, and displays the data that the service returns. The client application can connect to the Web service through the client proxy that you have created. As discussed earlier, the proxy component returns a string value, which contains the XML form of the recordset object, returned by the original COM component. Therefore, the client application needs to convert this data back to a recordset object and display it in a DataGrid (OLEDB) control. To convert the XML data to a recordset object, perform the following steps:

  1. Start Visual Basic 6.0 from the Programs menu.
  2. Create a new project of the type Standard EXE.
  3. In the Project, References menu, add a reference to the ClientProxy.DLL file and the Microsoft XML type library.
  4. Select Components from the Project menu.
  5. Note?/td>
    We will refer to the application that we created in the previous steps as the test application.

  6. In the resulting dialog box, select ADODC and DataGrid (OLEDB) controls.
  7. Add the Data control and the DataGrid control to the form along with a Button control. After adding these controls,the form should look like Figure.
  8. The Test Application

    The Test Application

  9. In the Click event handler for the button control, add the following code:

The preceding code retrieves a string containing the XML data. Next, the code writes the string into an ADODB.Stream object and then inserts the string into a recordset object. As you will notice, the whole process is the reverse of what you did to serialize the data in recordset in the custom type mapper application. Finally, the code sets the data source property of the DataGrid control to Adodc1, where Adodc1 is the instance of the ADODC control on the form.

Setting Up the Web Service

Web service files and the test client application are ready. Now, you need to set up the Web service. To do this, perform the following steps:

  1. In the Control Panel, Administrative Tools, run the Internet Services Manager (ISM). The ISM is shown in Figure.
  2. Internet Services Manager

    Setting Up the Web Service

  3. Right-click on Default Web Site.
  4. In the resulting menu, select New and Virtual Directory. Doing so launches the Virtual Directory Creation Wizard.
  5. Click on the Next button.
  6. In the Virtual Directory Creation Wizard, you need to specify the name or alias for the virtual directory.

  7. Enter the name as ProductSummary in the screen that appears.
  8. The Virtual Directory Creation Wizard

    The Virtual Directory Creation Wizard

  9. Click on the Next button.
  10. In the resultant screen, you need to specify the path for the Web site content directory. The resultant screen is shown in Figure.

    The Web Site Content Directory Screen

    The Web Site Content Directory Screen

  11. Select the folder that contains your Web service files.
  12. Click on the Next button. The Access Permissions screen appears, as shown in Figure
  13. The Access Permissions Screen

    The Access Permissions Screen

  14. Click on the Next button.
  15. In the resulting screen, click on the Finish button to complete the creation of the virtual directory.
  16. After setting up the Web service, you can now run the test application and verify the data that is displayed in the DataGrid control.

Securing the Web Service

After creating and testing the Web service, the next step is to secure the Web service. SOAP currently does not implement security; instead, it delegates security to the Transport layer. In this case, the Transport layer is HTTP. A Web service that you have created is an example of a Web application running on the IIS/Windows 2000 platform. Therefore, all methods of securing Web applications also apply to the Web service.

Securing a Web service includes preventing unauthorized access to it. You can accomplish this by authenticating the users who connect to the Web service. Several methods allow you to authenticate users. However, if you do not use an authentication method, the Anonymous Access mode is enabled by default.

We will now discuss the authentication methods in the following list:

  • Basic authentication method. This method is a basic and insecure method. In this method, to connect to a Web service, the client needs to supply a username and password. This username and password are sent over the wire with base-64 encoding and no encryption. Therefore, the username and password can be trapped and used to access other resources.
  • Note?/td>
    Base-64 encoding/decoding is a convention for converting binary data to a string of printable, alphanumeric characters. This technique is taken from RFC 1521.

  • Digest authentication method This method is a new method that was introduced in Windows 2000 and is part of the HTTP 1.1 standard protocol. However, it is not widely supported on other Web servers and platforms. The main limitation of the digest 114 authentication method is the lack of support from other Web client and server implementations. The digest authentication method is more secure than the basic authentication method.
  • Kerberos authentication method. This method is used on the Windows 2000 operating system. Even though it is a secure authentication method, its main drawback is that it is used for the Windows 2000 operating system only. This authentication mode is better suited for an intranet environment.
  • Windows integrated authentication method. This method is the native Windows authentication scheme, although it is implemented differently on different versions of Windows. The main drawback of Windows integrated authentication is that it is used only for Windows. Also, it does not work through proxies. It is the best scheme for an intranet consisting of Windows-based machines.
  • SSL and client certificates authentication method. This method involves the use of digital certificates for authentication. A server verifies its own identity through a server side digital certificate, and a client application can provide proof of its identity through a client side digital certificate. A Certification Authority (CA), such as VeriSign, issues the digital certificate. Using SSL with basic authentication ensures that the usernames and passwords are encrypted when they're sent over the wire. As a result, this is a secure and popular form of authentication.

Having looked at various ways in which you can secure your Web service, you will now secure your Web service by using the basic authentication method. To do this, perform the following steps:

  1. From the Start menu, select Programs, Administrative Tools, Internet Services Manager.
  2. In the Internet Services Manager, select the Web server or the virtual directory that you had previously set up for the ProductSummary Web service.
  3. Right-click the virtual directory, and in the resulting menu, select Properties. The Properties dialog box is displayed.
  4. In the Properties dialog box, select the Directory Security tab. The Directory Security dialog box is shown in Figure.
  5. The Directory Security Dialog Box

    The Directory Security Dialog Box

  6. In the Anonymous Access and Authentication Control section, click on the Edit button.
  7. In the resulting Authentication Methods dialog box, clear the Anonymous Access check box, if it's checked. You have now disabled anonymous access.
  8. Select the Basic Authentication check box. A dialog box is displayed that warns you of the perils of using basic authentication. Ignore it for now and click on the Yes button.

Now,try to connect to the Web service from the test client application that you created. You will get an Access Denied error message.

For the client to authenticate itself to the Web service, make the following changes to the ClientProxy DLL:

You can use the ConnectorProperty() method of the SoapClient class to pass the username and password to the Web service. If the virtual directory where the Web service is located requires authentication, you can pass it as shown:

Compile and generate the ClientProxy.dll file again with the previous changes. Run the test application and verify the connectivity to the Web service.

The basic authentication is now enabled for the Web service. The next step is to make the authentication more secure by adding an SSL Certificate. To do this, you can use the SSL trial feature at VeriSign.com.

However, before you request for a trial certificate, you need to prepare a certificate request. To prepare a certificate request, perform the following steps:

  1. In the control under Administrative Tools, open the Internet Services Manager.
  2. Open the Properties dialog box for the Web site that hosts your Web service.
  3. Right-click on the Web site name in the tree view and select Properties in the resulting dialog box. This opens the Web Site Properties dialog box shown in Figure.
  4. The Web Site Properties Dialog Box

    The Web Site Properties Dialog Box

  5. Click on the Directory Security tab.
  6. In the Directory Security tab, click on the Server Certificate button in the Secure Communications section. The IIS Certificate Wizard is invoked, as shown in Figure Click on the Next button.
  7. The IIS Certificate Wizard

    The IIS Certificate Wizard

  8. Select the Create a New Certificate option.
  9. Click on the Next button, and in the resulting dialog box, select Prepare the Request Now, But Send It Later option, as shown in Figure.
  10. Creating the Certificate Request

    Creating the Certificate Request

  11. Click on the Next button. The resultant dialog box is shown in Figure.
  12. The Name and Security Settings Screen

    The Name and Security Settings Screen

    In the screen shown in Figure, decide the encryption strengths for the keys that the certificate generates. The bit length of the encryption key depends on your need for security and speed. A higher bit length makes your application more secure, but if you are running a processor- and memory-intensive application over SSL, then a larger key might slow down your application.

  13. The Internet Services Manager creates a public/private key pair. The private key is stored locally on your machine, and the public part can be sent to a CA as part of a Certificate Signing Request (CSR).
  14. Create the CSR by entering your company's details. When you create a certificate for commercial use, you need to enter the data in the registration documents of the company.
  15. In the next few dialog boxes, enter the details about your company and contact information of the technical contact for the Web site.
  16. Specify the path and file name to store the CSR, as shown in Figure.

    Saving the File with the CSR.

    Saving the File with the CSR.

  17. When you specify the path, the wizard displays a confirmation screen with the data that you have entered. Click on the Finish button to generate the request file. After the file is created, you can open it. The content of the file is displayed as shown:

    opening the File with the CSR

The content is encrypted, so it is not intelligible.

The next step is to approach a CA for an SSL certificate.The certificate will be in a format similar to the request. A sample certificate response sent through e-mail is as shown:

To install the certificate, perform the following steps:

  1. Add the previous content to a text file.
  2. Run the Internet Services Manager.
  3. Open the Properties dialog box of the Web site for which you will install the certificate.
  4. Click the Directory Security tab.
  5. Under the Secure Communications section, click on the Server Certificate button.
  6. In the Web Site Certificate Wizard, click on the Next button. The dialog box should now look like Figure.

    The Pending Certificate Request Page.

    The Pending Certificate Request Page.

  7. Click on the Process the Pending Request and Install the Certificate option.
  8. Click on the Next button. Browse and locate the certificate response file that you save with the .cer extension.
  9. Click on the Next button.
  10. In the Summary screen, verify that you are installing the correct certificate; then finish the certificate installation.

You now have a server certificate installed. To securely connect to the Web service, you now have to use https instead of http.

To connect to the newly secured Web service from the Visual Basic client, perform the following steps:

  1. Change the code in the ClientProxy DLL project as shown:
  2. Re-create the client proxy DLL file and run the test application.
  3. Verify the connectivity with the Web service.

You have created a secure and functional Web service. You can now test the functioning of the service from an ASP page. The ASP page also uses the client proxy that you have created. The code for the ASP page is given next:

The code for the ASP page is similar to the test Visual Basic application you created previously. Here, a string that contains the XML data is received from the Web service and an ADODB recordset is populated from the data. The first three fields of the first record in the recordset are then displayed. Create a virtual directory for this ASP page and verify the functioning of the Web service.



Face Book Twitter Google Plus Instagram Youtube Linkedin Myspace Pinterest Soundcloud Wikipedia

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

XML Topics