1. Implementing and Accessing Web Services Using Visual Basic 6.0 and the Visual Studio SOAP Toolkit Karthik Ravindran Developer Support Engineer VB/ASP Web Database Microsoft Corporation

2. 2 Agenda  Background Web Services Web Services Current distributed object infrastructures Current distributed object infrastructures  SOAP Introduction Introduction Messaging Architecture Messaging Architecture Advantages and disadvantages Advantages and disadvantages  The Microsoft ® Visual Studio ® SOAP Toolkit Introduction - What is it ? Introduction - What is it ? What does it include What does it include Terminology Terminology Technologies Technologies

3. 3 Agenda (2)  ROPE – Remote Object Proxy Engine Introduction – What is it ? Introduction – What is it ? Purpose and usage Purpose and usage ROPE Objects ROPE Objects  Labs, process and code Walkthroughs Setting up a VB6 Web Service using the SOAP Toolkit Setting up a VB6 Web Service using the SOAP Toolkit Setting up VB6 ROPE clients to access a Web Service Setting up VB6 ROPE clients to access a Web Service Implementing a simple VB6 Web Services Discovery client using the ROPE Objects Implementing a simple VB6 Web Services Discovery client using the ROPE Objects Returning ADO recordsets in SOAP messaging Returning ADO recordsets in SOAP messaging  Q/A

4. 4 Web Services  A major shift in application development   Distributing and integrating application logic over the Web  Delivering software as a service accessible to anyone, anywhere, at anytime  Joining tightly coupled component technologies with loosely coupled Internet messaging standards loosely coupled Internet messaging standards  Components required to realize the concept of Web Services: Web Services: A standard messaging format for requests and responses A standard messaging format for requests and responses A service description language A service description language A Web Services Discovery Language/mechanism A Web Services Discovery Language/mechanism

5. 5 Distributed Object Infrastructures  Distributed object infrastructure = component technology + wire protocol  Current distributed object infrastructures: COM/DCOM, Java RMI/JRMP, CORBA/GIOP  Disadvantages of proprietary distributed object infrastructures: Vendor specific Vendor specific Platform specific Platform specific Lack of interoperability Lack of interoperability Administrative costs Administrative costs Custom runtime Custom runtime Configuring firewalls Configuring firewalls

6. 6 Introduction to SOAP   What is SOAP ? An Internet standard specification, the goal of which is to define a platform and vendor-neutral WIRE PROTOCOL based on Internet standard protocols [HTTP & XML] to define and access Web Services  Why SOAP ? Role of a ‘Wire Protocol’ in accessing distributed object services Vendor and/or platform-specific nature of current wire protocols hinder interoperability  SOAP Goals: Specify a platform independent Internet based format to package requests for services exposed by Web Services, and responses generates by Web Services [XML] Specify a platform independent Internet based format to package requests for services exposed by Web Services, and responses generates by Web Services [XML] Specify a platform independent format to describe Web Services [ XML ] Specify a platform independent format to describe Web Services [ XML ] Specify a platform independent Wire protocol [HTTP] Specify a platform independent Wire protocol [HTTP]

7. 7 Introduction to SOAP (2)  What SOAP is NOT ? SOAP is not a replacement for any of the current component technologies SOAP is not a replacement for any of the current component technologies It does not specify how key infrastructural elements of a Distributed Object Infrastructure need to be implemented [ eg: Distributed garbage collection, Object activation etc. ] It does not specify how key infrastructural elements of a Distributed Object Infrastructure need to be implemented [ eg: Distributed garbage collection, Object activation etc. ]

8. 8 Accessing a Web Service Using SOAP Accessing a Web Service Using SOAP CLIENT WS WEB SERVICE PROVIDER SOAP REQUEST PAYLOAD SOAP RESPONSE PAYLOAD SOAP RESPONSE PAYLOAD INTERNET/INTRANET 1 – Obtain/Examine SDL and Generate SOAP REQUEST 2 – Transmit REQUEST Payload [ HTTP POST ] 3 – Receive Request Payload on HTTP Port 80 4 – Parse Request, Process Request, and Generate SOAP RESPONSE 5 – Transmit RESPONSE Payload 6 – Receive and Parse RESPONSE SDL

9. 9 The SOAP Request Payload  A standard XML-based format to describe a SOAP request for a Web Service  Provides all the information required by the Web Service provider to process the request  General format of a SOAP request: HTTP Header SOAP Action

10. 10 The SOAP Response Payload   A standard XML-based format to describe the Response generated by a Web Service   Contains information that is to be passed back to the client   General format of a SOAP response: HTTP Header

11. 11 Advantages of SOAP  Tremendously lightweight. Requires two fundamental capabilities: Capability to send and receive HTTP packets Capability to send and receive HTTP packets Capability to process XML [ Requires an XML parser ] Capability to process XML [ Requires an XML parser ]  Built on open technologies  Facilitates true distributed interoperability  No firewall restrictions

12. 12 Disadvantages of SOAP  Based on HTTP, and is therefore Stateless Stateless Based on a request/response architecture – Implies no callback functionality Based on a request/response architecture – Implies no callback functionality  Performance is slightly degraded for the following reasons: An XML processor needs to be loaded each time to parse a SOAP request/response The SOAP request/response has to be parsed to extract the required information   Currently supports only parameter serialization by value   Will require XML processors that support full schema parsing, if XML schema extensions are used to format SOAP messages

13. 13 The Microsoft Visual Studio SOAP Toolkit – What is it?   A technology preview   Microsoft’s first step in demonstrating its commitment to supporting SOAP functionality in its development tools   Includes components that can be used to implement SOAP messaging/functionality in Visual Studio applications: Expose functionality implemented in COM components as Web Services Access Web Services using SOAP messaging   Microsoft’s SOAP based distributed object infrastructure – COM (Component Technology) + SOAP (Wire Protocol)

14. 14 The Microsoft Visual Studio SOAP Toolkit – What does it include?   An SDL Generator: Used to generate XML based Service Descriptions for Web Services   ROPE [ Remote Object Proxy Engine ]: A COM DLL which exposes objects that provide the infrastructure for binding SOAP clients and servers   Sample Applications   Online Documentation

15. 15 SOAP Toolkit Terminology  Web Service  Service description language  Web Services Discovery  SOAP Listener  ROPE  The SOAP Toolkit SDL Wizard

16. 16 Key SOAP Toolkit Technologies Key SOAP Toolkit Technologies  COM  XML Writing well-formed XML, schemas, and namespaces Writing well-formed XML, schemas, and namespaces  HTTP HTTP GET and POST HTTP GET and POST  IIS Setting up virtual directories Setting up virtual directories IIS security IIS security Directory permissions Directory permissions  ASP/ISAPI  Visual Studio development tools

17. 17 ROPE – Remote Object Proxy Engine   A COM DLL [ ROPE.DLL ]   Implements programmable objects that provide infrastructural services to bind SOAP clients and servers: Generating SOAP Request Payloads Generating SOAP Response Payloads Transporting the SOAP Requests and Responses using HTTP Interpreting Request payloads to extract method invocation information Interpreting Response payloads to extract results returned to the client   Advantages of using ROPE

18. 18 The ROPE Objects  ROPE.Proxy Provides a high-level interface that enables client applications to access remote Web Services exposed using the SOAP protocol as if they were local COM objects Provides a high-level interface that enables client applications to access remote Web Services exposed using the SOAP protocol as if they were local COM objects  ROPE.SOAPPackager Sending and receiving SOAP requests and responses Sending and receiving SOAP requests and responses Functionality for accessing contents of a SOAP envelope Functionality for accessing contents of a SOAP envelope  ROPE.WireTransfer Functionality for executing HTTP POST and GET Functionality for executing HTTP POST and GET  ROPE.SDMethodInfo Provides Information about methods exposed by a Web Service Provides Information about methods exposed by a Web Service

19. 19 The ROPE Objects (2)  ROPE.SDParameterInfo Describes the parameters for a method described by an SDMethodInfo object Describes the parameters for a method described by an SDMethodInfo object  ROPE.SDEndPointInfo Describes the URI location of a Web Service Describes the URI location of a Web Service  ROPE.ServiceDescriptors A collection of SDMethodInfo and SDEndPointInfo objects A collection of SDMethodInfo and SDEndPointInfo objects

20. 20 Lab 1: Installing the Visual Studio SOAP Toolkit  Instructions on downloading and installing the SOAP Toolkit  Exploring the SOAP Toolkit download – What does it contain?  Exploring the SOAP Toolkit documentation

21. 21 Setting UP a VB 6.0 Web Service  Create the VB COM DLL whose methods you wish to expose as Web Services – Stateless methods, parameters should be passed by value  Register the component on the Web server  Grant the IIS account(s) NTFS ‘Read & Execute’ access permissions to the component  Use the SOAP Toolkit SDL Generation Wizard to generate the SDL and the ASP interface for the service; specify an HTTP-accessible IIS virtual directory as the location to store the generated files  Place the generic ASP Listener in the IIS virtual directory that contains the SDL and ASP Interface for the Web Service

22. 22 SDL Generation Wizard – Screen 1 of 6

23. 23 SDL Generation Wizard – Screen 2 of 6

24. 24 SDL Generation Wizard – Screen 3 of 6

25. 25 SDL Generation Wizard – Screen 4 of 6

26. 26 SDL Generation Wizard – Screen 5 of 6

27. 27 SDL Generation Wizard – Screen 6 of 6

28. 28 Lab 2: Setting Up the PRODUCTS Web Service  Developing the PRODINFO COM DLL Implementing the PRODUCTS class module Implementing the PRODUCTS class module Methods: GetProducts(), GetUnitsInStock(ByVal ProductName as String) Methods: GetProducts(), GetUnitsInStock(ByVal ProductName as String)  Setting up the Web Service  Examining the SDL  Examining the ASP interface file

29. 29 Accessing the Web Service  The three server components that expose a SOAP Toolkit Web Service SDL document [generated by the wizard] SDL document [generated by the wizard] ASP/ISAPI interface [generated by the wizard] ASP/ISAPI interface [generated by the wizard] SOAP Toolkit Listener SOAP Toolkit Listener  Client components required to access a SOAP Web Service Rope.dll – Copy and register on the client workstation Rope.dll – Copy and register on the client workstation ROPE client – A Visual Studio/ASP application that utilizes the ROPE objects to access a Web Service ROPE client – A Visual Studio/ASP application that utilizes the ROPE objects to access a Web Service

30. 30 Server Components  What does the SDL document contain?  Interface files – What are they?  What is a SOAP Listener?  Types of VS SOAP Toolkit Listeners – ASP and ISAPI  Where are the generic Listeners located? ASP: :\Program Files\SOAP_Toolkit\ASP_Listener [Listener.ASP] ASP: :\Program Files\SOAP_Toolkit\ASP_Listener [Listener.ASP] ISAPI: :\Program Files\SOAP_Toolkit\ISAPI_Listener [soapisapi.dll] ISAPI: :\Program Files\SOAP_Toolkit\ISAPI_Listener [soapisapi.dll]  What does the generic ASP Listener do? How does it work with the ASP interface file?

31. 31 Examining the Key Sections of a Sample SDL  The SDL specifies the URL of the Web Service’s ASP interface file <service>  It contains XML-based specifications of the methods exposed by the Web Service </element>

32. 32 Examining an ASP Interface File <% Option Explicit Response.Expires = 0 'URI of service description file Const SOAP_SDLURI = http://karravms-srv2/soap/Products.xmlhttp://karravms-srv2/soap/Products.xml %> <% Public Function GetProducts () Dim objGetProducts Set objGetProducts = Server.CreateObject("ProdInfo.Products") GetProducts = GetXMLFromADORS(objGetProducts.GetProducts()) 'Insert additional code here Set objGetProducts = NOTHING End Function Public Function GetUnitsInStock (ByVal ProductName) Dim objGetUnitsInStock Set objGetUnitsInStock = Server.CreateObject("ProdInfo.Products") GetUnitsInStock = objGetUnitsInStock.GetUnitsInStock(ProductName) 'Insert additional code here Set objGetUnitsInStock = NOTHING End Function %>

33. 33 SDL ROPE WEB SERVICES PROVIDER COM Object ASP Interface ASP Listener Anatomy of a SOAP Web Services Provider

34. 34 SDL Your Client Code ROPE PROXY Anatomy of a ROPE Client

35. 35 SOAP Toolkit Client/Server Communication SDLs ROPE WEB SERVICES PROVIDER COM Object SDL Client Code ROPE PROXY ROPE Client ASP Interface ASP Listener SOAP Request/Response Payloads

36. 36 Accessing a Web Service using a ROPE Client Using the ROPE.Proxy Object  The ROPE.Proxy Object – What is it?   The LoadServicesDescription() method of the ROPE.Proxy Object: LoadServicesDescription icURI, “ ” LoadServicesDescription icSTRING, “ ”   Important properties of the ROPE.Proxy object ServicesDescription DataSent DataReceived FaultCode, FaultString, FaultDetail   ROPE.Proxy object uses the ROPE.SoapPackager and the ROPE.WireTransfer objects

37. 37 Using ROPE.Proxy to Access a Web Service: Code Walkthrough Dim rproxy As ROPE.Proxy Dim units As Integer Dim SelItem As String Set rproxy = New ROPE.Proxy rproxy.LoadServicesDescription icURI, "http://karravms- srv2/soap/Products.xml" If lstProducts.Text <> "" Then SelItem = lstProducts.Text SelItem = lstProducts.Text txtUnits.Text = rproxy.GetUnitsInStock(SelItem) txtUnits.Text = rproxy.GetUnitsInStock(SelItem) End If Set rproxy = Nothing Lab 3: Using the ROPE.Proxy Object to access the PRODINFO.PRODUCTS Web Service

38. 38 The ROPE.SoapPackager and ROPE.WireTransfer Objects  ROPE.SOAPPackager Sending and receiving SOAP requests and responses Sending and receiving SOAP requests and responses Access contents of a SOAP envelope Access contents of a SOAP envelope  ROPE.WireTransfer Execute HTTP POST and GET Execute HTTP POST and GET  The ROPE.Proxy object uses these two objects to send and receive SOAP requests and responses  Important methods of the ROPE.SOAPPackager object: LoadServicesDescription, GetMethodStruct, GetParameter, SetParameter, SetPayloadData LoadServicesDescription, GetMethodStruct, GetParameter, SetParameter, SetPayloadData  Important methods/properties of the ROPE.WireTransfer object Methods: AddStdSOAPHeaders, PostDataToURI Methods: AddStdSOAPHeaders, PostDataToURI Properties: DataSent, DataReceived Properties: DataSent, DataReceived

39. 39 Using the ROPE.SOAPPackager and ROPE.WireTransfer Objects to Access a Web Service  Lab 4: Using the ROPE.SoapPackager and ROPE.WireTransfer objects to access the PRODUCTS Web Service  SOAP payloads revisited Request and response SOAP payloads Request and response SOAP payloads HTTP requests and responses HTTP requests and responses XML parsers XML parsers  Lab 5: Examining the SOAP and HTTP request and response payloads generated by the ROPE.WireTransfer object

40. 40 Web Services Discovery  Concept of Web Services Discovery  Need for a Web Services Discovery Language  ROPE objects that aid in Web Services Discovery: ROPE.SDMethodInfo: Provides Information about methods exposed by a Web Service ROPE.SDMethodInfo: Provides Information about methods exposed by a Web Service ROPE.SDParameterInfo: Describes the parameters for a method described by a SDMethodInfo object ROPE.SDParameterInfo: Describes the parameters for a method described by a SDMethodInfo object ROPE.SDEndPointInfo: Describes the URI location of a Web Service ROPE.SDEndPointInfo: Describes the URI location of a Web Service ROPE.ServiceDescriptors: A collection of SDMethodInfo and SDEndPointInfo objects ROPE.ServiceDescriptors: A collection of SDMethodInfo and SDEndPointInfo objects  Lab 6: Implementing a simple Web Services Discovery Client using the ROPE ServiceDescriptors, SDMethodInfo, and SDParameterInfo objects

41. 41 SOAP Toolkit Data Types  Currently only scalar atomic data types are supported:  Currently only scalar atomic data types are supported: String, Integer, Double, Short, Float, Boolean, and Byte   Methods returning composite data types like ADO Recordsets and Arrays require: Manual modifications must be made to the SDL file to describe the composite data type – XML Schemas must be used to describe the composite type Additional wrapper code must be added to the ASP Interface to transform the return value into a form that can be packaged into a supported data type [ usually a String ] Custom code in the SOAP client to parse the return value and extract the required data   Lab 7: Handling ADO Recordsets: Accessing the GetProducts() method of the PRODUCTS Web Service

42. 42 Handling ADO Recordsets: Modifying the ASP Interface File Public Function GetProducts () Dim objGetProducts Set objGetProducts = Server.CreateObject("ProdInfo.Products") GetProducts = GetXMLFromADORS(objGetProducts.GetProducts()) 'Insert additional code here Set objGetProducts = NOTHING End Function   What does the function GetXMLFromADORS do? Transforms the data in the ADO Recordset to a well formed XML String Calls the CDataIt() custom function to enclose the XML string within a CDATA section

43. 43 Handling ADO Recordsets: Modifying the SDL File

44. 44 Handling ADO Recordsets: Parsing the Returned XML String in the SOAP Client Dim opxy As ROPE.Proxy Dim result As String Dim ResultXML As MSXML2.DOMDocument26 Dim rs As ADODB.Recordset Set opxy = New ROPE.Proxy opxy.LoadServicesDescription icURI, "http://karravms-srv2/soap/Products.xml" result = opxy.GetProducts() Set ResultXML = New MSXML2.DOMDocument30 ResultXML.setProperty "SelectionLanguage", "XPath" ResultXML.loadXML result Dim ProductList As MSXML2.IXMLDOMNodeList Dim Product As MSXML2.IXMLDOMNode Set ProductList = ResultXML.selectNodes("//ProductName") For Each Product In ProductList lstProducts.AddItem Product.Text Next Set opxy = Nothing

45. 45 XML Myths and Facts  Myths XML is a great language XML is a great language It is the panacea for all problems encountered in current programming languages and tools It is the panacea for all problems encountered in current programming languages and tools SOAP is a good example of applying XML to address a real-world development requirement SOAP is a good example of applying XML to address a real-world development requirement  Facts XML is a great markup language for exchanging data XML is a great markup language for exchanging data It is not a replacement for any application development tool or component technology It is not a replacement for any application development tool or component technology SOAP is a great example of applying XML to address a real-world development requirement SOAP is a great example of applying XML to address a real-world development requirement

46. 46 Additional Reading  Online documentation: The ROPE Samples Tutorial The ROPE Samples Tutorial Guide to using the SOAP Toolkit Wizard Guide to using the SOAP Toolkit Wizard Troubleshooting the SOAP Toolkit Troubleshooting the SOAP Toolkit  Returning ADO Recordsets with SOAP Messaging http://msdn.microsoft.com/xml/articles /soapguide_ado.asp http://msdn.microsoft.com/xml/articles /soapguide_ado.asp http://msdn.microsoft.com/xml/articles /soapguide_ado.asp  Understanding SOAP by Kennard Scribner ISBN: 0-672-31922-5 Publisher: SAMS ISBN: 0-672-31922-5 Publisher: SAMS NOTE: The above link is one path; it has been wrapped for readability.