Import WSDL Wizard

From RAD Studio
Jump to: navigation, search

Go Up to Component Menu

Component > Import WSDL
File > New > Other > Delphi Projects or C++Builder Projects > WebServices > WSDL Importer

Note: The WSDL importer invoked from File > New > Other requires that you create an application before you can activate the command, but the WSDL importer invoked from the Component menu allows you to run the wizard before you create an application.

Use this wizard to import a WSDL document or XML schema that describes a Web Service. Once you have imported the WSDL document or XML schema, the wizard generates all the interface and class definitions you need for calling on those Web Services using a remote interfaced object (THTTPRIO). You can also tell the wizard to generate skeletal code that you can complete to create a Web Service application (for example, if you want to implement a Web Service that is already defined in a WSDL document).

Language page

If you do not have a project opened when you invoke the wizard, an initial Language page is displayed. On this page, you specify whether the generated bindings are for:

  • Delphi
  • C/C++

WSDL Location page

Allows specifying the URL of the WSDL document to import (or select an already stored one) and indicating the credentials (username, password, and a proxy) used to access the document.

Item Description

Location of WSDL File or URL

Enter either a WSDL file name or the URL where the document is published. Click the ellipsis button next to the edit box to browse for a file location. After entering a file name, you can click the Next button to move to the SOAP Version page.

User Name

Specify the username to use if the WSDL document is on a secure server that requires authentication.

Password

Specify the password to use with User Name when the WSDL document is on a secure server that requires authentication.

Proxy

Specify the host names for any proxy servers that must forward requests to the URL specified on the Source page of the Web Services Import dialog.

SOAP Version page

Allows you to either specify the SOAP version (1.1 or 1.2) that is used by the WSDL document or allow the product to choose the latest version available. Note that a service can support both 1.1 and 1.2. To avoid a mismatched version (which can cause the generation of incorrect source code), you should typically select the Automatic SOAP versioning option.

Select one of the following options:

Item Description

Automatic SOAP versioning

Allows you to select the SOAP Services described in the WSDL you want to import based on the SOAP version they support. When both versions 1.1 and 1.2 are allowed and available, the product favors SOAP 1.2. See the example that follows this table.

Process only WSDL Binding extensions for the SOAP 1.1 Protocol

The process communicates with the Service using only the SOAP 1.1 protocol.

Process only WSDL Binding extensions for the SOAP 1.2 Protocol

The process communicates with the Service using only the SOAP 1.2 protocol.

For example, suppose the WSDL describes the SOAP version supported by each of the defined services:

  • CreditCardIssueService SOAP 1.1
  • CreditCardVerifyService SOAP 1.1, 1.2
  • CreditCardRevokeService SOAP 1.2

If you select Automatic SOAP Versioning on the SOAP version page, the following services are imported:

  • CreditCardIssueService SOAP 1.1
  • CreditCardVerifyService SOAP 1.2
  • CreditCardRevokeService SOAP 1.2

That is, the SOAP 1.1 version of the CreditCardVerifyService is not imported.

If you select Process only WSDL Binding extensions for the SOAP 1.1 Protocol, then the following services are imported:

  • CreditCardIssueService SOAP 1.1
  • CreditCardVerifyService SOAP 1.1

That is, the CreditCardRevokeService is omitted because it only supports SOAP 1.2

If you select Process only WSDL Binding extensions for the SOAP 1.2 Protocol, the following services are imported:

  • CreditCardVerifyService SOAP 1.2
  • CreditCardRevokeService SOAP 1.2

That is, the CreditCardIssueService is omitted because it only supports 1.1.


Click Next to proceed to the WSDL Import Options page.

WSDL Import Options page

Use this wizard page to configure the way the wizard generates code to represent definitions in a WSDL document. Select any of the options described below. You should typically use the default options, because the defaults provide the safest way to import WSDL documents.

Item Description

Generate verbose information about types and interfaces

If this options is enabled, the WSDL importer generates information regarding type namespaces, service styles, binding names, and various other WSDL exposed data.

One out parameter is return value

When checked, the importer maps operations with a single output message into functions where the output message is the return value. If this is not checked, the output message is mapped to an output parameter.

Generate server implementation instead of client implementation

When checked, the importer generates implementation classes for the imported interfaces. Use this option when writing a server that implements a Web Service that is already defined in a WSDL document.

Unwind Literal Params

In document literal encoding, the Web Service does not describe operations. It rather describes two records, one that presents the expected input and one that presents the output. When Unwind Literal Params is checked, the importer converts these two records into method calls.

Emit Literal Types

In document literal encoding, the Web Service does not describe operations. Rather, it describes two records, one that presents the expected input and one that presents the output. When Generate Literal Types is checked, the importer generates type definitions for these two records, even if it converts them to method calls (that is, even if Unwind Literal Params is checked).

Map String to WideString

When checked, the importer maps all string types to WideString values. When unchecked, the importer uses the string type instead. WideString values may be required to handle values that use extended characters. If string values do not use extended characters, it is more efficient to use the string type.

Generate destructors for remotable types

When checked, the importer generates destructors on the classes that represent types. These destructors free any nested members whose types are classes or arrays of classes. The generated destructors simplify the work you must do when freeing instances of classes that represent types, because you do not need to explicitly free class members that also use classes to represent the remotable type.

Generate warning comments

When checked, the importer adds warning messages to the comments it puts at the top of generated files. These warnings describe problems such as invalid type definitions in the WSDL document when Ignore Schema Errors is checked, problems encountered when unwinding literal parameters when Unwind Literal Params is checked, and so on.

Map pure collections to wrapper class types

Check this option to enable the WSDL importer to map the imported array types to wrapper classes. This option is mainly provided for C++Builder, where array types cannot be directly mapped to WSDL array types, thus requiring a wrapper collection class.

Do not emit unused types

If this option is checked, the WSDL importer does not generate code for types declared in the WSDL document, but not used in any exposed Service. Note that classes may not follow this rule, because a Service may return an instance of a derived class, where the base class is expected. In this case, code for both the base class and the derived class is generated.

Validate Enumeration members

Check this option to ensure that the WSDL importer uses a global symbol list when generating enumeration members. This option prevents name clashes between enumeration members of enumerated types declared in the WSDL document. Since Delphi 2009, we recommend you never uncheck this option.

Import Fault Types

Check this option to make the WSDL importer process types marked as fault.

Import Header Types

Check to enable the WSDL importer to process types marked as headers.

Generate interface GUIDs using COM API

Check to enable the WSDL importer to assign unique GUIDs each time a Service is imported. If this option is disabled, the GUID generated to each Service remains the same every time the WSDL importer generates code for that Service. In most cases, we recommend that this option be disabled.

Process included and imported schemas

Check this option to make the WSDL importer process included and imported schemas.

Generate class aliases as class types

Check this option to make the WSDL importer generate class types instead of weak aliases. This option makes sure that generated alias classes have distinct RTTI (Run-Time Type Information) from the base type.

Allow out parameters

This option controls whether the WSDL importer generates methods that use out parameters when returning multiple parts of a SOAP message. If this option is disabled, out parameters are not generated; the WSDL importer generates wrapper classes for multi-part SOAP messages.

Use Setters and Getters for properties

By default, the WSDL importer generates properties that map directly to the fields in the generated classes. By enabling this option, you can force the WSDL importer to generate setter and getter methods instead.

Process nillable and optional elements

Check this option to make the WSDL importer generate relevant information about optional and nillable properties. This information is used by the SOAP runtime to allow certain properties be nil.

Use TXSString for simple nillable types

The WSDL standard allows simple types to be nil, in Delphi or NULL, in C++, while Delphi and C++ do not allow that. Check this option to make the WSDL importer overcome this limitation by using instances of wrapper classes.

Generate scoped enumerations

When checked, scoped enumerations will be generated. Check this option if the WSDL document contains different enumerations that define values with the same name.

Click Finish on the WSDL Import Options page to proceed to source code generation.

Error Messages

The following error messages can be generated by the Import WSDL wizard.

  • Unable to load WSDL File/Location: <wrongURL>. Error [Empty document].
  • This error message typically indicates an invalid URL. That is, a URL that does not return any content.
  • Unable to load WSDL File/Location: <url>. Error [Whitespace is not allowed at this location]
  • This error indicates a URL that returned HTML or text content (i.e. a URL that did not return XML content)
  • Unable to load WSDL File/Location: <url>. Error [End tag 'ul' does not match the start of tag 'p']
  • This error also indicates a URL that returned HTML content. This message is common if you forgot the '?wsdl' query string commonly used by some WebServices. For example, if you use http://<domain>.com/service.asmx instead of http://<domain>.com/service.asmx?wsdl for a .NET WebService.
  • This error indicates that the URL returned XML content but that latter did not contain the root <definition> element expected for a WSDL file. This will happen if you import the schema used by a WSDL instead of the WSDL document itself, for example.

Troubleshooting

A simple way to troubleshoot your URL is to view the WSDL URL in your browser. If you see an HTML page, that is a bad URL. You should see XML in a WSDL document.

See Also