This step-by-step article describes how to write a Perl SOAP::Lite client for a Web Service that is based on the Microsoft SOAP Toolkit or .NET.
NOTE: Microsoft does not provide support for Perl.
Requirements
The following items describe the recommended hardware, software, network infrastructure, skills and knowledge, and service packs that you need:
- Perl version 5.00503 or later
- Microsoft SOAP Toolkit version 2.0 Service Pack 2
- .NET Framework Software Development Kit (SDK)
- SOAP::Lite versions 0.51 or later installed
This article assumes that you are familiar with the following topics:
- How to set up a Perl distribution from the Comprehensive Perl Archive Network (CPAN). If the XML Web Service that you access uses complex types, you should be familiar with how Perl handles hashes.
- How to read and understand Web Service Description Language (WSDL) files.
Edit the WSDL File
Incompatibilities exist between the SOAP::Lite WSDL reader and the WSDL generator that is provided by .NET. Specifically, the SOAP::Lite WSDL reader expects all XSD type information to be in a namespace called XSD. These incompatibilities are to be resolved in future releases of SOAP::Lite.
To edit a .NET-generated WSDL file so that it is useable by SOAP::Lite, follow these steps:
NOTE: If the WSDL was generated by the SOAP Toolkit version 2.0, this procedure is unnecessary.
- Obtain the WSDL file for the intended service and save it locally. With Active Server Pages (ASP) .NET, for example, you can do so by invoking the .asmx file with the "?WSDL" query string (that is, http://server/scripts/sample.asmx?WSDL). Alternatively, you can use the Disco.exe utility.
- Open the local copy of the WSDL file and edit the reference for the XML Namespace for xmlns:s in the definitions element. It originally resembles the following:
xmlns:s="http://www.w3.org/2001/XMLSchema"
You should edit it as follows:
xmlns:xsd=http://www.w3.org/2001/XMLSchema
- Change all instances of elements that are prefixed with s: to be prefixed with xsd:. This reflects the change that you made in step 2.
- Remove all elements that involve the HTTP GET and HTTP POST messages, portTypes, bindings, and service ports.
Call the Endpoint
After you have the WSDL properly formatted for SOAP::Lite, you can call the endpoint fairly simply. If the file is stored locally (as it is for a .NET endpoint), you must make sure that you are using the file:// style Uniform Resource Identifier (URI) to load the WSDL. To call a simple service that adds two numbers and prints the results, use code that resembles the following:
use SOAP::Lite;
$a = 45;
$b = 55;
print "Adding values ", $a, " and ", $b, "\n";
print SOAP::Lite
-> service('file://c:/voices/perl/service1.wsdl')
-> Add($a, $b);
Troubleshooting
Getting the WSDL set up correctly can take a little while. You may receive error messages from the SOAP::Lite module that do not seem to be related to how the WSDL is set up and parsed. It is also fairly easy to miss an element that needs to be eliminated or replaced. If this is a major concern, you can choose to not use the WSDL capabilities and make your SOAP calls more direct. When you do this, make sure to have the WSDL file and the SOAP::Lite User's Guide available for reference so that you can make sure that the correct values are passed back and forth and that they are all named correctly.
To make sure that you completely understand the WSDL setup, you can use the Mssoapt.exe tool that ships with the Microsoft SOAP Toolkit version 2.0.
SOAP::Lite and the .NET XML Web Service implementations are part of a larger community driving interoperability between SOAP implementations. For more information on the current state of the interoperability testing, see the following Web site:
For more information on how to handle SOAP faults and complex types, see the user's guide on the following Web site:
For more information, see the following Web site: