Supporto .NET Framework per i formati SOAP

Questo argomento è specifico di una tecnologia legacy. Servizi Web XML e client di servizi Web XML devono essere creati attualmente tramite Windows Communication Foundation.

Invece di creare manualmente un documento WSDL, uno sviluppatore che crea un servizio Web per ASP.NET può specificare i formati SOAP applicando attributi a metodi del servizio Web singoli o a intere classi del servizio Web. Se lo sviluppatore non specifica questi attributi, verranno utilizzati formati SOAP predefiniti.

Se si sta sviluppando un servizio Web basato su un documento WSDL esistente, è possibile eseguire lo strumento Wsdl.exe con l'opzione /server per generare una classe astratta del servizio Web in cui i valori degli attributi appropriati vengono impostati automaticamente.

Senza l'opzione /server, Wsdl.exe produce una classe proxy client che imposta gli attributi di formattazione SOAP pertinenti su valori che consentono la comunicazione con il servizio Web descritto dal documento WSDL di input. Una classe proxy client utilizza la maggior parte degli stessi attributi che possono essere specificati sul server. Normalmente, un sviluppatore non ha bisogno di aggiungere manualmente o di modificare gli attributi nella classe proxy client perché di solito il client viene generato da Wsdl.exe in modo da garantirne la conformità rispetto al contratto di servizio specificato dal documento WSDL.

La tabella seguente delinea le scelte di formattazione supportate da servizi Web e client creati utilizzando ASP.NET e .NET Framework, insieme agli attributi che caratterizzano ogni combinazione specifica. Gli attributi con suffisso Service possono essere applicati a una classe che implementa un servizio Web (non a una classe proxy client) per impostare lo stile di formattazione predefinito per i metodi del servizio Web all'interno della classe. Gli attributi con suffisso Method possono essere applicati sia a un metodo del servizio Web sia a un metodo di una classe proxy client che chiama un metodo del servizio Web. I dettagli di ognuna di queste combinazioni vengono analizzati nei paragrafi seguenti.

Formattazione del parametro (utilizzo)	Formattazione del corpo del testo del messaggio SOAP (stile) per i messaggi SOAP basati su Document	Formattazione del corpo del testo del messaggio SOAP (stile) per i messaggi SOAP basati su RPC secondo SOAP 1.1 Sezione 7s
Literal. In base a uno schema XSD per ogni parametro	SoapDocumentMethod oppure SoapDocumentService Utilizzare=Literal Questa è l'impostazione predefinita.	SoapRpcMethod oppure SoapRpcService Utilizzare=Literal
Encoded. Regole di codifica SOAP 1.1 Sezione 5	SoapDocumentMethod oppure SoapDocumentService Utilizzare=Encoded	SoapRpcMethod oppure SoapRpcService Utilizzare=Encoded Questa è l'impostazione predefinita.

Nota:
I nomi effettivi degli attributi utilizzano il suffisso Attribute. Nel codice sorgente i nomi possono essere abbreviati, come mostrato dalla tabella precedente.

Controllare la formattazione complessiva del corpo dei messaggi SOAP

Per lo stile che controlla se il motore di runtime del servizio Web applica le convenzioni RPC o rinvia ai documenti XML, la scelta predefinita in un servizio Web ASP.NET è Document, non RPC.

Lo stile Document può essere specificato in modo esplicito applicando l'attributo SoapDocumentMethodAttribute a un metodo del servizio Web o a un metodo del proxy client oppure applicando l'attributo SoapDocumentServiceAttribute a una classe del servizio Web. Lo stile RPC può essere specificato in modo esplicito applicando l'attributo SoapRpcMethodAttribute a un metodo del servizio Web o a un metodo del proxy client oppure applicando l'attributo SoapRpcServiceAttribute a una classe del servizio Web. Per un servizio, un attributo a livello di metodo esegue l'override di un attributo a livello di classe.

Questi stessi attributi giocano un ruolo nel determinare la formattazione del parametro e del valore restituito, come descritto più avanti in questo argomento. Giocano un ruolo anche nel determinare se un elemento "wrapper" viene generato automaticamente in fase di runtime per contenere i parametri o il valore restituito. Per ulteriori informazioni, vedere Procedura: controllare se i parametri del metodo del servizio Web sono racchiusi in un elemento supplementare..

Per ulteriori informazioni su su come applicare questi attributi, vedere Procedura: controllare la formattazione complessiva del corpo dei messaggi SOAP per un metodo del servizio Web.

Verifica della formattazione del parametro e del valore restituito

Per l'utilizzo, che controlla la formattazione dei parametri dei metodi del servizio Web o dei valori restituiti, la scelta predefinita in un servizio Web ASP.NET con stile Document è literal. La scelta predefinita in un servizio Web ASP.NET con stile RPC è encoded. È possibile modificare il valore di utilizzo impostando la proprietà Use per gli attributi SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute o SoapRpcServiceAttribute corrispondenti su SoapBindingUse.Literal oppure su SoapBindingUse.Encoded.

Per ulteriori informazioni su su come impostare la proprietà Use, vedere Procedura: formattazione del parametro di controllo e del valore restituito per un metodo del servizio Web.

Verifica dell'inserimento dei parametri in un elemento XML supplementare

I parametri o il valore restituito per un metodo del servizio Web possono essere inclusi automaticamente all'interno di un elemento XML padre nell'elemento Body del messaggio SOAP. Non è necessario che lo sviluppatore specifichi l'elemento padre. Come si è visto, ciò è dovuto allo stile di formattazione RPC. Tuttavia, è anche un'opzione con uno stile di formattazione Document. L'elemento supplementare viene inserito implicitamente dall'infrastruttura dei servizi Web in fase di runtime al posto dell'elemento XML padre, o wrapper, specificato nel documento WSDL.

Questa convenzione viene denominata wrapping e può essere specificata impostando la proprietà SoapDocumentMethod.ParameterStyle o SoapDocumentService.ParameterStyle sul valore SoapParameterStyle.Wrapped. Wrapped è anche il valore predefinito.

L'enumerazione SoapParameterStyle presenta inoltre un valore predefinito che consente di specificare lo stile del parametro predefinito a livello della classe del servizio, più un valore Bare che consente di disattivare il wrapping e tradurre letteralmente gli elementi XML specificati da WSDL come parti del messaggio in parametri del metodo e valori restituiti. Con uno stile di parametro Bare, ogni parametro o valore restituito corrisponde a una parte del messaggio specificata.

La scelta di effettuare o meno il wrapping non è specificata in un documento WSDL. Lo stile di associazione utilizzato con Wrapped e Bare è sempre Document. Tuttavia, la scelta riguarda l'associazione tra XML e codice, tra l'XML definito in WSDL e i parametri e i valori restituiti dei metodi.

Con la proprietà ParameterStyle impostata su SoapParameterStyle.Bare, lo sviluppatore è in grado di specificare un messaggio costituito da più parti, letteralmente più elementi XMLi che appaiono come figli dell'elemento Body del messaggio SOAP. Tecnicamente più elementi non costituiscono un documento XML, poiché un documento deve avere una sola radice. Pertanto, la pratica raccomandata nella community dei servizi Web è di utilizzare una sola parte del messaggio con servizi con stile Document. Ogni metodo del servizio Web non deve utilizzare la firma prevista ma una firma in cui un oggetto che esegue il mapping di un documento XML è il solo parametro e un altro oggetto che esegue il mapping di un documento XML è il valore restituito. Lo sviluppatore deve scrivere il codice per estrarre o comprimere i parametri o valori restituiti veri e propri.

Generalmente lo sviluppatore deve solo impostare la proprietà ParameterStyle su SoapParameterStyle.Wrapped. L'infrastruttura dei servizi Web inserirà i parametri e valori restituiti nei documenti XML.

Per ulteriori informazioni su su come impostare la proprietà ParameterStyle, vedere Procedura: controllare se i parametri del metodo del servizio Web sono racchiusi in un elemento supplementare..

Impostazione della formattazione SOAP predefinita per un intero servizio Web

Come notato precedentemente in questo argomento, gli attributi SoapDocumentServiceAttribute e SoapRpcServiceAttribute possono essere utilizzati per impostare valori predefiniti per lo stile, l'utilizzo e lo stile del mapping parametro-documento per un'intera classe del servizio Web, ma non per una classe proxy client. Gli attributi SoapDocumentMethod e SoapRpcMethod possono essere utilizzati per eseguire l'override di impostazioni al livello di servizio per ogni metodo del servizio Web.

Per ulteriori informazioni su su come utilizzare gli attributi SoapDocumentService e SoapRpcService, vedere Procedura: modificare la formattazione SOAP predefinita per un intero servizio Web.

Personalizzazione dei messaggi SOAP con la serializzazione XML

Oltre a specificare stile, utilizzo e se inserire un elemento wrapper o meno, è possibile personalizzare direttamente l'XML in un messaggio SOAP con la serializzazione XML. L'infrastruttura dei servizi Web di .NET Framework serializza automaticamente, per impostazione predefinita, campi e proprietà pubblici nei messaggi XML.

Lo spazio dei nomi System.Xml.Serialization include numerosi attributi per la modifica dell'XML. L'esempio di codice seguente mostra come possono essere applicati direttamente a parametri del metodo o valori restituiti del servizio Web alcuni di questi attributi.

[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

Di seguito sono elencati gli attributi utilizzati con maggiore frequenza. I nomi sono visualizzati senza il suffisso Attribute, che può essere omesso:

• XmlElement: specifica che una proprietà o un campo pubblico viene serializzato come elemento XML. Si tratta dell'attributo predefinito per la serializzazione di proprietà e campi pubblici non-matrice. Quando l'attributo XmlElement viene applicato a proprietà e campi pubblici di un attributo di tipo matrice, la matrice viene serializzata con gli altri membri, senza uno speciale elemento padre.

• XmlAttribute: specifica che una proprietà o un campo pubblico viene serializzato come attributo XML dell'elemento che rappresenta il tipo che lo contiene.

• XmlArray: specifica che un campo pubblico di un tipo di matrice viene serializzato con uno speciale elemento padre. Si tratta dell'attributo predefinito per la serializzazione di proprietà e campi pubblici di un tipo di matrice.

• XmlArrayItem: utilizzato in combinazione con l'attributo XmlArray per il controllo degli elementi di matrice.

• XmlIgnore: specifica che la proprietà o il campo pubblico non verrà serializzato

È inoltre possibile utilizzare gli attributi precedenti, ad eccezione di XmlIgnore, per specificare un elemento o un nome di attributo oltre all'impostazione predefinita, ovvero il nome del membro per i membri non-matrice. Si possono utilizzare anche per specificare uno spazio dei nomi per un particolare elemento. Generalmente gli spazi dei nomi non vengono combinati in un servizio Web e devono essere specificati solo al livello della classe utilizzando un attributo come WebService o WebServiceBinding.

Per ulteriori informazioni, vedere , vedere System.Xml.Serialization.

Nota:
Per servizi Web RPC o codificati, con stile RPC con codifica SOAP, l'utilizzo della serializzazione XML è limitato. Parametri e valori restituiti appaiono automaticamente senza qualifica dello spazio dei nomi. Inoltre, le regole di codifica, SOAP 1.1 Sezione 5, combinate con uno stile Document o RPC, proibiscono l'associazione di dati con attributi XML.

Nota:
Se una classe del servizio astratta o la classe proxy client viene generata da un documento WSDL, gli attributi System.Xml.Serialization corretti vengono applicati automaticamente per gli elementi di XML Schema e i tipi definiti nell'elemento types WSDL, sia che siano in linea sia che vengano importati.

Nota:

L'utilizzo di tipi nullable in un servizio Web restituisce WSDL contenente l'impostazione "nillable=true" per il tipo. Quando, tuttavia, tipi nullable vengono utilizzati direttamente come parametri o valori restituiti del metodo Web, l'ammissione di valori null non verrà riflessa nel WSDL restituito nei casi seguenti: 1) quando vengono utilizzati messaggi SOAP basati su RPC e 2) quando vengono utilizzati messaggi SOAP basati su Document con i parametri codificati in modalità Bare.

Per ulteriori informazioni su su come utilizzare l'attributo XmlElement, vedere Procedura: personalizzare il messaggi SOAP con la serializzazione XML.

Vedere anche

Attività

Procedura: controllare la formattazione complessiva del corpo dei messaggi SOAP per un metodo del servizio Web
Procedura: formattazione del parametro di controllo e del valore restituito per un metodo del servizio Web
Procedura: controllare se i parametri del metodo del servizio Web sono racchiusi in un elemento supplementare.
Procedura: modificare la formattazione SOAP predefinita per un intero servizio Web
Procedura: personalizzare il messaggi SOAP con la serializzazione XML

Riferimento

System.Xml.Serialization
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute

Concetti

Modifica di messaggi SOAP utilizzando estensioni SOAP
Compilazione di client dei servizi Web XML

Altre risorse

Introducing XML Serialization