• Article

SOAP Request Message Structure

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.

If you want your SOAP client to build its own SOAP requests instead of using the proxy classes provided by Visual Studio 2005, you must use the following message formats.

SOAP Request Message Format for Stored Procedures and User-Defined Types

The following sample shows a typical SOAP request sent to an instance of SQL Server. In the SOAP message the GetCustomerInfo operation is requested. Note that only a fragment of the HTTP header is shown.

POST /url HTTP/1.1
Host: HostServerName
Content-type: text/xml; charset=utf-8
Content-length: 350
SoapAction: http://tempUri.org/GetCustomerInfo
...

<?xml version="1.0" encoding="utf-8" ?> 
<soap:Envelope 
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
   <GetCustomerInfo xmlns="http://tempUri.org/">
<CustomerID>1</CustomerID> 
<OutputParam /> 
  </GetCustomerInfo>
</soap:Body>
</soap:Envelope>

HTTP Header

In the previous code, the value of the SoapAction HTTP header field is the method name preceded by its namespace. This value is the same method and namespace that you added to the endpoint created by using CREATE ENDPOINT. Note that this is an optional field. The Host HTTP header field identifies the server to which the HTTP request is sent.

<soap:Envelope> Element

The details of a SOAP request are included in the <Body> element in the SOAP envelope. The previous example requests the GetCustomerInfo method. The xmlns attribute in <GetCustomerInfo> is the same namespace that is specified for this method you created the endpoint by using CREATE ENDPOINT. For more information about the stored procedure and namespace, see Sample Applications for Sending Native XML Web Services Requests. The following method parameters are passed in as child elements of the <GetCustomerInfo> element:

  • The <CustomerID> element that has value 1 is the input parameter

  • The <OutputParam> element is the output parameter.

Input Parameter Handling

Input parameters are handled in the following ways:

  • If a SOAP method requires an input parameter, and this parameter is not included in the SOAP request, no value is passed to the called stored procedure. The default action defined in the stored procedure occurs.

  • If a SOAP method requires an input parameter, and this parameter is included in the request but no value is assigned to it, the parameter is passed to the stored procedure with an empty string as its value. Note that it is not NULL.

  • If a SOAP operation requires an input parameter and if you want to send a NULL value for this parameter, you must set an xsi:nil attribute to "true" in the SOAP request. For example:

    <GetCustomerInfo xmlns="http://tempUri.org/" >
  <CustomerID xsi:nil="true" />
  <OutputParam />
</GetCustomerInfo>

    In Visual Studio 2005, when you pass NULL values to string variables, this generates the xsi:nil="true" attribute in the SOAP request. But when you pass NULL values for parameters of types such as integer and float (value types), Visual Studio 2005 does not generate the xsi:nil="true" attribute; instead, it provides default values for these parameters; for example, 0 for integer types, 0.0 for float types, an so on. Therefore, if you want to pass NULL values to these types of parameters, you must build the SOAP message in your application by using the xsi:nil="true" attribute. For more information, see Guidelines and Limitations in Native XML Web Services

  • You can provide several facets on the parameters. A table shown later in this topic lists several facets that you can specify when you request ad hoc SQL queries. In this table, all the facets that you can specify for a <Value> node can be specified on the RPC method parameter nodes.

SOAP Request Message Format When Requesting Ad Hoc SQL Queries

When you send a SOAP request for ad hoc SQL query executions, you must call the sqlbatch method and pass the queries and whatever parameters may be required.

The following sample HTTP SOAP request calls the sqlbatch method. Note that only a fragment of the HTTP header is shown.

POST /url HTTP/1.1
Host: HostServerName
Content-type: text/xml; charset=utf-8
Content-length: 656
SoapAction: https://schemas.microsoft.com/sqlserver/2004/SOAPsqlbatch
...

<?xml version="1.0" encoding="utf-8" ?> 
 <soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
 <sqlbatch xmlns="https://schemas.microsoft.com/sqlserver/2004/SOAP">
<BatchCommands>
SELECT EmployeeID, FirstName, LastName 
FROM Employee 
WHERE EmployeeID=@x 
FOR XML AUTO;
</BatchCommands> 
<Parameters>
   <SqlParameter Name="x" SqlDbType="Int" MaxLength="20" 
   xmlns="https://schemas.microsoft.com/SQLServer/
    2001/12/SOAP/types/SqlParameter">
  <Value xsi:type="xsd:string">1</Value> 
   </SqlParameter>
</Parameters>
  </sqlbatch>
  </soap:Body>
  </soap:Envelope>

HTTP Header

In the HTTP header, note that the SoapAction HTTP header field value is the method name (sqlbatch) that the client uses to specify SQL queries. Note that this header is optional.

<soap:Envelope> Element

The SOAP request details appear in the <Body> element. The SOAP <Body> element has only one child element (<sqlbatch>), and it identifies the method requested. The namespace identified in the element is where the sqlbatch operation is defined. This element has following child elements:

  • The <BatchCommands> element specifies the query, or queries separated by semicolons (;), to execute.

  • The <Parameters> element provides an optional list of parameters. In the previous example request envelope, there is only one parameter passed to the query. Each parameter added to the SOAP message as a <SqlParameter> child element of the<Parameters> element. In passing the parameters, you must pass at least, the parameter name (Name attribute of <SqlParameter> element) and the parameter value (<Value> child element of <SqlParameter> element).

To avoid unexpected conversions, provide as much parameter information that you can. The following table lists additional parameter facets that you can specify for the <SqlParameter> element. You can also specify some of these facets for the <Value> element.

For facets that can be specified on both the <SqlParameter> and the <Value> element, when you specify the <Value> element, the facets must be in the https://schemas.microsoft.com/sqlserver/2004/sqltypes namespace as shown in the following example:

<Value xsi:type="xsd:string" sqltypes:maxLength="100" xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">1</Value>

Parameter facet

Comment

Can be specified on node

direction

Specifies the parameter direction (Input, InputOutput). Input is the default.

<SqlParameter>

localeID

Defines the windows locale for the collation of character types. Equivalent to LCID value returned by COLLATIONPROPERTY intrinsic.

<SqlParameter>

<Value>

maxLength

Attribute of <SqlParameter> element provides the maximum length of the parameter value. Default value is 1.

<SqlParameter>

<Value>

name

Attribute of <SqlParameter> element provides the parameter name.

<SqlParameter>

outputRequested

Can be applied to the parameter elements to indicate whether it should emit output. Default behavior depends on the parameterMode used, whether it is explicit or default.

If the attribute is set to "true" on an input parameter, it will generate an error.

<Value>

precision

This attribute of the <SqlParameter> element provides the precision of the parameter value. Default value is 18.

<SqlParameter>

<Value>

scale

This attribute of the <SqlParameter> element provides the scale of the parameter value. Default is 0.

<SqlParameter>

<Value>

sqlCompareOptions

Defines the comparison options to be used for the collation of character types. It is an enum of values that can be combined that matches with the ComparisonStyle value returned by the COLLATIONPROPERTY intrinsic.

<SqlParameter><Value>

sqlDbType

Specifies the parameter type. For a list of SQL Server system data types you can specify, see Data Type Mappings in Native XML Web Services.

<SqlParameter>

clrTypeName

Used to specify CLR user-defined type arguments. clrTypeName can contain the three-part name.

<SqlParameter>

<Value>

useDefaultValue

Indicates that a default value should be used for a parameter. The parameter element can either be omitted from the list or, alternatively, the Boolean attribute useDefaultValue with a value of "true" can be specified. The default value of this attribute is "false" if the element is included and "true" if the element is omitted.

<SqlParameter>

<Value>

XmlNamespace

Specifies the XML schema namespace associated with the xml type parameter.

<SqlParameter>

<Value>

xsi:type

Specifies the value type. For more information about how the xsi:type facet maps to SQL Server system data types, see Data Type Mappings in Native XML Web Services.

<Value>

typename

Used to specify user-defined type arguments. typename can contain the three-part name.

<SqlParameter>

<Value>