Supporto .NET Framework per i formati SOAP

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 dell'attributo appropriati sono impostati automaticamente.

Senza l'opzione /server, Wsdl.exe produce una classe proxy client che imposta gli attributi di formattazione SOAP pertinenti su valori adatti per comunicare 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 o SoapDocumentService Utilizzo=Literal È l'impostazione predefinita.	Funzionalità supportata.
Codifica – SOAP 1.1 Sezione 5 regole di codifica	SoapDocumentMethod o SoapDocumentService Utilizzo =Codifica	SoapRpcMethod o SoapRpcService

**Nota:**i nomi effettivi degli attributi utilizzano il suffisso Attributo. 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 SoapDocumentMethod a un metodo del servizio Web o a un metodo del proxy client, o applicando l'attributo SoapDocumentService a una classe del servizio Web. Lo stile RPC può essere specificato in modo esplicito applicando l'attributo SoapRpcMethod a un metodo del servizio Web o a un metodo del proxy client, o applicando l'attributo SoapRpcService 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 nella prossima sezione. Giocano un ruolo anche nel determinare se un elemento del "wrapper" viene generato automaticamente al runtime per contenere i parametri o il valore restituito. Vedere l'argomento Procedura: Controllare se i parametri del metodo di servizio Web sono racchiusi in un elemento supplementare..

L'argomento, Procedura: Controllare la formattazione complessiva del corpo dei messaggi SOAP per un metodo del servizio Webfornisce istruzioni sull'applicazione di questi attributi.

Verifica della formattazione del parametro di controllo e del valore restituito

Per un utilizzo che controlla la formattazione dei parametri del metodo del servizio Web o un valore restituito, la scelta predefinita in un servizio Web ASP.NET è letterale, senza codifica SOAP.

La scelta si basa tuttavia anche sullo stile, riguardo alla formattazione del primo e possibilmente secondo livello di contenuto dell'elemento Corpo del testo del messaggio SOAP. Se un metodo di servizio Web, o il metodo della classe proxy corrispondente, utilizza un attributo SoapRpcMethod, la codifica SOAP viene utilizzata automaticamente. .NET Framework supporta la combinazione RPC/letterale. La stessa cosa si verifica se un attributo SoapRpcService viene applicato alla classe del servizio Web e non viene eseguito l'override da parte di un attributo SoapDocumentMethod applicato a un metodo del servizio Web specificato. Gli attributi SoapDocumentMethod e SoapDocumentService, d'altra parte hanno una proprietà Utilizzo i cui valori possibili sono SoapBindingUse.Literal e SoapBindingUse.Encoded.

L'argomento, Procedura: Formattazione del parametro di controllo e del valore restituito per un metodo di servizio Webfornisce istruzioni sull'impostazione della proprietà Use.

Verificare se i parametri sono racchiusi in un elemento supplementare

I parametri o il valore restituito per un metodo del servizio Web possono essere inclusi automaticamente all'interno di un elemento XML padre all'interno dell'elemento Corpo del messaggio SOAP. Lo sviluppatore non deve specificare 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 aggiuntivo viene inserito implicitamente dall'infrastruttura dei servizi Web al runtime, al posto dell'elemento XML padre, o wrapper, specificato nel documento WSDL.

Questa convenzione è chiamata wrapping e può essere specificata impostando le proprietà SoapDocumentMethod.ParameterStyle o SoapDocumentService.ParameterStyle su un valore SoapParameterStyle.Wrapped. Wrapped è anche il valore predefinito.

L'enumerazione SoapParameterStyle ha anche un valore predefinito per specificare lo stile del parametro predefinito a livello della classe del servizio, più un valore Bare per 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 del 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; con Wrapped e Bare, poiché lo stile dell'associazione utilizzato è Document. Tuttavia, la scelta comporta l'associazione tra XML e codice; tra l'XML definito in WSDL e i parametri e valori restituiti dei metodi.

Con la proprietà ParameterStyle impostata su SoapParameterStyle.Bare, lo sviluppatore è in grado di specificare un messaggio che ha più parti, letteralmente elementi XML multipli che sembrano figli dell'elemento Corpo del testo del messaggio SOAP. Tecnicamente, gli elementi multipli 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 deve utilizzare non la firma desiderata 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.

Normalmente, è pertanto sufficiente che uno sviluppatore imposti la proprietà ParameterStyle su SoapParameterStyle.Wrapped e lasci che l'infrastruttura dei servizi Web si occupi di posizionare parametri e valori restituiti in documenti XML.

L'argomento, Procedura: Controllare se i parametri del metodo di servizio Web sono racchiusi in un elemento supplementare.fornisce istruzioni sull'impostazione della proprietà ParameterStyle.

Impostare la 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 stile, utilizzo e stile del mapping parametro-documento per un'intera classe di 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 sulla base del metodo del servizio Web per ogni servizio Web.

L'argomento, Procedura: Modificare la formattazione SOAP predefinita per un intero servizio Webfornisce istruzioni sull'utilizzo degli attributi SoapDocumentService e SoapRpcService.

Personalizzare i 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 serializzazione XML. L'infrastruttura dei servizi Web del .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

Alcuni attributi comunemente usati sono elencati qui di seguito, i nomi appaiono senza il suffisso Attributo che può essere omesso:

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

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

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

• XmlArrayItem: usato in combinazione con l'attributo XmlArray per controllare gli elementi della matrice.

• XmlIgnore: specifica che il campo o la proprietà pubblici non verranno serializzati.

Gli attributi precedenti, a parte XmlIgnore, possono essere utilizzati anche per specificare un elemento o un nome di attributo oltre all'impostazione predefinita, che è 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 informazioni più dettagliate, vedere System.Xml.Serialization.

Nota:
Per servizi Web RPC o codificati, con stile RPC con codifica SOAP, l'utilizzo della serializzazione XML è ristretto. 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 dello schema XML e i tipi definiti sotto l'elemento tipi WSDL, se appaiono in linea o vengono importati.

Nota:

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

L'argomento, Procedura: Personalizzare i messaggi SOAP con la serializzazione XML, fornisce informazioni su come utilizzare l'attributo XmlElement.

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 di servizio Web
Procedura: Controllare se i parametri del metodo di servizio Web sono racchiusi in un elemento supplementare.
Procedura: Modificare la formattazione SOAP predefinita per un intero servizio Web
Procedura: Personalizzare i messaggi SOAP con la serializzazione XML

Riferimenti

System.Xml.Serialization
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute

Concetti

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

Altre risorse

Introducing XML Serialization

Copyright © 2007 Microsoft Corporation. Tutti i diritti riservati.