Compartir a través de

Personalizar mensajes SOAP

  • Artículo

Para los servicios Web XML creados mediante ASP.NET y sus clientes que utilicen SOAP con el fin de comunicarse con los métodos de servicio Web XML, hay disponible un sofisticado mecanismo para controlar el formato del mensaje SOAP enviado al servidor que espera recibirlo. En SOAP se establece que el contenido del mensaje SOAP enviado y recibido por un servicio Web XML debe estar en formato XML. Sin embargo, no se describe estrictamente el formato XML. Como mecanismo para trabajar con servicios Web XML que esperan recibir un formato diferente, ASP.NET proporciona uno basado en atributos para controlar el formato del contenido XML del mensaje SOAP. Además, para controlar el mensaje SOAP con más detalle, hay disponible un mecanismo basado en atributos para especificar el elemento y los nombres de atributos específicos del mensaje SOAP enviado a través de la red.

La comunicación entre los servicios Web XML y sus clientes viene impuesta en gran medida por dos estándares: SOAP y Lenguaje de descripción de servicios Web (WSDL). SOAP define un esquema de formato para los datos que aparecen a continuación del elemento Body y uno para los parámetros del elemento Body. El primero se conoce como la sección 7 de SOAP o, simplemente, RPC. Para obtener más información acerca de la especificación de SOAP, visite el sitio Web de W3C (World Wide Web Consortium), en http://www.w3.org/TR/SOAP. El segundo se conoce como la sección 5 de SOAP o, simplemente, Encoded. WSDL, que se utiliza para describir los mensajes SOAP que un servicio Web XML espera recibir, permite que los servicios Web XML indiquen que aceptan mensajes RPC con parámetros codificados, pero define también otros dos términos: "literal" y "document". Los términos "literal" y "encoded" hacen referencia al formato de los parámetros. El término "document", al igual que el término "RPC", hace referencia al formato del elemento Body en general.

Personalizar el mensaje SOAP enviado por un cliente de servicios Web XML

En la tabla siguiente se describen los estilos de formato que admiten los servicios Web XML creados mediante ASP.NET y los atributos con los que se consigue cada combinación específica. Los atributos con un sufijo Service se pueden aplicar a una clase que implemente un servicio Web XML para establecer el estilo de formato predeterminado para los métodos de servicio Web XML de la clase. Los atributos con un sufijo Method sólo se pueden aplicar a un método de servicio Web XML o a un método de una clase de proxy que llame a un método de servicio Web XML. Los detalles de cada combinación se especifican en los párrafos siguientes.

    Formato general del elemento Body en SOAP
Formato de parámetros Mensajes SOAP basados en Document Mensajes SOAP basados en RPC según la sección 7 de SOAP
Literal: basado en un esquema XSD para cada parámetro SoapDocumentMethod o SoapDocumentService

Use=Literal

Éste es el valor predeterminado.

 No se admite.
Encoded: reglas de codificación de la sección 5 de SOAP SoapDocumentMethod o SoapDocumentService

Use=Encoded

SoapRpcMethod o SoapRpcService

Modificar el formato de los parámetros

Una de las primeras decisiones que se deben tomar al diseñar un servicio Web XML es la forma de codificación XML en la solicitud SOAP. En particular, se debe decidir si se desea que el documento XML siga estrictamente un esquema XSD o siga las reglas de formato que se describen en las secciones 5 y 7 de la especificación de SOAP. Las reglas de formato de dichas secciones permiten variaciones. Por ello, un destinatario de una solicitud SOAP que utilice las reglas de codificación de SOAP debe controlar todas las variaciones posibles. Si se define un esquema XSD para el método de servicio Web XML, se puede definir de forma concreta el contenido exacto que es necesario enviar en una solicitud SOAP. De forma predeterminada, los servicios Web XML creados mediante ASP.NET utilizan el paso de documentos basado en esquemas.

Dado que los parámetros de un método de servicio Web XML pueden constituir la mayor parte de los datos pasados en una solicitud o respuesta SOAP, la forma en que los parámetros se asignan a elementos XML determina la apariencia que tendrá el documento XML. El Lenguaje de descripción de servicios Web (WSDL) define dos estilos de formato para los parámetros: Encoded y Literal. Encoded hace referencia al formato de los parámetros mediante la codificación SOAP descrita en la sección 5 de la especificación SOAP. Literal hace referencia a la asignación de parámetros a elementos XML mediante un esquema XSD predefinido para cada parámetro.

Con un cliente de servicios Web XML, puede elegir cómo se asignan los parámetros a elementos XML en correspondencia con lo que el servicio Web XML espera recibir. Los servicios Web XML admiten los dos estilos de formato de parámetros, Literal y Encoded. Esta compatibilidad varía en función del formato elegido para los métodos de servicio Web XML. Para obtener más información, vea Modificar el formato general de BODY en SOAP.

Observe que aunque ASP.NET proporciona una arquitectura extensiva para controlar el formato XML, el orden de serialización de los parámetros no está garantizado.

Para especificar el formato de parámetros Literal

  • Aplique un atributo SoapDocumentMethod a un método de la clase de proxy, con el valor de la propiedad Use establecido a SoapBindingUse.Literal.

    En la enumeración SoapBindingUse se especifican los estilos de formato de parámetros que están disponibles para un servicio Web XML creado mediante ASP.NET.

    [SoapDocumentMethod(
    "https://www.contoso.com/DocumentLiteral",
    RequestNamespace="https://www.contoso.com",
    ResponseNamespace="https://www.contoso.com",
    Use=SoapBindingUse.Literal)]
public string DocumentLiteral(Address1 address, bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod( _
   "https://www.contoso.com/DocumentLiteral", _
   RequestNamespace:="https://www.contoso.com", _
   ResponseNamespace:="https://www.contoso.com", _
   Use:=SoapBindingUse.Literal)>  _
Public Function DocumentLiteral(ByVal address As Address1, _
                         ByVal useZipPlus4 As Boolean) As String

    A continuación se proporciona la parte XML de la solicitud SOAP enviada al método de servicio Web XML DocumentLiteral. Los parámetros residen en el elemento Body y están codificados como documentos XML independientes, puesto que hacen referencia a un esquema XSD.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentLiteral xmlns="https://www.contoso.com">
      <address>
        <Street>One Microsoft Way</Street>
        <City>Redmond</City>
        <Zip>98052</Zip>
      </address>
      <useZipPlus4>True</useZipPlus4>
    </DocumentLiteral>
  </soap:Body>
</soap:Envelope>

Para especificar el formato de parámetros Encoded

  • Aplique un atributo SoapDocumentMethod o SoapRpcMethod al método de la clase de proxy, con el valor de la propiedad Use establecido a SoapBindingUse.Encoded.

    A diferencia del estilo de formato de parámetros Literal, el estilo Encoded se puede utilizar en combinación con ambos estilos de formato de métodos de servicio Web XML. Para obtener más información acerca de los estilos de formato de métodos de servicio Web XML, vea Modificar el formato general de BODY en SOAP

    [SoapDocumentMethod("https://www.contoso.com/DocumentEncoded",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com",
                    Use=SoapBindingUse.Encoded)]
public string DocumentEncoded(Address address, bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod("https://www.contoso.com/DocumentEncoded", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Encoded)>  _
Public Function DocumentEncoded(ByVal address As Address, _ 
                  ByVal useZipPlus4 As Boolean) As String

    A continuación se proporciona la parte XML de la solicitud SOAP enviada al método de servicio DocumentEncoded. Observe que los parámetros se representan de forma muy distinta que en el estilo de formato Literal, puesto que el formato sigue las reglas de codificación que se describen en la sección 5 de la especificación de SOAP. Preste especial atención al parámetro address, que no es un tipo de datos simple.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="https://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="https://www.contoso.com"
xmlns:tnsTypes="https://www.contoso.com/encodedTypes"
xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="https://schemas.xmlsoap.org/soap/encoding/">
    <tnsTypes:DocumentEncoded>
      <address href="#1" />
      <useZipPlus4>boolean</useZipPlus4>
    </tnsTypes:DocumentEncoded>
    <tnsTypes:Address id="1">
      <Street id="2">string</Street>
      <City id="3">string</City>
      <Zip id="4">string</Zip>
    </tnsTypes:Address>
  </soap:Body>
</soap:Envelope>

Modificar el formato general de Body en SOAP

En WSDL se definen dos estilos posibles para el formato de un método de servicio Web XML, que denomina operación, en el elemento Body de una solicitud o respuesta SOAP: RPC y Document. En ASP.NET se admiten ambos estilos de formato. El estilo predeterminado es Document.

El estilo RPC hace referencia al formato del elemento Body de acuerdo con la especificación de SOAP en lo que respecta al uso de SOAP para RPC, que también se conoce como la sección 7 de la especificación de SOAP. Este estilo establece que todos los parámetros se encapsulan en un solo elemento, con el mismo nombre que el método de servicio Web XML, y que cada elemento de dicho elemento representa un parámetro con el mismo nombre que su respectivo parámetro. Además, se describen reglas para el formato de las respuestas SOAP.

El estilo Document hace referencia al formato del elemento Body como una serie de una o varias partes del mensaje bajo el elemento Body. La manera exacta en que se forman las partes individuales del mensaje viene determinada por las propiedades Use y ParameterStyle del atributo SoapDocumentMethod. La propiedad Use determina si los parámetros tienen formato Encoded o Literal. La propiedad ParameterStyle determina si los parámetros está encapsulados en una única parte del mensaje bajo el elemento Body o si cada parámetro es una parte individual del mensaje. Para obtener más información sobre cómo establecer el valor de la propiedad ParameterStyle, vea Modificar si los parámetros se encapsulan en un solo elemento XML.

Para especificar el estilo de formato Document

  • Aplique un atributo SoapDocumentMethod al método de la clase de proxy que llama al método de servicio Web XML pertinente.

    En el estilo de formato Document, los servicios Web XML creados mediante ASP.NET permiten el uso de los estilos de formato de parámetros Literal y Encoded. En el ejemplo siguiente se combina el estilo de formato de métodos Document con el estilo de formato de parámetros Literal.

    [SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com",
                    Use=SoapBindingUse.Literal)]
public string DocumentWrappedLiteral(Address MyAddress, 
                                     bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Literal)> _
   Public Function DocumentWrappedLiteral(ByVal MyAddress As Address, _
                             ByVal useZipPlus4 As Boolean)As String

    Al igual que con el estilo de formato Document, se define un esquema XSD en la descripción de servicio que define la solicitud SOAP y la respuesta SOAP. A continuación se proporciona un extracto de la descripción de servicio para la solicitud SOAP del método de servicio Web XML DocumentWrappedLiteral. Como el primer parámetro para el método de servicio Web XML DocumentWrappedLiteral es una clase y se especificó el estilo de formato de parámetros Literal, se crea un esquema XSD para el tipo address.

    <s:elementname="DocumentWrappedLiteral">
  <s:complexType>
    <s:sequence>
       <s:element minOccurs="1" maxOccurs="1" name="MyAddress"nillable="true" type="s0:Address" /> 
       <s:element minOccurs="1" maxOccurs="1" name="useZipPlus4" type="s:boolean" /> 
    </s:sequence>
  </s:complexType>
</s:element>

<s:complexType name="Address">
   <s:sequence>
      <s:element minOccurs="1" maxOccurs="1" name="Street"nillable="true" type="s:string" /> 
      <s:element minOccurs="1" maxOccurs="1" name="City" nillable="true" type="s:string" /> 
      <s:element minOccurs="1" maxOccurs="1" name="Zip" nillable="true"
                 type="s:string" /> 
   </s:sequence>
</s:complexType>

    Dado el esquema XSD que se define en la descripción de servicio, a continuación se muestra la parte XML de la solicitud SOAP al método de servicio DocumentWrappedLiteral. Observe que los elementos XML debajo del elemento Body en la solicitud SOAP coinciden con los elementos definidos en el esquema XSD.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteral xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </DocumentWrappedLiteral>
  </soap:Body>
</soap:Envelope>

Para especificar el estilo de formato RPC

  • Aplique un atributo SoapRpcMethod al método de la clase de proxy que llama al método de servicio Web XML pertinente.

    Con el estilo de formato RPC, ASP.NET sólo admite el estilo de formato de parámetros Encoded. Por lo tanto, en el ejemplo de código siguiente no se especifica una propiedad Use para el formato de parámetros, porque el atributo SoapRpcMethod no tiene esa propiedad.

    [SoapRpcMethodAttribute("https://www.contoso.com/Rpc",
                        RequestNamespace="https://www.contoso.com",
                        ResponseNamespace="https://www.contoso.com")]
public Address Rpc(Address address, bool useZipPlus4) {
[Visual Basic]
<SoapRpcMethodAttribute("https://www.contoso.com/Rpc", _
                        RequestNamespace:="https://www.contoso.com", _
                        ResponseNamespace:="https://www.contoso.com")> _
Public Function Rpc(ByVal address As Address, _
                    ByVal useZipPlus4 As Boolean) As Address

    En la descripción de servicio no se define estrictamente un esquema XSD para la solicitud SOAP o la respuesta SOAP al método Rpc del ejemplo anterior, sino sólo las partes de que se componen. Por lo tanto, observe que en la solicitud SOAP para el método Rpc, los parámetros están encapsulados en un solo elemento y codificados mediante el formato de parámetros Encoded.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soapenc="https://schemas.xmlsoap.org/soap/encoding/"
             xmlns:tns="https://www.contoso.com"
             xmlns:tnsTypes="https://www.contoso.com/encodedTypes"
             xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="https://schemas.xmlsoap.org/soap/encoding/">
    <tns:Rpc>
      <address href="#1" />
      <useZipPlus4>boolean</useZipPlus4>
    </tns:Rpc>
    <tnsTypes:Address id="1">
      <Street id="2">string</Street>
      <City id="3">string</City>
      <Zip id="4">string</Zip>
    </tnsTypes:Address>
  </soap:Body>
</soap:Envelope>

Modificar si los parámetros se encapsulan en un solo elemento XML

Los parámetros de un método de servicio Web XML se pueden encapsular en un solo elemento si se asignan a elementos XML que residen en el elemento Body del mensaje SOAP. Como se ha visto, RPC siempre encapsula los parámetros en un solo elemento; sin embargo, si se utiliza el estilo de formato Document, se puede elegir. En la descripción de servicio, los parámetros se asignan a partes del mensaje SOAP. Si se encapsulan en un solo elemento XML, los parámetros se asignan a una única parte del mensaje. En caso contrario, pueden englobar varias partes del mensaje.

Para especificar que los parámetros se encapsulen en un solo elemento XML

  • Aplique un atributo SoapDocumentMethod al método de la clase de proxy que llama al método de servicio Web XML pertinente y establezca el valor de la propiedad ParameterStyle a Wrapped.

    En el ejemplo de código siguiente se establece ParameterStyle a Wrapped. También se establece el estilo de formato de parámetros a Literal.

    [SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral",
                    RequestNamespace="https://www.contoso.com",
                    ResponseNamespace="https://www.contoso.com", 
                    Use=SoapBindingUse.Literal, 
                    ParameterStyle=SoapParameterStyle.Wrapped)]
public string DocumentWrappedLiteral(Address1 address, 
                                     bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod("https://www.contoso.com/DocumentWrappedLiteral", _
                    RequestNamespace:="https://www.contoso.com", _
                    ResponseNamespace:="https://www.contoso.com", _
                    Use:=SoapBindingUse.Literal, _
                    ParameterStyle:=SoapParameterStyle.Wrapped)> _
Public Function DocumentWrappedLiteral(ByVal address As Address1, _
                             ByVal useZipPlus4 As Boolean) As String

    La parte XML de la solicitud SOAP encapsula los parámetros en un elemento que, de forma predeterminada, recibe el nombre del método de servicio Web XML.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteral xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </DocumentWrappedLiteral>
  </soap:Body>
</soap:Envelope>

    La parte XML de la respuesta SOAP encapsula los parámetros out del método de servicio Web XML e incluye el resultado en un elemento. De forma predeterminada, el elemento encapsulador tiene el mismo nombre que el método de servicio Web XML y la palabra Response agregada.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentWrappedLiteralResponse xmlns="https://www.contoso.com">
      <DocumentWrappedLiteralResult>string
      </DocumentWrappedLiteralResult>
    </DocumentWrappedLiteralResponse>
  </soap:Body>
</soap:Envelope>

Para especificar que los parámetros se coloquen inmediatamente a continuación del elemento Body

  • Aplique un atributo SoapDocumentMethod al método de la clase de proxy que llama al método de servicio Web XML pertinente y establezca el valor de la propiedad ParameterStyle a Bare.

    En el ejemplo siguiente, que se generó con la utilidad Wsdl.exe, se establece el valor de ParameterStyle a Bare y el estilo de formato de parámetros a Literal. Puesto que el espacio de nombres no se puede especificar en un elemento que encapsule todos los parámetros, se debe especificar de forma individual para cada parámetro y valor devuelto. Para ello, se debe aplicar un atributo XmlElementAttribute a cada parámetro y al valor devuelto, y se debe establecer la propiedad Namespace.

    [SoapDocumentMethod(
     "https://www.contoso.com/DocumentBareLiteral",
     Use=SoapBindingUse.Literal,
     ParameterStyle=SoapParameterStyle.Bare)]
[return: XmlElement(Namespace="https://www.contoso.com",                    IsNullable=true)]
public string DocumentBareLiteral(
   [XmlElement(Namespace="https://www.contoso.com",
                     IsNullable=true)] 
   Address1 MyAddress, 
   [XmlElement(Namespace="https://www.contoso.com",
            IsNullable=false)] 
   bool useZipPlus4) {
[Visual Basic]
<SoapDocumentMethod( _
     https://www.contoso.com/DocumentBareLiteral", _
     Use:=SoapBindingUse.Literal, _
     ParameterStyle:= SoapParameterStyle.Bare)> _
Public Function DocumentBareLiteral( _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=true)> _
   MyAddress As Address1, _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=false)> _
   useZipPlus4 As Boolean) _
   As <XmlElement([Namespace]:="https://www.contoso.com", _
                  IsNullable:=true)> _
   String

    Los elementos XML a los que se asignan los parámetros en la solicitud SOAP se encuentran justo después del elemento Body, cada uno de ellos especifica un espacio de nombres.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <MyAddress xmlns="https://www.contoso.com">
      <Street>string</Street>
      <City>string</City>
      <Zip>string</Zip>
    </MyAddress>
    <useZipPlus4 xmlns="https://www.contoso.com">boolean</useZipPlus4>
  </soap:Body>
</soap:Envelope>

    Los parámetros out, incluido el valor devuelto, se asignan a elementos XML a continuación del elemento Body en la respuesta SOAP. De forma predeterminada, el elemento de valor devuelto tiene el mismo nombre que el método de servicio Web XML con el sufijo Result.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DocumentBareLiteralResult xmlns="https://www.contoso.com">
       string</DocumentBareLiteralResult>
  </soap:Body>
</soap:Envelope>

Personalizar el mensaje SOAP que se espera recibir en un método de servicio Web XML

Si necesita cambiar el mensaje SOAP que se espera recibir en un servicio Web XML creado mediante ASP.NET, puede utilizar los mismos mecanismos que están disponibles para un cliente de servicios Web XML creado mediante ASP.NET. Puede controlar la asignación de parámetros a elementos XML, el elemento XML que representa el método de servicio Web XML y si los elementos asignados se encapsulan en un elemento. Los mismos atributos se pueden utilizar por cada método: SoapDocumentMethod y SoapRpcMethod. Además, puede establecer la configuración de formato predeterminada en el servicio Web XML mediante la aplicación de los correspondientes atributos SoapDocumentService y SoapRpcService al servicio Web XML. Al aplicar un atributo SoapDocumentService a un servicio Web XML, se establece como Document el estilo predeterminado de formato para los métodos de servicio Web XML. Igualmente, el atributo SoapRpcService establece el estilo predeterminado a RPC.

Para establecer el estilo predeterminado de formato de los métodos para un servicio Web XML

  • Aplique un atributo SoapRpcService o un atributo SoapDocumentService a la clase que implementa el servicio Web XML.

    En el siguiente ejemplo de código se establece en Document el estilo de formato de los métodos y en Literal el formato predeterminado de los parámetros, y se especifica que los parámetros se deben encapsular en un solo elemento.

    <%@ WebService Language="C#" Class="SoapDocumentServiceSample" %>
 using System.Web.Services;
 using System.Web.Services.Protocols;
 using System.Web.Services.Description;

[SoapDocumentService(Use=SoapBindingUse.Literal,
                     ParameterStyle=SoapParameterStyle.Wrapped)]
[WebService(Namespace="https://www.contoso.com")]
public class SoapDocumentServiceSample  
{
    [ WebMethod ]
    public string UseDefaultEncoding(Address MyAddress, 
                                     bool useZipPlus4) 
    {
     return "Use the default encodings for this XML Web service.";
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="SoapDocumentServiceSample" %>
Imports System.Web.Services
Imports System.Xml.Serialization
Imports System.Web.Services.Protocols
Imports System.Web.Services.Description

< SoapDocumentService(Use := SoapBindingUse.Literal, _
                      ParameterStyle := SoapParameterStyle.Wrapped)> _
Public Class SoapDocumentServiceSample
  < WebMethod > _
  Public Function UseDefaultEncoding(MyAddress as Address, _
                                     useZipPlus4 As Boolean) As String 
     Return "Use the default formattings for this XML Web service."
  End Function
End Class

    A continuación se proporciona la parte XML de la solicitud SOAP que se espera recibir en el método de servicio Web XML UseDefaultEncoding.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <UseDefaultEncoding xmlns="https://www.contoso.com">
      <MyAddress>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddress>
      <useZipPlus4>boolean</useZipPlus4>
    </UseDefaultEncoding>
  </soap:Body>
</soap:Envelope>

Personalizar el mensaje SOAP con serialización XML

Además de especificar el formato de los parámetros, el estilo de formato para el método de servicio Web XML y si los parámetros se encapsulan en un solo elemento o no, puede personalizar directamente un mensaje SOAP con serialización XML. En cierta medida, esto se ha visto ya con el atributo XmlElement, pero el espacio de nombres System.Xml.Serialization incluye muchos atributos para manipular el código XML. Dado que SOAP utiliza XML para codificar los datos enviados y recibidos por un servicio Web XML, los atributos del espacio de nombres System.Xml.Serialization son idóneos para personalizar el mensaje SOAP enviado y recibido por un servicio Web XML. Para obtener más información, vea System.Xml.Serialization.

Para especificar el nombre del elemento XML que representa un parámetro

  • Aplique al parámetro un atributo XmlElement en el que se especifique el nombre deseado para el elemento y, opcionalmente, un espacio de nombres si el formato de los parámetros se establece a Literal. Si el formato de los parámetros se establece a Encoded, aplique al parámetro un atributo SoapElement.

    En el ejemplo de código siguiente se espera que los nombres de los elementos que representan los parámetros sean MyAddressElement, MyZipElement y ReturnValueElement. También se espera que el nombre del elemento que representa el valor devuelto sea ReturnValueElement. El formato de los métodos de servicio Web XML del ejemplo es Document, que es la opción predeterminada para ASP.NET.

    <%@ WebService Language="C#" Class="SoapDocumentServiceSample" %>
 using System.Web.Services;
 using System.Web.Services.Protocols;
 using System.Xml.Serialization;

[WebService(Namespace="https://www.contoso.com")] 
public class SoapDocumentServiceSample  
{
  [ WebMethod ]
  [ return: XmlElement("ReturnValueElement",IsNullable=false)]
  public Address ValidateAddress(
    [XmlElement("MyAddressElement")] Address MyAddress,
    [XmlElement("MyZipElement")] bool useZipPlus4) 
  {
    useZipPlus4 = true;    
    return new Address();
  }
}
[Visual Basic]
<%@ WebService Language="VB" Class="SoapDocumentServiceSample" %>
 Imports System.Web.Services
 Imports System.Web.Services.Protocols
 Imports System.Xml.Serialization

<WebService(Namespace := "https://www.contoso.com")> _
Public Class SoapDocumentServiceSample
  < WebMethod > _
  Public Function ValidateAddress( _
       <XmlElement("MyAddressElement")> MyAddress As Address, _
       <XmlElement("MyZipElement")> useZipPlus4 As Boolean)  
       As <XmlElement("ReturnValueElement",IsNullable :=false)> _
       Address 
        useZipPlus4 = True 
     Return new Address()
  End Function
End Class

    A continuación se indica la solicitud SOAP que el servicio Web XML espera recibir. Observe que los nombres de los elementos coinciden con lo especificado en el atributo XmlElement, en contraste con los nombres de los parámetros.

    <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ValidateAddress xmlns="http://tempuri.org/">
      <MyAddressElement>
        <Street>string</Street>
        <City>string</City>
        <Zip>string</Zip>
      </MyAddressElement>
      <MyZipElement>boolean</MyZipElement>
    </ValidateAddress>
  </soap:Body>
</soap:Envelope>

Vea también

Presentar la serialización XML | System.Xml.Serialization (Espacio de nombres) | Alterar el mensaje SOAP mediante extensiones SOAP | SoapDocumentMethodAttribute | SoapRpcMethodAttribute | SoapDocumentServiceAttribute | SoapRpcServiceAttribute | Generar servicios Web XML mediante ASP.NET | Generar clientes de servicios Web XML