• Article

Ending 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 end a session, a request must specify the sqlSession header with both the sessionId and terminate attributes set. The sessionId must identify a known session that the server that is in an accessible state at the server and the terminate attribute must be set to a value of true.

If there is no session existing with the specified ID, a SOAP fault is returned with the terminate attribute in the sqlSession header.

If the request is executed under a different security context or endpoint than that which initiated the session, a SOAP fault is returned and the session remains unaltered.

When explicitly ended, no new requests are accepted under the session. The session is closed when the last batch within the session is completed. This is not necessarily the same batch in which session termination was actually requested.

Examples

The following example shows ending a SOAP session. To end a session, a SOAP client sends a request such as the following with the known and valid sessionId attribute value set and the terminate attribute specified with a value of true:

<SOAP-ENV:Header
  xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sqloptions="https://schemas.microsoft.com/sqlserver/2004/SOAP/Options">
    <!-- enlist in an existing session, and terminate it -->
    <sqloptions:sqlSession terminate="true" sessionId="AAAAADreaLE="/>
</SOAP-ENV:Header>

Requests to end a session can be empty or have a message body. If a body is present, the terminate header is processed and acknowledged, regardless of the errors occurring on the execution of the method.

The server will then return a confirmation, such as the following, to indicate the session has ended.

<SOAP-ENV:Header
  xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sqloptions="https://schemas.microsoft.com/sqlserver/2004/SOAP/Options">
    <!-- response to terminating an existing session -->
    <sqloptions:sqlSession terminate="true" sessionId="AAAAADreaLE="/>
</SOAP-ENV:Header>

To make sure termination is completed, clients will typically have to scan for the confirmation response from the server. If the confirmation is not received at the client within a reasonable period of time, the client should retry the termination request.