Microsoft SOAP Toolkit Version 2.0 FAQ

  • Article

 

Microsoft Corporation

August 2001

Summary: This article provides in-depth answers to frequently asked development questions regarding Microsoft SOAP Toolkit 2.0. (12 printed pages)

January 2005 Update: SOAP Toolkit 2.0 is no longer supported. Information in this article may apply to SOAP Toolkit 3.0, which has been deprecated by the Microsoft .NET Framework. See the SOAP Toolkit page on the MSDN Web Services Developer Center for information on available support for SOAP Toolkit 3.0.

Contents

1.1 What's the latest Soap Toolkit Version?
1.2 How do I run the Soap trace utility?
     To use MSSOAPT to trace on the server:
     To use MSSOAPT to trace on the client:
1.3 What do I have to do to get SSL to work?
1.4 Why didn't the SMO Generator install?
1.6 How do I get the Soap Toolkit to interoperate with Apache?
1.9 What is WSDL?
1.10 Where is the WSDL Standard?
1.11 Why can't I read the WSDL file when I run my client in an ASP?
1.11 What is WSML?
1.12 Why would I use SMO instead of the high-level interface?
1.13 When do I use the ISAPI listener instead of ASP?
1.14 Why doesn't the ISAPI work on my virtual root?
1.15 Are arrays supported in the Soap Toolkit?
1.19 What does the Soap Toolkit fault Detail element contain?
1.20 Why do I get a library not registered error?
2.1 What's the deal with XSD namespaces?
2.2 How do I install Soap on clients?
2.3 Why does my client complain that my server component can't be found?
2.4 Does the Soap Toolkit support COM EXE's as server objects?
2.5 Why can't WSDLReader be called from a script?
2.6 Why doesn't my character encoding work on NT4?
2.7 How do I write XML into my message using the low-level interface?
2.8 Why do I get an Access Denied error?
2.9 What do those SoapConnector HResults mean?
2.10 Why doesn't my client work when I move the Soap Server to another machine?
2.11 How to I implement a Soap Client without installing the Soap Toolkit on all my clients?
2.12 How do I secure my Soap Application?
2.13 Why don't my Client Certificates work?
2.14 How do I get support for Soap Toolkit 2.0 problems?
2.15 Is the Soap Toolkit supported on Windows 95?
2.16 Why doesn't my low-level API application work?
2.17 My IIS Server is returning an HTTP status code. What does it mean?
2.18 How do I get my WebService Behaviors questions answered?
2.19 When will the next Soap Toolkit be released?
2.20 Why can't I do more than 5 Soap calls a second from a single Soap Client?
2.21 Why can't the Soap Toolkit read the WSDL from this site?

1.1 What's the latest Soap Toolkit Version?

Version 2.0 SP2, released June 21, 2001, is available at: https://msdn.microsoft.com/library/default.asp?url=/downloads/list/websrv.asp.

1.2 How do I run the Soap trace utility?

  • To trace on the server using MSSOAPT:

    1. Modify the location attribute of the soap:address element in the WSDL to direct clients to port 8080. For example, if the WSDL contains <https://MyServer/VDir/Service.wsdl>, change it to <https://MyServer:8080/VDir/Service.wsdl>.
    2. Run MSSOAPT on the server.
    3. Choose File, New, Formatted Trace (if you don't need to see HTTP headers) or File, New Unformatted Trace (if do want to see HTTP headers like ContentType and SoapAction).
    4. Click OK on the Trace Setup dialog to accept the default values.

    Now all requests/responses to/from the address specified in the WSDL willshow up in the trace.

  • To trace on the client using MSSOAPT:

    1. Make a local copy of the service's WSDL document.
    2. Modify the location attribute of the soap:address element in the WSDL to direct the client to localhost:8080 and make a note of the current host and port. For example, if the WSDL contains <https://MyServer/VDir/Service.wsdl>, change it to <https://localhost:8080/VDir/Service.wsdl> and make note of "MyServer".
    3. Run MSSOAPT on the client.
    4. Choose File, New, Formatted Trace (if you don't need to see HTTP headers) or File, New Unformatted Trace (if do want to see HTTP headers).
    5. In the Trace Setup dialog, enter the host and port noted in step 2 as the destination host and destination port values, then click OK.

    Now, any request/response sent from/to the client will show up in the trace.

1.3 What do I have to do to get SSL to work?

Assuming your server is set up to require SSL, you should only have to change the URL in the WSDL file (or the Soap Connector URL if you are using the low-level interface) to start with HTTPS instead of HTTP. It's not necessary to set the UseSSL property on the client. When this doesn't work, the most common causes are that the Server certificate has expired or the server requires a client certificate. Note that we commonly hear "it works OK with an HTTP URL but fails with an HTTPS URL." If the virtual root is set up to require SSL, it won't work with HTTP so this statement means your server is not set up to require SSL.

Some other common problems:

  • Please make sure the certificate is valid and has trusted root—open this certificate (dblclick on it) and check if there are warnings on it.

  • Please make sure your server has ssl configured correctly—serverside certificate is valid, has trusted root and its root is installed in LOCAL_MACHINE store.

  • You can't use localhost as the hostname—the hostname in the URL should match hostname in the server-side certificate.

  • To look your certificates if you don't have mmc tool on your machines, you can use IE—go to Tools/Options/Content/Certificates/.

  • If you have your server vdir set up to require client certificates —you can check which available client certificates you can use by accessing vdir through Microsoft Internet Explorer. IE will display a list of client certificates that have roots trusted on the server. If you have IE 5.5, disable the "Miscellaneous\Don't prompt for client certificates selection when no certificates or only one certificate exists" flag in Security settings

    A good explanation of these and other problems can be found in the MSDN article, Building Secure Web Services with Microsoft SOAP Toolkit 2.0.

1.4 Why didn't the SMO Generator install?

The option to install the SMO Generator should be visible when the
"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\6.0\Setup\Microsoft
Visual Basic\ProductDir" registry key is found. Please use regedit to see if
this key is present.

1.6 How do I get the Soap Toolkit to interoperate with Apache?

Before version 2.1, Apache required xsi:type attributes for all Soap parameters. Also, the Soap Toolkit does not normally send the xsi:type in Soap messages. Apache version 2.1 no longer requires xsi:type attributes if the types are defined in the deployment descriptors. However, Apache services don't yet use WSDL, so a WSDL file will have to be created for a Soap Toolkit client to talk to an Apache server. The RTM Soap Toolkit has been successfully tested with Apache 2.2.

Another trick that works sometimes is editing the WSDL file after it has been generated to change the types that Apache is having trouble with to "xsd:anyType". This will make the toolkit think the parameter is a variant, so it will include the type information that Apache is looking for.

1.9 What is WSDL?

WSDL is a standard, structured way of describing Soap messages and Web Services. The Soap Toolkit is dependent upon WSDL to create and interpret Soap Messages, so a WSDL file is required for any Soap Toolkit 2.0 client or server. If you want a Soap Toolkit 2.0 client to communicate with a Soap Server that doesn't supply a WSDL, you must create a WSDL file that describes the messages the Soap Services expects. I find the easiest way to do this is to create a dummy interface in Microsoft® Visual Basic® that matches what the server expects and use WSDLGen on the VB dll to create the WSDL file. You may also create the WSDL file by hand. If you want a non-WSDL enabled Soap client to talk to a Soap Toolkit 2.0 Service, just use the WSDL file as a description of what the Soap message needs to look like and translate this to whatever mechanism the client uses to create Soap messages.

1.10 Where is the WSDL Standard?

The W3C has acknowledged the submission of the WSDL 1.1 specification. It can now be found at https://www.w3.org/TR/wsdl.

1.11 Why can't I read the WSDL file when I run my client in an ASP?

WSDL Files are loaded into a DOM in the WSDL reader using MSXML's http interface. Running the MSXML HTTP stack in an ASP page requires the use of the ServerHTTPRequest option. To enable this do the following:

  1. Set the "ServerHTTPRequest" ClientProperty to true. Example:
    SoapClient.ClientProperty("ServerHTTPRequest") = True

  2. Need to run proxycfg.exe (See Knowledge Base article Q289481).

    Another option is to use a local filepath to specify the WSDL:
    mssoapinit ("C:\wsldfiles\MyProject.wsdl")

1.11 What is WSML?

WSML is best described as the Soap Toolkit configuration file. It contains the information required to map the Soap message described by a WSDL file to a COM interface. This includes the standard COM'isms like ProgID's and DispID's. WSML will never be a standard because it makes sense only to the Soap Toolkit.

1.12 Why would I use SMO instead of the high level interface?

While some overlap exists between the two, the high-level interface is at its best in traditional RPC type applications. SMO, meanwhile, is better at performing message-oriented applications. If you wish to use Soap to exchange XML documents, SMO is the best choice. If you want to use Soap to execute operations on a remote host, the high-level interface is probably a better choice. SMO provides an interface that is easier to use to create complex XML documents than the high level interface.

1.13 When do I use the ISAPI listener instead of ASP?

My answer is pretty much always. The ISAPI is faster and easier to use than an ASP page, so unless you need to do something the ISAPI doesn't do or you are using SMO, I would recommend using the ISAPI.

1.14 Why doesn't the ISAPI work on my virtual root?

When the ISAPI is installed, it registers itself to handle ".WSDL" files. Soap Toolkit 2.0 installation does this by creating an "App Mapping" to associate the ".WSDL" extension with soapisap.dll at the machine (server) level. If the "App Mappings" have changed at a lower node than the machine level (such as at the "Web Site" or "Virtual Directory" level) prior to SoapToolkit 2.0 installation, then the newly added ".WSDL" mapping will not be inherited from the machine level settings. In this case you can manually enter the "App Mappings" at the lower-level node using the IIS MMC Admin tool.

For example, here are the steps to manually add the "App Mappings" for the "Default Web Site" on IIS 5.0 using the IIS MMC Admin tool (make sure you have local admin rights before attempting this):

  1. Select the Home Directory tab under the properties for the "Default Web Site."

  2. On the Home Directory tab, click the Configuration button and select the App Mappings tab.

  3. If the .wsdl extension does not exist, then add a new extension entry for .wsdl by clicking the Add button.

  4. Enter the path to soapisap.dll.

    Note Because of a bug in the UI of the IIS Admin tool a pathname with spaces cannot be added. To workaround this problem, enter the short-file pathname to the soapisap.dll (Example: C:\PROGRA~1\COMMON~1\MSSOAP\BINARIES\SOAPISAP.DLL). Enter .wsdl in the "Extension" text box. If you are using Microsoft® Windows® 2000, for "Verbs" select Limit to and add: GET, POST, HEAD. If you are using Windows NT® 4, leave the Exclude box blank. Finally, "Script Engine" should be checked and "Check that files exist" should be unchecked. Now click OK to enter the new entry.

    Note Although, the above steps will add the "App Mappings" at the "Default Web Site" level, the same procedure can be followed at lower levels such as the "Virtual Directory" level.

1.15 Are arrays supported in the Soap Toolkit?

One-dimensional arrays of simple types, arrays of complex types and multi-dimensional arrays are supported in the Soap Toolkit. Several improvements and fixes to array handling are included in the next service pack.

1.19 What does the Soap Toolkit fault Detail element contain?

The detail section is namespace qualified, using the following namespace:

https://schemas.microsoft.com/soap-toolkit/faultdetail/error/

All Soap Toolkit specific information goes into the following skeleton:

<soap:fault....>
<detail>
<mserror:errorInfo 
xmlns:mserror="https://schemas.microsoft.com/soap-
         toolkit/faultdetail/error/">
     <mserror:returnCode></mserror:returnCode> 
    <mserror:serverErrorInfo>
        <mserror:description></mserror:description> 
        <mserror:source></mserror:source> 
        <mserror:helpFile></mserror:helpFile> 
        <mserror:helpContext></mserror:helpContext> 
     </mserror:serverErrorInfo>
   <mserror:callStack>
      <mserror:callElement>
         <mserror:component></mserror:component> 
           <mserror:description></mserror:description> 
           <mserror:returnCode></mserror:returnCode> 
        </mserror:callElement>
     </mserror:callStack>
  </mserror:errorInfo>
  </detail>

Therefore, assuming we have assembled rich error information, we will create the extended errorinfo section starting with the mserror:errorInfo element. Inside the first child is the returnCode, which goes into the HR of the Error object on the client.

If the failure was caused by something providing an errorinfo object itself on the server (such as the servercomponent getting called), then (and only then, so the following is not always needed) we create the mserror:serverErrorInfo section. All fields in this section are optional—although when a helpfile is persisted you always get a helpContext in addition—and the fields will only be persisted if the server had information in them. These fields, if present, go into the Error object on the client.

1.20 Why do I get a "library not registered" error?

The error "library not registered" has been seen when attempting to execute: Server.CreateObject("MSSOAP.SoapServer").

The cause of this error has been traced to the typelib registry key not giving the "Everyone" group read access. This is most likely the result of a prior installation of Crystal Reports 8.0 (see https://support.microsoft.com/support/kb/articles/Q266/6/21.ASP).

2.1 What's the deal with XSD namespaces?

You may encounter three versions of the XSD namespace in Soap applications: 1999, 2000/10, and 2001. The Soap Toolkit 2.0 will accept messages with any of these three as long as the namespace in the message matches the one in the WSDL file. WSDLGen has been modified to enable you to specify which of the three namespaces you wish to use. If you don't need to use 1999 or 2000 for compatibility with an older Soap implementation, we recommend you stay with the 2001 default. Note that several datatype names have changed in the 2001 spec. See the documentation for details.

2.2 How do I install Soap on clients

This is truly an FAQ. The right answer is to use the .MSM files, which are available for download from the same page as the toolkit download. If you're careful to get all the DLL's in the proper directories and registered correctly, you could probably do your own installation; however, merging the .MSM's into your installation program is the safest and only supported way to do this.

2.3 Why does my client complain that my server component can't be found?

You may need to use a WSML file on the client if your Soap methods use custom type mappers. The WSML file specifies the progid of the custom mapper for the SoapClient to know where to find it. If your WSML file specifies the progid of your server component (as it will if you use the WSML generated for the server) you may want to remove the server component information so the SoapClient doesn't attempt to load your server component.

2.4 Does the Soap Toolkit support COM EXE's as server objects?

While this might work in some instances, this is not a tested or supported configuration. We suggest writing a DLL-based wrapper for the .EXE to handle this situation.

2.5 Why can't WSDLReader be called from a script?

WSDLReader does not expose a dispatch interface so it can't be used in a script.

2.6 Why doesn't my character encoding work on NT4?

Windows NT 4.0 does not support CHS:gb2312 or AR:iso8859-6 encodings.

2.7 How do I write XML into my message using the low-level interface?

Serializer.writeXML writes out XML without escaping. The documentation says it uses a CDATA section, but this is not actually the case.

2.8 Why do I get an Access Denied error?

Keep in mind that a Soap Toolkit application is a Web application. All Web servers have many safeguards to ensure that users are unable to access anything they shouldn't. This means that Access Denied is often the default state for a server application. A few things to check:

  • Make sure that the user your application is running as (IWAM_... or IUSR_... etc.) has read access to the WSDL & WSML files—check the file ACL and the IIS configuration.

  • Make sure that the Web application user has read and execute permissions for the dll that implements your Soap Service.

  • Make sure you virtual root is set up to allow read and execute permissions for the .wsdl extension.

  • This often happens when running your server object in the VB debugger. The anonymous user doesn't have sufficient permissions to activate an object in the VB debugger.

    This isn't an exhaustive list but it should give you some idea of where to start.

2.9 What do those SoapConnector HResults mean?

Error Decimal Hex
AMBIGUOUS 5000 1388
BAD_REQUEST 5050 13BA
ACCESS_DENIED 5051 13BB
FORBIDDEN 5052 13BC
NOT_FOUND 5053 13BD
BAD_METHOD 5054 13BE
REQ_TIMEOUT 5055 13BF
CONFLICT 5056 13C0
GONE 5057 13C1
TOO_LARGE 5058 13C2
ADDRESS 5059 13C3
SERVER_ERROR 5100 13EC
SRV_NOT_SUPPORTED 5101 13ED
BAD_GATEWAY 5102 13EE
NOT_AVAILABLE 5103 13EF
SRV_TIMEOUT 5104 13F0
VER_NOT_SUPPORTED 5105 13F1
BAD_CONTENT 5200 1450
CONNECTION_ERROR 5300 1464
BAD_CERTIFICATE_NAME 5301 1465
HTTP_UNSPECIFIED 5400 1518
HTTP_SENDRECV 5401 1519
HTTP_BAD_REQUEST 5402 151A
HTTP_BAD_RESPONSE 5403 151B
HTTP_BAD_URL 5404 151C
HTTP_DNS_FAILURE 5405 151D
HTTP_CONNECT_FAILED 5406 151E
HTTP_SEND_FAILED 5407 151F
HTTP_RECV_FAILED 5408 1520
HTTP_HOST_NOT_FOUND 5409 1521
HTTP_OVERLOADED 5410 1522
HTTP_FORCED_ABORT 5411 1523
HTTP_NO_RESPONSE 5412 1524
HTTP_BAD_CHUNK 5413 1525
HTTP_PARSE_RESPONSE 5414 1526
HTTP_TIMEOUT 5415 1527
HTTP_CANNOT_USE_PROXY 5416 1528
HTTP_BAD_CERTIFICATE 5417 1529
HTTP_BAD_CERT_AUTHORITY 5418 152A
HTTP_SSL_ERROR 5419 152B
WSDL_MUSTUNDERSTAND 7100 1BBC

2.10 Why doesn't my client work when I move the Soap Server to another machine?

One of the more common reasons for this to happen is that two different URLs may need to be changed. The SoapClient.mssoapinit call contains the location of the WSDL file (and optionally the WSML file). If these files are moved when the service is moved, the parameter will have to be changed to match. The actual URL for the Soap Service is specified in the WSDL file in the "location" attribute—this is the one that is often forgotten.

2.11 How do I implement a Soap Client without installing the Soap Toolkit on all my clients?

There is a script-based Soap implementation that does not require the installation of a Soap Toolkit.

2.12 How do I secure my Soap Application?

Soap is essentially a Web application, so all the security fundamentals that apply to Web applications apply to Soap. We have covered a few of the most commonly misunderstood areas in this FAQ, but security is too broad a topic to be covered here. Here's an article on Soap Security written by our test lead: https://msdn.microsoft.com/library/default.asp?url=/library/en-us/Dnsoap/html/Soapsecurity.asp?frame=true. The best resource I have found for setting up Web security is Michael Howard's book: Designing Secure Web-Based Applications for Microsoft Windows 2000, Microsoft Press; ISBN: 0735609950.

ASPToday also has several good security articles, among them: Securing Windows 2000 IIS 5.0 applications.

2.13 Why don't my Client Certificates work?

A common problem with Client Certificates is that there are multiple names in a certificate—the Friendly name and the Subject Name. The Subject name is the one to use when specifying the client certificate in the Soap Client. To find the subject name, use IE to navigate to IE/Tools/Internet Options/Content, and click the certificates button. The name to use is in the "Issued To" column. This name is often an X.500 name. If so, the CN is the part of the name that's required. See the Soap security article at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/Dnsoap/html/Soapsecurity.asp?frame=true for more information.

2.14 How do I get support for Soap Toolkit 2.0 problems?

Microsoft Support options overview is available at https://support.microsoft.com/directory/overview.asp?sd=gn&fr=0. You can choose the telephone or Web-based support from: https://support.microsoft.com/directory/directory.asp?sd=gn.

2.15 Is the Soap Toolkit supported on Windows 95?

Windows 95 is missing some system calls used by the Soap Toolkit code, so it cannot presently be supported.

2.16 Why doesn't my low-level API application work?

Some marshalling issues with the low-level objects cause problems when they are used across process boundaries (such as medium or high protection, COM+ server apps, and VB debugger). For now, use the low-level components inproc only. This issue will be fixed in a service-pack release.

2.17 My IIS Server is returning an HTTP status code. What does it mean?

Look it up at: https://msdn.microsoft.com/workshop/networking/wininet/reference/constants/statuscodes.asp.

2.18 How do I get my Web Service Behaviors questions answered?

The soapsdk newsgroup is not a good place. Instead, send questions to: iewctrls@microsoft.com.

2.19 When will the next Soap Toolkit be released?

The Soap Toolkit 3.0 should have its first beta late in fall 2001.

2.20 Why can't I do more than five Soap calls per second from a single Soap Client?

A registry setting was added to allow you to turn off the Nagling delay in the ISAPI server. Nagling prevents TCP from sending small packets by adding a delay after each buffer is received from the ISAPI on a particular connection in case another buffer is coming soon so the two can be combined. The delay is 200 ms, so most Soap operations have an extra 200 ms added to their execution time by the Nagling delay. This makes some simple-minded benchmarks that have a single Client calling the server in a loop report much worse results than they would with Nagling off. Obviously, even if the client and server took 0 time to execute, a single-client thread could not push more than five transactions per second to the server. In more realistic benchmarks with thousands of clients hitting the server in parallel, Nagling will often help performance by reducing the number of small packets sent. In general, if your benchmarks are giving much worse results than you think you should be getting, try turning off Nagling to see if it helps. To turn off the Nagling delay, change the "NoNagling" DWORD value in HKEY_LOCAL_MACHINE\Software\Microsoft\MSSOAP\SOAPISAP to one (1).

2.21 Why can't the Soap Toolkit read the WSDL from this site?

Look at the WSDL and see if it has an import statement. The 2.0 version of the toolkit doesn't yet support import. The only detour is to make your own copy of the WSDL file and use cut-and-paste to pull the imported information into the main file. This should be fixed in the 3.0 version of the toolkit.