Share via

  • Article

Initiating a SOAP Session

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.

To initiate a session, a client request must include the sqlSession header, and specify the initiate attribute with a value of true. If a session is successfully established, the response from the server contains the session header that specifies a server generated value for the sessionID property.

The security credentials of the session initiator are associated with the session, and all subsequent requests within the session must be executed under the same credentials.

If the HTTP endpoint that services the SOAP session has specified a DATABASE clause, this setting only takes effect for the request that is initiating the session. Subsequent requests execute under the current database of the session.

Note

SOAP sessions are connection-independent and can out last SQL Server connections. SOAP sessions do not count against the maximum connections count for the server.

Example

The following example shows how to initiate a SOAP session. When a SOAP session is initiated, the following messages are used:

  • The SOAP request sent by the Web services client to request a session

  • The SOAP response returned by the server to confirm the request

The following is an example of the SOAP request that would be sent by the client.

<SOAP-ENV:Header
  xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sqloptions="https://schemas.microsoft.com/sqlserver/2004/SOAP/Options">
    <!-- create a new session, with explicit timeout -->
    <sqloptions:sqlSession initiate="true" timeout="12"/>
</SOAP-ENV:Header>

Note that the option name is case sensitive; therefore, the exact string must include the uppercase S, as sqlSession is encoded previously.

To initiate the session, the server would then return the following request.

<SOAP-ENV:Header
  xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sqloptions="https://schemas.microsoft.com/sqlserver/2004/SOAP/Options">
    <!-- response to creating a new session, or enlisting in an existing session -->
    <sqloptions:sqlSession sessionId="AAAAADreaLE=" timeout="12"/>
</SOAP-ENV:Header>

In this example, as long as the time-out value requested is less than or equal to the maximum session time-out set at the server on the HTTP endpoint, the server will honor the time-out interval requested by the client and echo the same value ("12") in the response. If the time-out interval specified by the client in the request is larger than the maximum time-out for the server, the server maximum time-out is specified in the response to the client.