Personalizzazione dei messaggi SOAP

Articolo
04/11/2008

Per i servizi Web XML creati con ASP.NET e i relativi client creati con SOAP per la comunicazione con metodi di servizio Web XML, è disponibile un meccanismo avanzato che consente di controllare il formato del messaggio SOAP inviato e previsto dal server. SOAP stabilisce che il contenuto del messaggio SOAP inviato a e da un servizio Web XML debba essere in formato XML. Tuttavia, la formattazione XML non è rigorosamente definita. Per fornire un meccanismo che consenta di utilizzare i servizi Web XML che prevedono una formattazione differente, ASP.NET dispone di un meccanismo basato su attributi, per il controllo del formato di XML nel messaggio SOAP. È inoltre disponibile un meccanismo basato su attributi che consente di specificare a un livello più dettagliato i nomi dell'elemento e dell'attributo del SOAP inviato in rete.

La comunicazione tra i servizi Web XML e i relativi client è stabilita in larga parte da due standard del settore: SOAP e WSDL (Web Services Description Language). SOAP definisce uno schema di formattazione per i dati visualizzati sotto l'elemento Body e uno schema di formattazione per la modalità di formattazione dei parametri all'interno dell'elemento Body. Il primo schema viene definito sezione 7 di SOAP o semplicemente RPC. Per ulteriori informazioni sulla specifica SOAP, vedere il sito Web W3C all'indirizzo http://www.w3.org/TR/SOAP (informazioni in lingua inglese). Il secondo schema viene definito sezione 5 di SOAP o semplicemente Encoded. WSDL, utilizzato per descrivere i messaggi SOAP previsti da un servizio Web XML, consente ai servizi Web XML di dichiarare l'accettazione dei messaggi RPC con parametri codificati e definisce, inoltre, altri due termini: Literal e Document. Literal, come Encoded, si riferisce alla modalità di formattazione dei parametri. Document, come RPC, si riferisce alla modalità di formattazione dell'elemento Body complessivo.

Personalizzazione del SOAP inviato da un client Web XML

Nella tabella seguente vengono descritti gli stili di formattazione supportati dai servizi Web XML creati con ASP.NET e gli attributi che consentono di ottenere ogni combinazione specifica. Gli attributi con un suffisso Service possono essere applicati a una classe che implementa un servizio Web XML per impostare lo stile di formattazione predefinito per metodi di servizio Web XML all'interno della classe. Gli attributi con un suffisso Method possono essere applicati a un solo metodo di servizio Web XML o a un metodo in una classe proxy che chiama un metodo di servizio Web XML. Nei paragrafi successivi viene descritta in dettaglio ciascuna combinazione.

	Formattazione complessiva del corpo di SOAP
Formattazione dei parametri	Messaggi SOAP basati su Document	Messaggi SOAP basati su RPC in base alla Sezione 7 di SOAP
Literal — basato su uno schema XSD per ogni parametro	SoapDocumentMethod o SoapDocumentService Use=Literal Si tratta dell'impostazione predefinita.	Non supportato.
Encoded - regole di codifica della Sezione 5 di SOAP	SoapDocumentMethod o SoapDocumentService Use=Encoded	SoapRpcMethod o SoapRpcService

Formattazione complessiva del corpo di SOAP

Formattazione dei parametri

Messaggi SOAP basati su Document

Messaggi SOAP basati su RPC in base alla Sezione 7 di SOAP

Literal — basato su uno schema XSD per ogni parametro

SoapDocumentMethod o SoapDocumentService

Use=Literal

Si tratta dell'impostazione predefinita.

Non supportato.

Encoded - regole di codifica della Sezione 5 di SOAP

SoapDocumentMethod o SoapDocumentService

Use=Encoded

SoapRpcMethod o SoapRpcService

Modifica della formattazione dei parametri

Una delle prime decisioni da prendere quando si progetta un servizio Web XML riguarda la modalità che si desidera utilizzare per la codifica dell'XML all'interno della richiesta SOAP, in particolare se si desidera che il documento XML segua rigorosamente uno schema XSD o le regole di formattazione riportate nelle sezioni 5 e 7 della specifica SOAP. Le regole di formattazione della specifica SOAP riportate nelle sezioni 5 e 7 consentono alcune variazioni. Pertanto, un destinatario di una richiesta SOAP che utilizza le regole di codifica SOAP deve gestire tutte le possibili variazioni. Definendo uno schema XSD per il metodo di servizio Web XML, è possibile definire esattamente ciò che è necessario inviare in una richiesta SOAP. L'impostazione predefinita per i servizi Web XML creati con ASP.NET è il passaggio dei documenti basato su schemi.

Poiché i parametri di un metodo di servizio Web XML possono rappresentare la maggior parte dei dati passati in una richiesta o risposta SOAP, il modo in cui viene eseguito il mapping dei parametri a elementi XML determina l'aspetto del documento XML. WSDL (Web Services Description Language) definisce due stili di formattazione per i parametri: Encoded e Literal. Encoded si riferisce alla formattazione dei parametri secondo le regole di codifica SOAP descritte nelle specifiche SOAP nella Sezione 5. Literal si riferisce al mapping dei parametri a elementi XML mediante uno schema XSD predefinito per ogni parametro.

Con un client del servizio Web XML, è possibile scegliere il tipo di mapping dei parametri a elementi XML in modo da corrispondere a quanto previsto dal servizio Web XML. I servizi Web XML supportano entrambi gli stili di formattazione dei parametri Literal e Encoded. Gli stili di formattazione supportati variano in base alla scelta di formattazione del metodo di servizio Web XML. Per ulteriori informazioni, vedere Modifica della formattazione complessiva del corpo di SOAP.

Si noti che, sebbene ASP.NET fornisce un'architettura completa per il controllo della modalità di formattazione di XML, l'ordine di serializzazione dei parametri non viene garantito.

Per specificare la formattazione dei parametri Literal

Applicare un attributo SoapDocumentMethod a un metodo nella classe proxy, impostando la proprietà Use su SoapBindingUse.Literal.

L'enumerazione SoapBindingUse specifica gli stili di formattazione dei parametri disponibili per un servizio Web XML creato con 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

Di seguito è riportata la parte XML della richiesta SOAP al metodo di servizio Web XML DocumentLiteral. I parametri si trovano all'interno dell'elemento Body e vengono codificati come documenti XML indipendenti, poiché si riferiscono a uno schema 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>

Per specificare la formattazione dei parametri Encoded

Applicare un attributo SoapDocumentMethod o un attributo SoapRpcMethod al metodo nella classe proxy, impostando la proprietà Use su SoapBindingUse.Encoded.

A differenza dello stile di formattazione dei parametri Literal, lo stile di formattazione dei parametri Encoded può essere utilizzato in combinazione con entrambi gli stili di formattazione del metodo di servizio Web XML. Per ulteriori informazioni sugli stili di formattazione del metodo di servizio Web XML, vedere Modifica della formattazione complessiva del corpo di 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

Di seguito è riportata la parte XML della richiesta SOAP al metodo di servizio DocumentEncoded. Si noti come i parametri vengono rappresentati diversamente da quanto avviene con lo stile di formattazione Literal, poiché sono formattati seguendo le regole di codifica descritte nella Sezione 5 della specifica SOAP. Prestare particolare attenzione al parametro address, che non è un semplice tipo di dati.

<?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>

Modifica della formattazione complessiva del corpo di SOAP

In WSDL vengono definiti due stili per la formattazione di un metodo di servizio Web XML, che viene denominata operazione, all'interno dell'elemento Body di una richiesta o risposta SOAP: RPC e Document. In ASP.NET, sono supportati entrambi gli stili di formattazione Document e RPC. L'impostazione predefinita è Document.

Lo stile RPC si riferisce alla formattazione dell'elemento Body in base alla specifica SOAP per l'utilizzo di SOAP per RPC, altrimenti nota come Sezione 7 della specifica SOAP. Questo stile stabilisce che tutti i parametri siano incapsulati all'interno di un singolo elemento, denominato come il metodo di servizio Web XML, e che ogni elemento in esso contenuto rappresenti un parametro a cui viene assegnato il nome del rispettivo parametro. Lo stile stabilisce inoltre le regole di formattazione delle risposte SOAP.

Lo stile Document si riferisce alla formattazione dell'elemento Body come una serie di una o più parti di messaggio sotto l'elemento Body. Il modo esatto in cui vengono formate le parti del messaggio viene determinato dalle proprietà Use e ParameterStyle dell'attributo SoapDocumentMethod. La proprietà Use determina se i parametri vengono formattati come Encoded o Literal. ParameterStyle determina se i parametri sono incapsulati all'interno di una parte di un singolo messaggio sotto l'elemento Body o se ogni parametro è una parte di messaggio individuale. Per ulteriori informazioni sull'impostazione della proprietà ParameterStyle, vedere Modifica di parametri incapsulati in un elemento XML.

Per specificare uno stile di formattazione Document

Applicare un attributo SoapDocumentMethod al metodo nella classe proxy che chiama il metodo di servizio Web XML appropriato.

Con lo stile di formattazione Document, i servizi Web XML creati con ASP.NET supportano l'utilizzo di entrambi gli stili di formattazione dei parametri Literal ed Encoded. Nell'esempio seguente viene combinato lo stile di formattazione Document con lo stile di formattazione dei parametri 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

Come previsto per lo stile di formattazione Document, viene definito uno schema XSD all'interno della descrizione del servizio che definisce sia la richiesta che la risposta SOAP. Di seguito viene riportato un estratto della descrizione del servizio per una richiesta SOAP relativa al metodo di servizio Web XML DocumentWrappedLiteral. Poiché il primo parametro nel metodo di servizio Web XML DocumentWrappedLiteral è una classe ed è stato specificato lo stile di formattazione dei parametri Literal, viene creato uno schema XSD per il 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>

Sulla base allo schema XSD definito nella descrizione del servizio, di seguito è riportata la parte XML della richiesta SOAP al metodo di servizio DocumentWrappedLiteral. Si noti che gli elementi XML sotto l'elemento Body nella richiesta SOAP corrispondono agli elementi definiti nello schema 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>

Per specificare lo stile di formattazione RPC

Applicare un attributo SoapRpcMethod al metodo nella classe proxy che chiama il metodo di servizio Web XML appropriato.

Con lo stile di formattazione RPC, ASP.NET supporta solo lo stile di formattazione dei parametri Encoded. Nell'esempio di codice seguente, pertanto, non viene specificata la proprietà Use per la formattazione dei parametri, poiché l'attributo SoapRpcMethod non dispone di una proprietà Use.

[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

Uno schema XSD non viene definito rigorosamente nella descrizione del servizio per la richiesta o la risposta SOAP inviata al metodo Rpc descritto nell'esempio precedente, bensì vengono definite soltanto le parti che lo compongono. Osservare pertanto la richiesta SOAP per il metodo Rpc, tenendo presente che i parametri sono incapsulati all'interno di un elemento e vengono codificati con la formattazione dei parametri 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>

Modifica di parametri incapsulati in un elemento XML

I parametri di un metodo di servizio Web XML possono essere incapsulati in un elemento XML quando vengono mappati a elementi XML che si trovano all'interno dell'elemento Body del messaggio SOAP. Come illustrato in precedenza, RPC incapsula sempre i parametri all'interno di un elemento. Tuttavia è possibile scegliere quando utilizzare lo stile di formattazione Document. Nella descrizione del servizio viene eseguito il mapping dei parametri a parti del messaggio SOAP, denominate parti del messaggio. Quando vengono incapsulati in un elemento XML, i parametri vengono mappati a una singola parte del messaggio. Quando invece i parametri non vengono incapsulati, possono comprendere più parti del messaggio.

Per specificare che i parametri devono essere incapsulati in un elemento XML

Applicare un attributo SoapDocumentMethod al metodo nella classe proxy che chiama il metodo di servizio Web XML appropriato, impostando la proprietà ParameterStyle su Wrapped.

Nell'esempio di codice seguente, ParameterStyle viene impostato su Wrapped e lo stile di formattazione dei parametri su 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 della richiesta SOAP incapsula i parametri in un elemento che, per impostazione predefinita, viene denominato come il metodo di servizio 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 della risposta SOAP incapsula i parametri out per il metodo di servizio Web XML, compreso il risultato all'interno di un elemento. Per impostazione predefinita, il nome dell'elemento in cui i parametri vengono incapsulati corrisponde al nome del metodo di servizio Web XML seguito da Response.

<?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>

Per specificare che i parametri devono seguire direttamente l'elemento Body

Applicare l'attributo SoapDocumentMethod al metodo nella classe proxy che chiama il metodo di servizio Web XML appropriato, impostando la proprietà ParameterStyle su Bare.

Nell'esempio seguente, generato da Wsdl.exe, ParameterStyle viene impostato su Bare e lo stile di formattazione dei parametri su Literal. Poiché è impossibile specificare lo spazio dei nomi in un elemento in cui sono incapsulati tutti i parametri, lo spazio dei nomi deve essere specificato singolarmente per ogni parametro e valore restituito. È possibile eseguire questa operazione applicando un XmlElementAttribute a ogni parametro e valore restituito e impostando la proprietà 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

Gli elementi XML a cui è stato eseguito il mapping dei parametri all'interno della richiesta SOAP seguono direttamente l'elemento Body e ognuno specifica uno spazio dei nomi.

<?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>

Viene eseguito il mapping dei parametri out, compreso il valore restituito, agli elementi XML che seguono l'elemento Body all'interno della risposta SOAP. Per impostazione predefinita, il nome dell'elemento del valore restituito è composto dal nome del metodo di servizio Web XML con un suffisso 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>

Personalizzazione del SOAP previsto da un metodo di servizio Web XML

Se è necessario modificare il SOAP previsto da un servizio Web XML creato con ASP.NET, sarà possibile utilizzare gli stessi meccanismi disponibili per un client del servizio Web XML creato con ASP.NET. È possibile controllare il mapping di parametri a elementi XML, l'elemento XML che rappresenta il metodo di servizio Web XML e se gli elementi mappati sono incapsulati all'interno di un elemento. Gli stessi attributi possono essere utilizzati in base al metodo, ovvero SoapDocumentMethod e SoapRpcMethod. È inoltre possibile definire le impostazioni di formattazione predefinite a livello di servizio Web XML applicando gli attributi SoapDocumentService e SoapRpcService corrispondenti al servizio Web XML. L'applicazione di un attributo SoapDocumentService a un servizio Web XML consente di impostare su Document lo stile di formattazione del metodo predefinito per i relativi metodi di servizio Web XML. In modo analogo, l'attributo SoapRpcService definisce l'impostazione predefinita dello stile su RPC.

Per impostare lo stile di formattazione del metodo predefinito per un servizio Web XML

Applicare l'attributo SoapRpcService o l'attributo SoapDocumentService alla classe che implementa il servizio Web XML.

Nell'esempio di codice che segue vengono impostati lo stile di formattazione del metodo su Document e la formattazione dei parametri predefinita su Literal e viene specificato che i parametri devono essere incapsulati all'interno di un singolo 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

Di seguito è riportata la parte XML della richiesta SOAP prevista dal metodo di servizio 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>

Personalizzazione del messaggio SOAP con la serializzazione XML

Oltre a specificare la formattazione dei parametri, lo stile di formattazione del metodo del servizio Web XML e se i parametri devono essere incapsulati o meno all'interno di un elemento, è possibile personalizzare direttamente un messaggio SOAP con la serializzazione XML, già illustrata in parte in relazione all'attributo XmlElement. Lo spazio dei nomi System.Xml.Serialization comprende comunque numerosi attributi per la modifica dell'XML. Dato che SOAP utilizza XML per codificare i dati inviati e ricevuti da un servizio Web XML, gli attributi nello spazio dei nomi System.Xml.Serialization rappresentano la soluzione ideale per la personalizzazione del SOAP inviato e ricevuto da un servizio Web XML. Per ulteriori informazioni, vedere System.Xml.Serialization.

Per specificare il nome dell'elemento XML che rappresenta un parametro

Se la formattazione dei parametri è impostata su Literal, applicare un attributo XmlElement al parametro, specificando il nome desiderato per l'elemento ed eventualmente uno spazio dei nomi. Se la formattazione dei parametri è impostata su Encoded, applicare al parametro un attributo SoapElement.

Nell'esempio di codice seguente è previsto che i nomi degli elementi che rappresentano i parametri siano MyAddressElement, MyZipElement e ReturnValueElement. È inoltre previsto che il nome dell'elemento che rappresenta il valore restituito sia ReturnValueElement. Lo stile di formattazione del metodo di servizio Web XML nell'esempio è Document, che rappresenta l'impostazione predefinita per 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

Il servizio Web XML prevede la richiesta SOAP seguente. Si noti che i nomi degli elementi corrispondono a quanto specificato nell'attributo XmlElement e non ai nomi dei parametri.

<?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>

Vedere anche