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

Statt manuell ein WSDL-Dokument 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 automatisch geeignete Attributwerte festgelegt werden.

Ohne die Option /server erstellt 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.

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 angegeben werden, indem das SoapDocumentMethod-Attribut auf eine Webdienstmethode oder eine Clientproxymethode bzw. das SoapDocumentService-Attribut auf eine Webdienstklasse angewendet wird. Der RPC-Stil kann explizit angegeben werden, indem das SoapRpcMethod-Attribut auf eine Webdienstmethode oder eine Clientproxymethode bzw. das SoapRpcService-Attribut auf eine Webdienstklasse angewendet wird. Bei Diensten setzen Attribute auf Methodenebene Attribute auf Klassenebene außer Kraft.

Wie unter der nächsten Überschrift 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 Gewusst wie: Steuern, ob Webdienst-Methodenparameter in ein zusätzliches Element eingeschlossen werden.

Nähere Informationen zur Anwendung dieser Attribute finden Sie unter Gewusst wie: 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 standardmäßig literal und nicht die SOAP-Codierung gewählt.

Die Auswahl hängt jedoch auch vom gewählten Stil ab, was die Formatierung des Inhalts der ersten und möglicherweise zweiten Ebene des SOAP-Elements Body angeht. Wenn in einer Webdienstmethode oder der entsprechenden Proxyklassenmethode das SoapRpcMethod-Attribut verwendet wird, wird automatisch die SOAP-Codierung verwendet. Die Kombination von RPC und literal wird von .NET Framework unterstützt. Dasselbe gilt, wenn das SoapRpcService-Attribut auf die Webdienstklasse angewendet und nicht durch ein auf eine gegebene Webdienstmethode angewendetes SoapDocumentMethod-Attribut außer Kraft gesetzt wird. Die Attribute SoapDocumentMethod und SoapDocumentService verfügen andererseits über die Use-Eigenschaft mit den möglichen Werten SoapBindingUse.Literal und SoapBindingUse.Encoded.

Das Thema Gewusst wie: Steuern der Formatierung der Parameter und Rückgabewerte für eine Webdienstmethode enthält Anweisungen zum Festlegen der Use-Eigenschaft.

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 Webdienstinfrastruktur implizit eingefügt.

Diese Konvention wird als Wrapping bezeichnet und kann angegeben werden, indem die SoapDocumentMethod.ParameterStyle-Eigenschaft oder die SoapDocumentService.ParameterStyle-Eigenschaft auf den Wert SoapParameterStyle.Wrapped festgelegt wird. Wrapped ist auch 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 verpacken.

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

Das Thema Gewusst wie: Steuern, ob Webdienst-Methodenparameter in ein zusätzliches Element eingeschlossen werden enthält Anweisungen zum Festlegen der ParameterStyle-Eigenschaft.

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. Mithilfe der Attribute SoapDocumentMethod und SoapRpcMethod können für einzelne Webdienstmethoden Einstellungen auf Dienstebene außer Kraft gesetzt werden.

Das Thema Gewusst wie: Ändern der SOAP-Standardformatierung für einen ganzen Webdienst enthält Anweisungen zur Verwendung der Attribute SoapDocumentService und SoapRpcService.

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 Webdienstinfrastruktur 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 soll.

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 Nicht-Arraymember, 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 System.Xml.Serialization.

Hinweis:
Für RPC-Webdienste oder codierte Webdienste mit RPC-Stil 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 für 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. 2) Dokumentenbasierte SOAP-Nachrichten werden mit codierten Parametern im bare-Modus verwendet

Das Thema Gewusst wie: Anpassen von SOAP-Nachrichten mit der XML-Serialisierung enthält Anweisungen zur Verwendung des XmlElement-Attributs.

Siehe auch

Aufgaben

Gewusst wie: Steuern der allgemeinen SOAP-Textformatierung für eine Webdienstmethode
Gewusst wie: Steuern der Formatierung der Parameter und Rückgabewerte für eine Webdienstmethode
Gewusst wie: Steuern, ob Webdienst-Methodenparameter in ein zusätzliches Element eingeschlossen werden
Gewusst wie: Ändern der SOAP-Standardformatierung für einen ganzen Webdienst
Gewusst wie: Anpassen von SOAP-Nachrichten mit der XML-Serialisierung

Referenz

System.Xml.Serialization
SoapDocumentMethodAttribute
SoapRpcMethodAttribute
SoapDocumentServiceAttribute
SoapRpcServiceAttribute

Konzepte

SOAP-Nachrichtenänderung mit SOAP-Erweiterungen
Erstellen von XML-Webdienstclients

Weitere Ressourcen

Introducing XML Serialization

Copyright © 2007 by Microsoft Corporation. Alle Rechte vorbehalten.