مشاركة عبر

  • مقالة

Using WSDL

This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

The Web Service Description Language (WSDL) defines the Web interface definition for any RPC functions exposed on the HTTP endpoint and also describe the SQL batch functionality for the endpoint. A client can request a WSDL response from an instance of SQL Server and use it to generate RPC and SQL batch requests against the server by using the HTTP endpoints that have been configured to support a WSDL type. The WSDL response is actually a dynamically generated XML document based on the RPC functions associated with endpoint at the time of the request.

Note

For background information about WSDL, see the WSDL 1.1 specification available at the World Wide Web Consortium (W3C) Web site at http://www.w3c.org.

HTTP endpoints that are configured to support a WSDL offering can specify one of the following WSDL configurations for use in answering clients that submit WSDL requests:

  • A default WSDL

  • A customized WSDL

When configured to provide the default WSDL option, SQL Server offers support for two WSDL types: a default, or extended WSDL, and a simplified WSDL format.

Although any one of these WSDL documents describe the methods that are supported on the endpoint, the default WSDL uses additional features of an XML Schema (XSD) to provide a richer description of the methods, data types, parameters, and return values that are available or exposed by the endpoint.

The simplified WSDL format, which might be required for down-level compatibility with older clients, uses a very basic XSD schema that requires only primitive data types. If neither the default nor the simplified WSDL provides the exact WSDL contents appropriate for a particular client, you can update the server to provide a customized version of the WSDL as required.

WSDL responses are generated and returned by an instance of SQL Server upon initial connection to an HTTP endpoint by a Web services client that submits a WSDL request.

How WSDL is Supported by SQL Server

When an endpoint is defined, the WSDL argument in the CREATE ENDPOINT Transact-SQL statement is used to specify for the server whether a WSDL response is generated and returned for the endpoint to describe its Web programmable features. If the endpoint was established by using a WSDL=NONE value, the server will not return a WSDL response.

If default WSDL generation was specified, such as if WSDL=DEFAULT was specified when the endpoint was created, the format of the WSDL returned by the server will vary depending upon the URL string used by the client to connect to the HTTP endpoint. Clients can use one of the following URL formats to request the WSDL:

  • Default WSDL

    This is full version of the extended WSDL response that is returned when you use the http://server/endpoint_path?wsdl URL to connect to the endpoint. This format uses XSD derived types to provide mapping support for more complex SQL types. For more information, see Default WSDL.

  • Simple WSDL

    This is a short simplified version of the default WSDL that maps all SQL Server system data types to native XSD types. This format is returned when you use http://server/endpoint_path?wsdlsimple as the URL to connect to the endpoint. For more information, see Simple WSDL.

  • Custom WSDL

    When either version of the WSDL that the instance of SQL Server returns, either the default or simplified one, is not acceptable for clients, you can specify a custom WSDL offering. This option requires that you design and implement additional code. In this way, a stored procedure can be used to generate and return the customized WSDL contents as a result to the clients that specify the custom WSDL type in an HTTP-based query. For more information, see Implementing Custom WSDL Support.

Contents of the WSDL

A Web Services Description Language (WSDL) instance is an XML document that has a root <definitions> element that specifies the WSDL namespace (https://schemas.xmlsoap.org/wsdl) and defines a set of Web services as a collection of network endpoints, or ports. A typical WSDL document will have the following top-level structure:

<wsdl:definitions>
  <wsdl:types>...</wsdl:types>
  <wsdl:message>...<wsdl:message/>
  <wsdl:portType>...</wsdl:portType>
  <wsdl:binding>...</wsdl:binding>
  <wsdl:service>...<wsdl:service>
<wsdl:definitions>

As this simplified view of the WSDL format shows, several elements are used to indicate the main sections within the WSDL document. The role of each of these is described briefly in the following table.

Element

Description

wsdl:types

Container element for data type definitions that are made using XML Schema (XSD) or another similar system for data types.

wsdl:message

Definition of the message data being communicated. The message can be made up of multiple parts and each part can be of a different type,

wsdl:portType

Abstract set of operations supported by one or more endpoints.

wsdl:binding

Concrete protocol and data format specification for a particular port type.

wsdl:service

Collection of related endpoints.

System Stored Procedures Used to Support WSDL

The following system stored procedures are included with Native XML Web Services in SQL Server to support default and simple WSDL implementations and are invoked in response to a request for WSDL:

  • sp_http_generate_wsdl_defaultcomplexorsimple

  • sp_http_generate_wsdl_defaultsimpleorcomplex

  • sp_http_generate_wsdl_complex

  • sp_http_generate_wsdl_simple

To execute these stored procedures, requires membership in the public role. Internally, each of these stored procedures queries the catalogs to obtain information about additional stored procedures exposed through the endpoints as Web methods. Users only require permissions on these Web method stored procedures. For more information, see Exposing SQL Programmability to the Web.