Artigo
09/28/2010

Estrutura de mensagens de resposta SOAP

Esse recurso será removido em uma versão futura do Microsoft SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.

Este tópico descreverá a estrutura de mensagens de resposta de SOAP se você desejar analisar a resposta de SOAP, em vez de usar as classes de proxy fornecidas por Visual Studio 2005.

Uma mensagem de resposta de SOAP que é retornada por uma instância do SQL Server pode incluir um ou mais dos seguintes itens:

Resultados definidos para consultas SELECT.
Código de retorno para procedimentos armazenados e funções definidas pelo usuário.
Contagem de linhas. Este é o número de linhas afetadas pela consulta.
Valores de parâmetro de saída.
Mensagens de erro ou avisos.

O seguinte é um fragmento da estrutura de resposta de SOAP que é retornada pelo SQL Server depois que um procedimento armazenado é executado:

<?xml version="1.0" encoding="utf-8" ?> 
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  ...>
  <SOAP-ENV:Body>
  <method:MethodNameResponse>
  <method:MethodNameResult  
 xsi:type="sqlresultstream:SqlResultStream">
<!-- 
  the results are returned here
-->
  </method:MethodNameResult>
  <method:OutputParam>Value</method:OutputParam> 
  </method:MethodNameResponse>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

Os resultados de uma operação são encapsulados no elemento <MethodNameResponse> no corpo de SOAP. O elemento <MethodNameResponse> pode incluir os seguintes elementos filho:

<MethodNameResult> inclui os resultados, os valores de contagem de linha e mensagens de erro e avisos.
<OutputParameter> inclui parâmetros de saída, se houver algum, retornados por procedimentos armazenados.

Elemento <MethodNameResult>

Os resultados de uma operação são retornados dentro do elemento <MethodNameResult>, em que MethodName é o nome de um procedimento armazenado ou uma função definida pelo usuário ou é sqlbatch para consultas de lote ad hoc. sqlbatch é o método usado para executar consultas ad hoc.

Dentro do elemento <MethodNameResultado>, os resultados são serializados da seguinte forma:

O resultado de uma instrução SELECT é encapsulado em um elemento <SqlRowSet>. Os resultados serializados no elemento < SqlRowSet> usam o formato de serialização DiffGram. O formato DiffGram é introduzido no componente DataSet do Microsoft.NET Framework. Neste caso, a resposta também inclui um esquema XSD (se o ponto de extremidade for criado com esquema habilitado) antes dos dados. No cliente Visual Studio 2005, os resultados são retornados como objetos System.Data.DataSet.

Observação
Para carregar resultados de SOAP em objetos System.Data.DataSet quando você estiver usando Visual Studio 2005, o SQL Server deverá incluir esquemas embutidos nas respostas de SOAP que ele retorna aos clientes. Este comportamento é habilitado para pontos de extremidade omitindo a palavra-chave SCHEMA ou especificando SCHEMA=STANDARD quando você cria o ponto de extremidade. Para obter mais informações, consulte CREATE ENDPOINT (Transact-SQL).

Para carregar resultados de SOAP em objetos System.Data.DataSet quando você estiver usando Visual Studio 2005, o SQL Server deverá incluir esquemas embutidos nas respostas de SOAP que ele retorna aos clientes. Este comportamento é habilitado para pontos de extremidade omitindo a palavra-chave SCHEMA ou especificando SCHEMA=STANDARD quando você cria o ponto de extremidade. Para obter mais informações, consulte CREATE ENDPOINT (Transact-SQL).

O resultado de uma instrução SELECT... FOR XML instrução é encapsulado em um elemento <SqlXml>. Se vários conjuntos de resultados forem retornados (por exemplo, um procedimento armazenado com várias consultas SELECT...FOR XML), cada conjunto de resultados será encapsulado em seu próprio elemento <SqlXml>. Além disso, cada resultado é seguido por um elemento <SqlRowCount>. Esse elemento retorna o número de linhas afetadas pela consulta, como mostrado no seguinte fragmento de resposta:

<tns:MethodNameResponse>
  <tns:MethodNameResult 
xsi:type="sqlsoaptypes:SqlResultStream">
     <sqlresultstream:SqlXml xsi:type="sqlsoaptypes:SqlXml" >
 <SqlXml>
    <!-- XML result --> 
 </SqlXml>
</sqlresultstream:SqlXml>
<sqlresultstream:SqlRowCount xsi:type="sqlrowcount:SqlRowCount">
   <sqlrowcount:Count>NoOfRowsAffected</sqlrowcount:Count> 
</sqlresultstream:SqlRowCount>
<sqlresultstream:SqlXml xsi:type="sqlsoaptypes:SqlXml" >
  <SqlXml>
    <!-- XML Document that maps to XMLElement object 
   in the client--> 
  </SqlXml>
</sqlresultstream:SqlXml>
<sqlresultstream:SqlRowCount xsi:type="sqlrowcount:SqlRowCount">
   <sqlrowcount:Count>NoOfRowsAffected</sqlrowcount:Count> 
</sqlresultstream:SqlRowCount>

     <!-- more results ...-->
  </tns:MethodNameResult>
  <tns:OutputParam>Value</tns:OutputParam> 
</tns:MethodNameResponse>

Se a consulta SELECT... FOR XML solicitar um esquema XSD especificando a opção XMLSCHEMA, o esquema XSD será retornado como o primeiro elemento filho do elemento <SqlXml>.

No cliente Visual Studio 2005, os resultados são retornados como objetos System.Xml.XmlElement.

Os valores de código de retorno de procedimentos armazenados e funções definidas pelo usuário são encapsulados em um elemento <SqlResultCode>, como mostrado no seguinte fragmento de resposta:

<tns:MethodNameResponse>

  <tns:MethodNameResult 
xsi:type="sqlsoaptypes:SqlResultStream">
  <!-- 
    results 
  -->
     <sqlresultstream:SqlResultCode
xsi:type="sqlsoaptypes:SqlResultCode">
   ReturnCodeValue
     </sqlresultstream:SqlResultCode> 
  </tns:MethodNameResult>
  <tns:OutputParam>Value</tns:OutputParam> 
</tns:MethodNameResponse>

No cliente Visual Studio 2005, o código de retorno é retornado como um objeto.

As mensagens de erro, os avisos e outras mensagens informativas do SQL Server são encapsuladas em um elemento <SqlMessage>, como mostrado no seguinte fragmento de resposta de SOAP:

<tns:MethodNameResponse>
  <tns:MethodNameResult xsi:type="sqlresultstream:SqlResultStream">
     <sqlresultstream:SqlMessage>
    <!-- Error message returned as SqlMessage object 
 in the client --> 
</sqlresultstream:SqlMessage>
 ...
  </tns:MethodNameResult>
  <!-- followed by one or more return parameters ->
   ...
</tns:MethodNameResponse>

O fragmento de resposta de SOAP a seguir é retornado executando o procedimento armazenado GetCustomerInfo. Para obter informações sobre este procedimento armazenado, consulte Aplicativos de exemplo para enviar solicitações de XML Web Services Nativos. A primeira instrução INSERT no procedimento armazenado falha. Isto causa a resposta a seguir.

<method:GetCustomerInfoResponse>
 <method:GetCustomerInfoResult 
    xsi:type="sqlresultstream:SqlResultStream">
    <sqlresultstream:SqlMessage>
     <sqlresultstream:SqlMessage xsi:type="sqlmessage:SqlMessage">
<sqlmessage:Class>16</sqlmessage:Class> 
<sqlmessage:LineNumber>12</sqlmessage:LineNumber> 
<sqlmessage:Message>Cannot insert the value NULL into column 
'CompanyName', table 'Northwind.dbo.Customers'; 
column does not allow nulls. INSERT fails. 
</sqlmessage:Message> 
     <sqlmessage:Number>515</sqlmessage:Number> 
     <sqlmessage:Procedure>GetCustomerInfo</sqlmessage:Procedure> 
     <sqlmessage:Server>SQLServerName</sqlmessage:Server> 
     <sqlmessage:Source>MicrosofTransact-
SQL/9.0</sqlmessage:Source> 
     <sqlmessage:State>2</sqlmessage:State> 
    </sqlresultstream:SqlMessage>
    <sqlresultstream:SqlRowCount xsi:type="sqlrowcount:SqlRowCount">
 <sqlrowcount:Count>0</sqlrowcount:Count> 
    </sqlresultstream:SqlRowCount> 
    <sqlresultstream:SqlResultCode 
  xsi:type="sqlsoaptypes:SqlResultCode">-6 
    </sqlresultstream:SqlResultCode> 
  </method:GetCustomerInfoResult>
  <!-- followed by one or more output parameters ->
 </method:GetCustomerInfoResponse>
</tns:MethodNameResponse>

No cliente do Visual Studio 2005, estes resultados são retornados como um objeto de tipo SqlMessage.

Elemento <OutputParameter>

Cada valor de parâmetro de saída é retornado encapsulado em um elemento. O nome de elemento é o nome do parâmetro de saída. Observe que esse elemento aparece depois do elemento <MethodNameResult> como o último filho do elemento <MethodNameResponse>; isto é mostrado no seguinte fragmento de resposta de SOAP. São retornados dois parâmetros de saída.

<tns:MethodNameResponse>
   <tns:MethodNameResult xsi:type="sqlresultstream:SqlResultStream">
     <!-- results, error messages and warnings -->
   </tns:MethodNameResult>
   <tns:OutputParam1>Value</tns:OutputParam1> 
   <tns:OutputParam2>Value</tns:OutputParam2> 
</tns:MethodNameResponse>