Compatibilidad de .NET Framework para formatos SOAP

Este tema es específico de una tecnología heredada. Ahora, los servicios Web XML y los clientes de servicios Web XML deben crearse con Windows Communication Foundation.

En lugar de hacer a mano un documento WSDL, un programador que crea un servicio Web para ASP.NET puede especificar estos formatos SOAP aplicando los atributos a métodos de servicio Web individuales o clases de servicio de la Web entera. Si un programador no especifica estos atributos, se utilizan los formatos SOAP predeterminados.

Si está desarrollando un servicio Web basado en un documento WSDL existente, puede ejecutar la herramienta Wsdl.exe con la opción server para generar una clase de servicio Web abstracta que tenga los valores de atributo adecuados establecidos automáticamente.

Sin la opción server, Wsdl.exe genera una clase proxy de cliente que establece los atributos de formato SOAP pertinentes en los valores adecuados para comunicar con el servicio Web descritos por el documento de WSDL de entrada. Una clase proxy de cliente utiliza la mayoría de los mismos atributos que se pueden especificar en el servidor. Normalmente, un programador no necesita agregar manualmente o modificar estos atributos en la clase proxy de cliente porque Wsdl.exe genera normalmente el cliente para asegurarse de que obedece al contrato de servicios especificado por el documento WSDL.

La tabla siguiente describe las opciones de formato admitidas por servicio Web y los clientes creados utilizando ASP.NET y .NET Framework, junto con los atributos que logran cada combinación concreta. Los atributos con un sufijo de ServiceServicio se pueden aplicar a una clase que implementa un servicio Web (no una clase proxy de cliente) para establecer el estilo de formato predeterminado para los métodos de servicio Web dentro de la clase. Los atributos con un sufijo Method se pueden aplicar o a un método de servicio Web o a un método en una clase proxy de cliente que llama a un método de servicio Web. Los detalles de cada combinación se cubren en los párrafos siguientes.

Formato de parámetro (uso)	Body de SOAP que da formato (estilo) a los mensajes SOAP basados en Documento	Body de SOAP que da formato (estilo) a los mensajes SOAP basados en RPC según SOAP 1.1, sección 7s
Literal: basado en un esquema XSD para cada parámetro	SoapDocumentMethod o bien SoapDocumentService Utilice= Literal. Este es el valor predeterminado.	SoapRpcMethod o bien SoapRpcService Utilice= Literal.
Se codifica - SOAP 1.1, Sección 5, reglas de codificado	SoapDocumentMethod o bien SoapDocumentService Utilice= Encoded.	SoapRpcMethod o bien SoapRpcService Utilice= Encoded. Este es el valor predeterminado.

Nota:
Los nombres de atributo reales utilizan el sufijo Attribute. En el código fuente, los nombres se pueden abreviar, como se muestra en la tabla anterior.

Controlar el formato general del elemento Body en SOAP

Para el estilo, que controla si el motor de ejecución del servicio Web aplica las convenciones de RPC o si aplaza los documentos XML, la opción predeterminada en un servicio Web ASP.NET es documento, no RPC.

El estilo de documento se puede especificar explícitamente aplicando el atributo SoapDocumentMethodAttribute a un método de servicio Web o método de proxy de cliente o aplicando el atributo SoapDocumentServiceAttribute a una clase de servicio Web. El estilo de RPC se puede especificar explícitamente aplicando el atributo SoapRpcMethodAttribute**** a un método de servicio Web o método de proxy de cliente o aplicando el atributo SoapRpcServiceAttribute a una clase de servicio Web. Para un servicio, un atributo del nivel de método invalida un atributo de nivel de clase.

Estos mismos atributos representan un rol para determinar el parámetro y el formato del valor devuelto, tal como se describe más tarde en este tema. También desempeña el rol de determinar si un elemento "contenedor" se genera automáticamente en el tiempo de ejecución para contener los parámetros o el valor devuelto. Para obtener más información, vea Cómo: Controlar si los parámetros del método del servicio web están encerrados en un elemento adicional.

Para obtener más información sobre cómo aplicar estos atributos, vea Cómo: Controlar el formato general del elemento Body en SOAP para un método de servicio web.

Controlar el parámetro y el formato del valor devuelto

Para el uso, que controla el formato de los parámetros de método de servicio Web o un valor devuelto, la opción predeterminada en un servicio Web ASP.NET de estilo de documento es literal. La opción predeterminada en un servicio Web ASP.NET de estilo RPC es codificada. Puede cambiar el valor de uso estableciendo la propiedad Use en los atributos SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute o SoapRpcServiceAttribute correspondientes en SoapBindingUse.Literal o SoapBindingUse.Encoded.

Para obtener más información sobre cómo establecer la propiedad Use, vea Cómo: Controlar el formato de parámetros y valores devueltos para un método de servicio Web.

Controlar si los parámetros se agregan en un elemento XML adicional

Los parámetros o el valor devuelto para un método de servicio Web se puede encapsular automáticamente dentro de un elemento XML primario dentro del elemento Body del mensaje SOAP. El programador no tiene que especificar el elemento principal. Como ya ha observado, el estilo de formato de RPC actúa de este modo. Sin embargo, también es una opción con un estilo de formato de documento. En lugar del elemento XML primario o contenedor, especificado en el documento WSDL, la infraestructura de los servicio Web inserta implícitamente el elemento adicional en el tiempo de ejecución.

Esta convención se llama de ajuste y se puede especificar estableciendo propiedad SoapDocumentService.ParameterStyle o SoapDocumentMethod.ParameterStyle en un valor de SoapParameterStyle.Wrapped. Wrapped también es el valor predeterminado.

La enumeración SoapParameterStyle también tiene un valor predeterminado para especificar el estilo de parámetro predeterminado en el nivel de clase del servicio, más un valor Bare para desactivar el ajuste y traducir literalmente los elementos XML que el WSDL especifica como partes de mensajes en los parámetros de método y valores devueltos. Con un estilo de parámetroBare, cada parámetro o valor devuelto corresponde a una parte del mensaje especificada.

La opción de si ser ajustado, o no, no se especifica en un documento WSDL; con ambos Wrapped y Bare, el estilo de enlace que se utiliza es el de documento. Más bien, la opción implica el enlace entre XML y el código - entre el XML definido en el WSDL y los parámetros y valores devueltos de los métodos.

Con la propiedad ParameterStyle establecida para SoapParameterStyle.Bare, el programador puede especificar un mensaje que tiene varias partes - literalmente varios elementos XML que aparecen como elementos secundarios del elemento Body de SOAP. Técnicamente, varios elementos no constituyen un documento XML porque un documento debe tener una raíz única. Por consiguiente, el ejercicio recomendado en la comunidad de los servicio Web es utilizar una parte del mensaje única con servicios del estilo de documento. Cada método de servicio Web no debe utilizar su firma intencional sino una firma donde una asignación de objeto a un documento XML es el parámetro único y otra asignación de objeto a un documento XML es el valor devuelto. Un programador debe escribir el código para extraer o empaquetar los verdaderos parámetros o valores devueltos.

Por consiguiente, normalmente es suficiente para un programador establecer la propiedad ParameterStyle en SoapParameterStyle.Wrapped y permitir que la infraestructura de servicio Web coloque los parámetros y valores devueltos en los documentos XML.

Para obtener más información sobre cómo establecer la propiedad ParameterStyle, vea Cómo: Controlar si los parámetros del método del servicio web están encerrados en un elemento adicional.

Establecer el formato SOAP predeterminado para un Servicio de toda la Web

Como se ha descrito anteriormente en este tema, SoapDocumentServiceAttribute y los atributos SoapRpcServiceAttribute se pueden utilizar para establecer los valores predeterminados para el estilo y para el uso y estilo de asignación de parámetros a documentos para una clase de servicio de la Web entera, pero no para una clase proxy de cliente. Los atributos SoapDocumentMethod y SoapRpcMethod se pueden utilizar para anular los valores de nivel del servicio de cada método de servicio Web.

Para obtener más información sobre cómo utilizar atributos SoapRpcService y SoapDocumentService, vea Cómo: Modificar el formato SOAP predeterminado para todo un servicio web.

Personalizar los mensajes SOAP con serialización XML

Además de especificar el estilo, el uso, y si insertar un elemento contenedor, puede personalizar directamente el XML en un mensaje SOAP con serialización XML. De forma predeterminada, la infraestructura de los servicios Web del .NET Framework serializa automáticamente campos públicos y propiedades en los mensajes XML.

El espacio de nombres System.Xml.Serialization incluye numerosos atributos para manipular XML. El ejemplo de código siguiente muestra cómo algunos de estos atributos se pueden aplicar directamente a parámetros de método de servicio Web o valores devueltos.

[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) {

<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

Algunos atributos utilizados normalmente están listados como sigue, sus nombres aparecen sin el sufijo Attribute, que se puede omitir:

• XmlElement: especifica que un campo público o propiedad se serializa como un elemento XML. Éste es el atributo predeterminado para serializar campos públicos no matriciales y propiedades. Cuando el atributo XmlElement se aplica a los campos públicos y propiedades de un atributo de tipo de matriz, la matriz se serializa junto a otros miembros, sin un elemento principal especial.

• XmlAttribute: especifica que un campo público o propiedad se serializa como un atributo XML del elemento que representa el tipo contenedor.

• XmlArray: especifica que un campo público de un tipo de matriz se serializa con un elemento principal especial. Éste es el atributo predeterminado para serializar campos públicos y propiedades de un tipo de matriz.

• XmlArrayItem: utilizado en combinación con el atributo XmlArray para controlar los elementos de matriz.

• XmlIgnore: especifica que no se serialice ningún campo público o propiedad.

Los atributos anteriores, salvo XmlIgnore, también se pueden utilizar para especificar un elemento o nombre de atributo además del valor predeterminado, que es el nombre de miembro para los miembros no matriciales. También se pueden utilizar para especificar un espacio de nombres para un elemento determinado. Normalmente, un servicio Web no mezcla espacios de nombres y solo se necesita especificar un espacio de nombres en el nivel de clase, utilizando un atributo como WebService o WebServiceBinding.

Para obtener más información, vea , consulte System.Xml.Serialization.

Nota:
Para RPC o los servicios Web codificados, con estilo RPC con codificación SOAP, el uso de la serialización XML está restringido. Los parámetros y valores devueltos aparecen automáticamente sin la calificación de espacio de nombres. También, SOAP 1.1, Sección 5, codificación, combinado con un documento o estilo RPC, prohíbe el enlace de datos a los atributos XML.

Nota:
Si una clase de servicio abstracta o la clase proxy de cliente se genera a partir de un documento WSDL, los atributos System.Xml.Serialization correctos se aplican automáticamente para los elementos y tipos de esquema XML que se define bajo el elemento WSDL types, si aparecen alineados o si se importan.

Nota:

Utilizar los tipos que aceptan valores Null en los resultados de un servicio Web en WSDL que contiene el valor "nillable=true" establecido para el tipo. Sin embargo, cuando los tipos Nullable se utilizan directamente como parámetros de método de web o valores devueltos, la condición de admisión de valores null no se reflejará en el WSDL resultante en los casos siguientes: 1) cuando se utilizan los mensajes SOAP basados en RPC, y 2) Cuando los mensajes SOAP basados en Documento se utilizan con parámetros codificados en el modo Bare.

Para obtener más información sobre cómo utilizar el atributo XmlElement, vea Cómo: Personalizar mensajes SOAP con serialización XML.

Vea también

Tareas

Cómo: Controlar el formato general del elemento Body en SOAP para un método de servicio web
Cómo: Controlar el formato de parámetros y valores devueltos para un método de servicio Web
Cómo: Controlar si los parámetros del método del servicio web están encerrados en un elemento adicional
Cómo: Modificar el formato SOAP predeterminado para todo un servicio web
Cómo: Personalizar mensajes SOAP con serialización XML

Referencia

System.Xml.Serialization
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute

Conceptos

Modificación de mensajes SOAP con extensiones SOAP
Generar clientes de servicios web XML

Otros recursos

Introducing XML Serialization