.NET Framework-Unterstützung für SOAP-Formate

Artikel
02/27/2011

Dieses Thema bezieht sich auf eine veraltete Technologie. XML-Webdienste und XML-Webdienstclients sollten nun mithilfe der folgenden Technologie erstellt werden: Windows Communication Foundation.

Statt ein WSDL-Dokument manuell zu erstellen, können Entwickler beim Erstellen eines Webdiensts für ASP.NET diese SOAP-Formate angeben, indem sie Attribute auf einzelne Webdienstmethoden oder auf gesamte Webdienstklassen anwenden. Wenn diese Attribute nicht angegeben werden, werden die SOAP-Standardformate verwendet.

Wenn Sie einen auf einem vorhandenen WSDL-Dokument basierenden Webdienst entwickeln, können Sie das Tool Wsdl.exe mit der Option /server ausführen, um eine abstrakte Webdienstklasse zu generieren, für die geeignete Attributwerte automatisch festgelegt werden.

Ohne die Option /server erzeugt Wsdl.exe eine Clientproxyklasse, die die relevanten SOAP-Formatierungsattribute auf die geeigneten Werte für die Kommunikation mit dem Webdienst festlegt, der im WSDL-Eingabedokument beschrieben wird. Clientproxyklassen verwenden größtenteils die gleichen Attribute, die auf dem Server angegeben werden können. Normalerweise müssen Entwickler diese Attribute in der Clientproxyklasse nicht manuell hinzufügen oder bearbeiten, da der Client von Wsdl.exe generiert wird, um sicherzustellen, dass er dem im WSDL-Dokument beschriebenen Dienstvertrag entspricht.

In der folgenden Tabelle sind die Formatierungsoptionen, die von den mit ASP.NET erstellten Webdiensten und Clients unterstützt werden, sowie die Attribute zur Bildung der jeweiligen Kombination aufgeführt. Die Attribute mit dem Suffix Service können auf eine Klasse angewendet werden, durch die ein Webdienst (keine Clientproxyklasse) implementiert wird, um innerhalb der Klasse den Standardformatierungsstil für Webdienstmethoden festzulegen. Die Attribute mit dem Suffix Method können entweder auf eine Webdienstmethode oder eine Methode einer Clientproxyklasse, die eine Webdienstmethode aufruft, angewendet werden. Nähere Informationen zu den einzelnen Kombinationen enthalten die folgenden Absätze.

Parameterformatierung (use)	SOAP-Textformatierung (style) für dokumentbasierte SOAP-Nachrichten	SOAP-Textformatierung (style) für RPC-basierte SOAP-Nachrichten gemäß SOAP 1.1, Abschnitt 7s
Literal – basiert auf einem XSD-Schema für jeden Parameter	SoapDocumentMethod oder SoapDocumentService Use=Literal Dies ist die Standardeinstellung.	SoapRpcMethod oder SoapRpcService Use=Literal
Encoded – Codierungsregeln gemäß SOAP 1.1, Abschnitt 5	SoapDocumentMethod oder SoapDocumentService Use=Encoded	SoapRpcMethod oder SoapRpcService Use=Encoded Dies ist die Standardeinstellung.

Literal – basiert auf einem XSD-Schema für jeden Parameter

SoapDocumentMethod oder SoapDocumentService

Use=Literal

Dies ist die Standardeinstellung.

SoapRpcMethod oder SoapRpcService

Use=Literal

Encoded – Codierungsregeln gemäß SOAP 1.1, Abschnitt 5

SoapDocumentMethod oder SoapDocumentService

Use=Encoded

SoapRpcMethod oder SoapRpcService

Use=Encoded

Dies ist die Standardeinstellung.

Hinweis:
Für die tatsächlichen Attributnamen wird das Attribute-Suffix verwendet. Im Quellcode können die Namen wie in der vorangehenden Tabelle gezeigt abgekürzt werden.

Steuern der gesamten SOAP-Formatierung

Für einen Stil, der steuert, ob das Laufzeitmodul des Webdiensts die RPC-Konventionen anwendet oder sich nach XML-Dokumenten richtet, wird in einem ASP.NET-Webdienst standardmäßig document, nicht RPC gewählt.

Der Dokumentstil kann explizit festgelegt werden, indem das SoapDocumentMethodAttribute-Attribut auf eine Webdienstmethode oder eine Clientproxymethode angewendet wird oder indem das SoapDocumentServiceAttribute-Attribut auf eine Webdienstklasse angewendet wird. Das RPC-Format kann explizit festgelegt werden, indem das SoapRpcMethodAttribute****-Attribut auf eine Webdienstmethode oder Clientproxymethode angewendet wird oder indem das SoapRpcServiceAttribute-Attribut auf eine Webdienstklasse angewendet wird. Bei Diensten setzen Attribute auf Methodenebene Attribute auf Klassenebene außer Kraft.

Wie weiter unten beschrieben, spielen die gleichen Attribute eine Rolle beim Festlegen der Formatierung für Parameter und Rückgabewerte. Außerdem wirken sie sich darauf aus, ob ein Wrapperelement, das die Parameter oder den Rückgabewert enthält, automatisch zur Laufzeit generiert wird. Weitere Informationen finden Sie unter Vorgehensweise: Steuern, ob Webdienst-Methodenparameter in ein zusätzliches Element eingeschlossen werden.

Weitere Informationen über über die Anwendung dieser Attribute finden Sie unter Vorgehensweise: Steuern der allgemeinen SOAP-Textformatierung für eine Webdienstmethode.

Steuern der Formatierung von Parametern und Rückgabewerten

Für die Option use, mit der die Formatierung der Webdienst-Methodenparameter oder Rückgabewerte gesteuert wird, wird in einem ASP.NET-Webdienst mit Dokumentstil standardmäßig literal gewählt. Die Standardauswahl in einem ASP.NET-Webdienst mit RPC-Format ist encoded. Sie können den use-Wert ändern, indem Sie die Use-Eigenschaft der entsprechenden Attribute SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute oder SoapRpcServiceAttribute entweder auf SoapBindingUse.Literal oder SoapBindingUse.Encoded festlegen.

Weitere Informationen über über das Festlegen der Use-Eigenschaft finden Sie unter Vorgehensweise: Steuern der Formatierung der Parameter und Rückgabewerte für eine Webdienstmethode.

Steuern, ob Parameter in ein zusätzliches XML-Element eingeschlossen werden

Die Parameter oder Rückgabewerte einer Webdienstmethode können automatisch in ein übergeordnetes XML-Element innerhalb des Body-Elements der SOAP-Nachricht eingeschlossen werden. Der Entwickler muss das übergeordnete Element nicht angeben. Wie Sie gesehen haben, ist der RPC-Formatierungsstil hierfür zuständig. Es ist aber auch bei Verwendung des Dokumentformatierungsstils möglich. Das übergeordnete XML-Element bzw. der Wrapper wird hierbei nicht im WSDL-Dokument angegeben, sondern das zusätzliche Element wird zur Laufzeit von der Webdiensteinfrastruktur implizit eingefügt.

Diese Konvention wird als Wrapping bezeichnet und kann festgelegt werden, indem für die SoapDocumentMethod.ParameterStyle-Eigenschaft oder SoapDocumentService.ParameterStyle-Eigenschaft der Wert SoapParameterStyle.Wrapped festgelegt wird. Wrapped ist darüber hinaus der Standardwert.

Die SoapParameterStyle-Enumeration enthält zudem den Wert Default zur Festlegung des Standardparameterstils auf Dienstklassenebene sowie den Wert Bare, mit dem der Wrapping-Mechanismus deaktiviert und die XML-Elemente, die im WSDL-Dokument als Nachrichtenteile angegeben sind, wörtlich in Methodenparameter und Rückgabewerte übersetzt werden. Beim Bare-Parameterstil entspricht jeder Parameter oder Rückgabewert einem angegebenen Nachrichtenteil.

Ob der Wrapping-Mechanismus zum Einsatz kommt, wird nicht im WSDL-Dokument festgelegt. Sowohl bei Angabe von Wrapped als auch bei Angabe von Bare wird als Bindungsstil document verwendet. Diese Entscheidung wird durch die Bindung zwischen XML und Quellcode bestimmt, zwischen den im WSDL-Dokument definierten XML-Elementen und den Parametern und Rückgabewerten der Methoden.

Wenn die ParameterStyle-Eigenschaft auf SoapParameterStyle.Bare festgelegt ist, kann der Entwickler eine aus mehreren Teilen bestehende Nachricht angeben, also buchstäblich mehrere XML-Elemente, die als untergeordnete Elemente des SOAP-Body-Elements angezeigt werden. Technisch gesehen bilden mehrere Elemente kein XML-Dokument, da ein Dokument über ein einzelnes Stammelement verfügen muss. Daher wird von der Webdienstecommunity empfohlen, für Dienste im Dokumentstil einen einzigen Nachrichtenteil zu verwenden. Jede Webdienstmethode muss statt der vorgesehenen Signatur eine Signatur verwenden, die als einzigen Parameter eine Objektzuordnung zu einem XML-Dokument und als Rückgabewert eine weitere Objektzuordnung zu einem XML-Dokument enthält. Der Entwickler muss Code schreiben, um die tatsächlichen Parameter oder Rückgabewerte zu extrahieren oder zu packen.

Daher reicht es normalerweise aus, wenn der Entwickler die ParameterStyle-Eigenschaft auf SoapParameterStyle.Wrapped festlegt und es der Webdiensteinfrastruktur überlässt, die Parameter und Rückgabewerte in XML-Dokumente einzufügen.

Weitere Informationen über über das Festlegen der ParameterStyle-Eigenschaft finden Sie unter Vorgehensweise: Steuern, ob Webdienst-Methodenparameter in ein zusätzliches Element eingeschlossen werden.

Festlegen der SOAP-Standardformatierung für einen gesamten Webdienst

Wie weiter oben in diesem Thema angemerkt, können mithilfe der Attribute SoapDocumentServiceAttribute und SoapRpcServiceAttribute Standardwerte für die Zuordnungsstile style, use und parameter-to-document für eine gesamte Webdienstklasse, nicht jedoch für eine Clientproxyklasse festgelegt werden. Mit dem SoapDocumentMethod-Attribut und dem SoapRpcMethod-Attribut können die Einstellungen auf Dienstebene für die einzelnen Webdienstmethoden überschrieben werden.

Weitere Informationen über über die Verwendung des SoapDocumentService-Attributs und des SoapRpcService-Attributs finden Sie unter Vorgehensweise: Ändern der SOAP-Standardformatierung für einen ganzen Webdienst.

Anpassen von SOAP-Nachrichten mit der XML-Serialisierung

Sie können nicht nur style und use verwenden und angeben, ob ein Wrapperelement eingefügt werden soll, sondern den in einer SOAP-Nachricht enthaltenen XML-Code auch direkt über die XML-Serialisierung anpassen. Standardmäßig serialisiert die Webdiensteinfrastruktur von .NET Framework öffentliche Felder und Eigenschaften automatisch in XML-Nachrichten.

Der System.Xml.Serialization-Namespace umfasst zahlreiche Attribute zum Bearbeiten von XML. Im folgenden Codebeispiel wird gezeigt, wie einige dieser Attribute direkt auf Parameter oder Rückgabewerte von Webdienstmethoden angewendet werden können.

[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

Einige häufig verwendete Attribute werden nachfolgend aufgelistet, wobei ihre Namen ohne das Suffix Attribute angegeben werden, das weggelassen werden kann:

XmlElement: Gibt an, dass ein öffentliches Feld oder eine öffentliche Eigenschaft als XML-Element serialisiert wird. Dies ist das Standardattribut für das Serialisieren von öffentlichen Feldern und Eigenschaften, die kein Array sind. Wenn das XmlElement-Attribut auf öffentliche Felder oder Eigenschaften eines Arraytypattributs angewendet wird, dann wird das Array zusammen mit anderen Membern ohne spezielles übergeordnetes Element serialisiert.
XmlAttribute: Gibt an, dass ein öffentliches Feld oder eine öffentliche Eigenschaft als XML-Attribut des Elements serialisiert wird, das den Typ darstellt, in dem das Feld bzw. die Eigenschaft enthalten ist.
XmlArray: Gibt an, dass ein öffentliches Feld eines Arraytyps mit einem besonderen übergeordneten Element serialisiert wird. Dies ist das Standardattribut für das Serialisieren von öffentlichen Feldern und Eigenschaften eines Arraytyps.
XmlArrayItem: Wird in Verbindung mit dem XmlArray-Attribut zum Steuern der Arrayelemente verwendet.
XmlIgnore: Gibt an, dass ein öffentliches Feld oder eine öffentliche Eigenschaft nicht serialisiert werden sollen.

Mit Ausnahme von XmlIgnore können die oben genannten Attribute auch verwendet werden, um einen anderen Element- oder Attributnamen als den Standardnamen, d. h. den Membernamen für Nichtarraymember, anzugeben. Sie können zudem zur Angabe eines Namespace für ein bestimmtes Element verwendet werden. In der Regel werden in einem Webdienst nicht verschiedene Namespaces verwendet. Der Namespace muss nur auf Klassenebene mithilfe eines Attributs wie WebService oder WebServiceBinding angegeben werden.

Weitere Informationen finden Sie unter , siehe System.Xml.Serialization.

Hinweis:
Für RPC-Webdienste oder codierte Webdienste im RPC-Format mit SOAP-Codierung kann die XML-Serialisierung nur eingeschränkt genutzt werden. Parameter und Rückgabewerte werden automatisch ohne Namespacenennung angezeigt. Wenn die Codierung gemäß SOAP 1.1, Abschnitt 5, in Kombination mit dem Dokumentstil oder RPC-Stil verwendet wird, ist es zudem gar nicht möglich, Daten an XML-Attribute zu binden.

Für RPC-Webdienste oder codierte Webdienste im RPC-Format mit SOAP-Codierung kann die XML-Serialisierung nur eingeschränkt genutzt werden. Parameter und Rückgabewerte werden automatisch ohne Namespacenennung angezeigt. Wenn die Codierung gemäß SOAP 1.1, Abschnitt 5, in Kombination mit dem Dokumentstil oder RPC-Stil verwendet wird, ist es zudem gar nicht möglich, Daten an XML-Attribute zu binden.

Hinweis:
Wenn eine abstrakte Dienstklasse oder Clientproxyklasse aus einem WSDL-Dokument generiert wird, werden automatisch die richtigen System.Xml.Serialization-Attribute auf die unter dem WSDL-Element types definierten XML-Schemaelemente und -typen angewendet. Dabei spielt es keine Rolle, ob diese inline angegeben oder importiert werden.

Hinweis:
Die Verwendung von Typen mit Nullwerten in einem Webdienst führt zu einem WSDL-Dokument, das für den Typ die Einstellung "nillable=true" enthält. Wenn Typen mit Nullwerten jedoch direkt als Webmethodenparameter oder Rückgabewerte verwendet werden, gibt das resultierende WSDL-Dokument in folgenden Fällen die Zulässigkeit von Nullwerten nicht wieder: 1) Es werden RPC-basierte SOAP-Nachrichten verwendet, und 2) Dokumentenbasierte SOAP-Nachrichten werden mit codierten Parametern im Bare-Modus verwendet.

Die Verwendung von Typen mit Nullwerten in einem Webdienst führt zu einem WSDL-Dokument, das für den Typ die Einstellung "nillable=true" enthält. Wenn Typen mit Nullwerten jedoch direkt als Webmethodenparameter oder Rückgabewerte verwendet werden, gibt das resultierende WSDL-Dokument in folgenden Fällen die Zulässigkeit von Nullwerten nicht wieder: 1) Es werden RPC-basierte SOAP-Nachrichten verwendet, und 2) Dokumentenbasierte SOAP-Nachrichten werden mit codierten Parametern im Bare-Modus verwendet.

Weitere Informationen über über die Verwendung des XmlElement-Attributs finden Sie unter Vorgehensweise: Anpassen von SOAP-Nachrichten mit der XML-Serialisierung.

Siehe auch

.NET Framework-Unterstützung für SOAP-Formate

Steuern der gesamten SOAP-Formatierung

Steuern der Formatierung von Parametern und Rückgabewerten

Steuern, ob Parameter in ein zusätzliches XML-Element eingeschlossen werden

Festlegen der SOAP-Standardformatierung für einen gesamten Webdienst

Anpassen von SOAP-Nachrichten mit der XML-Serialisierung

Siehe auch

Aufgaben

Verweis

Konzepte

Weitere Ressourcen

Zusätzliche Ressourcen