Share via

Anpassen von SOAP-Meldungen

  • Artikel

Für XML-Webdienste, die mit ASP.NET erstellt wurden, und ihre Clients, die über SOAP mit XML-Webdienstmethoden kommunizieren, steht ein hochentwickelter Mechanismus zur Verfügung, mit dem das Format der an den Server gesendeten und von ihm empfangenen SOAP-Meldung gesteuert wird. SOAP gibt vor, dass der Inhalt der SOAP-Meldung, die von einem XML-Webdienst gesendet und empfangen wird, in XML geschrieben werden muss. Hinsichtlich der Formatierung der XML werden jedoch keine strengen Vorgaben gemacht. Für die Zusammenarbeit mit XML-Webdiensten, die eine andere Formatierung erwarten, stellt ASP.NET einen attributbasierten Mechanismus zur Verfügung, der das Format von XML in der SOAP-Meldung steuert. Um die SOAP-Meldung in ihren Einzelheiten abzustimmen, ist zusätzlich ein attributbasierter Mechanismus verfügbar, mit dem die spezifischen Element- und Attributnamen der im Netzwerk übertragenen SOAP-Meldung festgelegt werden.

Die Kommunikation zwischen XML-Webdiensten und ihren Clients wird vornehmlich durch zwei Industriestandards bestimmt: SOAP und WSDL (Web Services Description Language). SOAP definiert ein Formatierungsschema für die Daten, die unterhalb des Body-Elements angezeigt werden, sowie ein Formatierungsschema für die Formatierung der Parameter innerhalb dieses Body-Elements. Das erste Schema ist unter SOAP, Abschnitt 7, oder einfach RPC geläufig. Ausführliche Informationen zur SOAP-Spezifikation finden Sie auf der W3C-Website unter http://www.w3.org/TR/SOAP (nur auf Englisch verfügbar). Das zweite Schema ist unter SOAP, Abschnitt 5, oder einfach Encoded geläufig. Über die Sprache WSDL zur Beschreibung von SOAP-Meldungen, die von einem XML-Webdienst erwartet werden, können XML-Webdienste festlegen, dass sie RPC-Meldungen mit codierten Parametern akzeptieren. Diese Sprache definiert jedoch noch zwei weitere Begriffe: Literal und Document. Literal bezieht sich wie Encoded auf die Formatierungsweise der Parameter. Document bezieht sich wie RPC auf die Formatierungsweise des gesamten Body-Elements.

Anpassen der von einem XML-Webdienstclient gesendeten SOAP-Meldung

In der folgenden Tabelle sind die Formatierungsstile, die von den mit ASP.NET erstellten XML-Webdiensten unterstützt werden, sowie die Attribute zur Bildung der spezifischen Kombinationen aufgeführt. Die Attribute mit einem Service-Suffix können auf eine Klasse angewendet werden, durch die ein XML-Webdienst implementiert wird, um innerhalb der Klasse den Standardformatierungsstil für XML-Webdienstmethoden festzulegen. Die Attribute mit einem Method-Suffix können nur auf eine XML-Webdienstmethode oder auf eine Methode in einer Proxyklasse angewendet werden, durch die eine XML-Webdienstmethode aufgerufen wird. Die Details der einzelnen Kombinationen werden in den folgenden Abschnitten behandelt.

    Formatierung des gesamten SOAP-Elements "Body"
Parameterformatierung Dokumentbasierte SOAP-Meldungen RPC-basierte SOAP-Meldungen gemäß SOAP, Abschnitt 7
Literal – basiert auf einem XSD-Schema für die einzelnen Parameter SoapDocumentMethod oder SoapDocumentService

Use=Literal

Dies ist die Standardeinstellung.

 Wird nicht unterstützt.
Encoded – SOAP, Abschnitt 5, Codierungsregeln SoapDocumentMethod oder SoapDocumentService

Use=Encoded

SoapRpcMethod oder SoapRpcService

Ändern der Parameterformatierung

Als eine der ersten Fragen beim Entwerfen eines XML-Webdienstes muss entschieden werden, wie die XML innerhalb der SOAP-Anforderung codiert werden soll. Konkret muss entschieden werden, ob das XML-Dokument einem strengen XSD-Schema oder den Formatierungsregeln in der SOAP-Spezifikation, Abschnitte 5 und 7, folgen soll. Die Formatierungsregeln der SOAP-Spezifikation, Abschnitte 5 und 7, lassen auch Variationsmöglichkeiten zu. Ein Empfänger einer SOAP-Anforderung, die die SOAP-Codierungsregeln verwendet, muss folglich alle möglichen Variationen verarbeiten können. Durch die Definition eines XSD-Schemas für die XML-Webdienstmethode kann genau festgelegt werden, welche Informationen in einer SOAP-Anforderung gesendet werden müssen. Das Standardverfahren für XML-Webdienste, die mit ASP.NET erstellt wurden, ist die Übermittlung von Dokumenten auf der Grundlage von Schemas.

Da die Parameter für eine XML-Webdienstmethode den größten Teil der Daten ausmachen können, die in einer SOAP-Anforderung oder -Antwort übermittelt werden, wird durch die Zuordnung der Parameter zu XML-Elementen das Erscheinungsbild des XML-Dokuments festgelegt. In der Web Services Description Language (WSDL) sind zwei Formatierungsstile für Parameter definiert: Encoded und Literal. Encoded bezieht sich auf die Formatierung der Parameter gemäß der SOAP-Codierung in der SOAP-Spezifikation, Abschnitt 5. Literal bezieht sich auf die Zuordnung der Parameter zu XML-Elementen, bei der für jeden Parameter ein vordefiniertes XSD-Schema verwendet wird.

Mit einem XML-Webdienstclient können Sie auswählen, wie die Parameter den XML-Elementen zugeordnet werden, damit die Anforderungen des XML-Webdienstes an die erwartete Meldung erfüllt werden. XML-Webdienste unterstützen sowohl den Parameterformatierungsstil Literal als auch Encoded. Die unterstützten Stile können variieren, je nachdem, welche Formatierung für die XML-Webdienstmethode ausgewählt wurde. Weitere Informationen finden Sie unter Formatierung des gesamten SOAP-Elements Body.

Obwohl ASP.NET eine umfassende Architektur bietet, um die Formatierung der XML zu steuern, ist die Serialisierungsreihenfolge der Parameter nicht immer genau vorhersehbar.

So legen Sie die den Parameterformatierungsstil "Literal" fest

  • Wenden Sie ein SoapDocumentMethod-Attribut auf eine Methode in der Proxyklasse an, indem Sie die Use-Eigenschaft auf SoapBindingUse.Literal setzen.

    In der SoapBindingUse-Enumeration werden die Parameterformatierungsstile festgelegt, die für einen mit ASP.NET erstellten XML-Webdienst verfügbar sind.

    [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

    Im Folgenden sehen Sie den XML-Bereich der an die XML-Webdienstmethode DocumentLiteral gerichteten SOAP-Anforderung. Die Parameter befinden sich im Body-Element und werden als unabhängige XML-Dokumente codiert, da sie sich auf ein XSD-Schema beziehen.

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

So legen Sie die den Parameterformatierungsstil "Encoded" fest

  • Wenden Sie ein SoapDocumentMethod-Attribut oder ein SoapRpcMethod-Attribut auf die Methode in der Proxyklasse an, indem Sie die Use-Eigenschaft auf SoapBindingUse.Encoded setzen.

    Im Unterschied zum Parameterformatierungsstil Literal kann der Parameterformatierungsstil Encoded zusammen mit beiden Formatierungsstilen für XML-Webdienstmethoden verwendet werden. Ausführliche Informationen zu Formatierungsstilen für XML-Webdienstmethoden finden Sie unter Formatierung des gesamten SOAP-Elements Body.

    [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

    Im Folgenden sehen Sie den XML-Bereich der an die Dienstmethode DocumentEncoded gerichteten SOAP-Anforderung. Beachten Sie, dass die Darstellung der Parameter deutlich von der Darstellung im Formatierungsstil Literal abweicht, da sie anhand der Codierungsregeln in Abschnitt 5 der SOAP-Spezifikation formatiert wurden. Besondere Beachtung verdient der address-Parameter, der keinen einfachen Datentyp darstellt.

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

Formatierung des gesamten SOAP-Elements "Body"

WSDL enthält zwei Stildefinitionen dafür, wie eine XML-Webdienstmethode, die als Operation bezeichnet wird, innerhalb des Body-Elements einer SOAP-Anforderung oder einer SOAP-Antwort formatiert werden kann: RPC und Document. In ASP.NET wird sowohl der Formatierungsstil Document als auch der Formatierungsstil RPC unterstützt. Document wird standardmäßig verwendet.

Der RPC-Stil bezieht sich auf die Formatierung des Body-Elements gemäß den Richtlinien, die in der SOAP-Spezifikation für die RPC-Formatierung mittels SOAP festgelegt sind. Diese Richtlinien sind auch als Abschnitt 7 der SOAP-Spezifikation bekannt. Dieser Stil legt fest, dass alle Parameter in einem einzelnen Element, das nach der XML-Webdienstmethode benannt wird, eingeschlossen werden und dass jedes Element innerhalb dieses Elements einen Parameter darstellt, der nach dem zugehörigen Parameternamen benannt ist. Dieser Stil beschreibt außerdem die Regeln für die Formatierung von SOAP-Antworten.

Der Document-Stil bezieht sich auf die Formatierung des Body-Elements als eine Reihe von einem oder mehreren Meldungsteilen, die dem Body-Element untergeordnet sind. Wie die einzelnen Meldungsteile genau aussehen, wird durch die Eigenschaften Use und ParameterStyle des SoapDocumentMethod-Attributs bestimmt. Durch die Use-Eigenschaft wird festgelegt, ob Parameter mit dem Stil Encoded oder Literal formatiert werden. Durch ParameterStyle wird festgelegt, ob die Parameter in einem einzelnen Meldungsteil unterhalb des Body-Elements eingeschlossen sind oder ob jeder Parameter einen separaten Meldungsteil darstellt. Ausführliche Informationen zum Festlegen der ParameterStyle-Eigenschaft finden Sie unter Anpassen, ob die Parameter in einem XML-Element eingeschlossen werden.

So legen Sie den Formatierungsstil "Document" fest

  • Wenden Sie ein SoapDocumentMethod-Attribut auf die Methode in der Proxyklasse an, durch die die zugehörige XML-Webdienstmethode aufgerufen wird.

    Bei Verwendung des Formatierungsstils Document unterstützen die mit ASP.NET erstellten XML-Webdienste sowohl den Parameterformatierungsstil Literal als auch den Parameterformatierungsstil Encoded. Im folgenden Beispiel wird der Methodenformatierungsstil Document mit dem Parameterformatierungsstil Literal kombiniert.

    [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

    Wie beim Formatierungsstil Document erwartet, wird innerhalb der Dienstbeschreibung ein XSD-Schema definiert, das sowohl für die SOAP-Anforderung als auch für die SOAP-Antwort gilt. Das folgende Beispiel ist ein Auszug aus der Dienstbeschreibung der SOAP-Anforderung für die XML-Webdienstmethode DocumentWrappedLiteral. Da es sich beim ersten Parameter für die XML-Webdienstmethode DocumentWrappedLiteral um eine Klasse handelt und der Parameterformatierungsstil Literal festgelegt wurde, wird ein XSD-Schema für den address-Typ erstellt.

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

    Da das XSD-Schema in der Dienstbeschreibung definiert ist, folgt der XML-Bereich der an die Dienstmethode DocumentWrappedLiteral gerichteten SOAP-Anforderung. Beachten Sie, dass die XML-Elemente unterhalb des Body-Elements in der SOAP-Anforderung mit den im XSD-Schema definierten Elementen übereinstimmen.

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

So legen Sie den Formatierungsstil "RPC" fest

  • Wenden Sie ein SoapRpcMethod-Attribut auf die Methode in der Proxyklasse an, durch die die zugehörige XML-Webdienstmethode aufgerufen wird.

    Bei Verwendung des Formatierungsstils RPC unterstützt ASP.NET nur den Parameterformatierungsstil Encoded. Deshalb wurde im folgenden Codebeispiel keine Use-Eigenschaft für die Parameterformatierung angegeben, da das SoapRpcMethod-Attribut keine Use-Eigenschaft enthält.

    [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

    Weder für die SOAP-Anforderung noch für die SOAP-Antwort auf die Rpc-Methode wurde im vorherigen Beispiel ein strenges XSD-Schema in der Dienstbeschreibung definiert. Es wurden lediglich Teile festgelegt, in denen sie enthalten sind. Betrachten Sie daher die SOAP-Anforderung für die Rpc-Methode. Sie werden sehen, dass die Parameter in einem Element eingeschlossen und mit der Parameterformatierung Encoded codiert sind.

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

Anpassen, ob die Parameter in einem XML-Element eingeschlossen werden

Die Parameter für eine XML-Webdienstmethode können in einem XML-Element eingeschlossen werden, wenn sie XML-Elementen im Body-Element der SOAP-Meldung zugeordnet sind. Wie Sie bereits gesehen haben, werden die Parameter von RPC stets in einem Element eingeschlossen. Bei Verwendung des Formatierungsstils Document können Sie dies jedoch ändern. In der Dienstbeschreibung werden die Parameter den Teilen der SOAP-Meldung zugeordnet, den so genannten Meldungsteilen. Wenn die Parameter in einem XML-Element eingeschlossen sind, werden sie einem einzelnen Meldungsteil zugeordnet. Andernfalls können die Parameter mehrere Meldungsteile umfassen.

So legen Sie fest, dass Parameter in einem XML-Element eingeschlossen sind

  • Wenden Sie ein SoapDocumentMethod-Attribut auf die Methode in der Proxyklasse an, durch die die zugehörige XML-Webdienstmethode aufgerufen wird, indem Sie die ParameterStyle-Eigenschaft auf Wrapped setzen.

    Im folgenden Codebeispiel wird der ParameterStyle auf Wrapped festgelegt. Darüber hinaus wird der Parameterformatierungsstil Literal festgelegt.

    [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

    Die Parameter sind im XML-Bereich der SOAP-Anforderung in einem Element eingeschlossen, das standardmäßig nach der XML-Webdienstmethode benannt ist.

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

    Im XML-Bereich der SOAP-Antwort sind die Ausgabeparameter für die XML-Webdienstmethode, einschließlich der in einem Element befindlichen Ergebnisse, eingeschlossen. Der Name des einschließenden Elements entspricht standardmäßig dem Namen der XML-Webdienstmethode mit dem angefügten Suffix 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>

So legen Sie fest, dass Parameter direkt auf das Body-Element folgen

  • Wenden Sie ein SoapDocumentMethod-Attribut auf die Methode in der Proxyklasse an, durch die die zugehörige XML-Webdienstmethode aufgerufen wird, indem Sie die ParameterStyle-Eigenschaft auf Bare setzen.

    Im folgenden, von Wsdl.exe generierten Beispiel wurde ParameterStyle auf Bare gesetzt und als Parameterformatierungsstil Literal ausgewählt. Da der Namespace in einem Element, das alle Parameter einschließt, nicht angegeben werden kann, muss er für jeden Parameter und Rückgabewert separat festgelegt werden. Sie erreichen dies, indem Sie auf jeden Parameter und auf den Rückgabewert ein XmlElementAttribute anwenden und die Namespace-Eigenschaft festlegen.

    [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

    Die XML-Elemente, denen die Parameter innerhalb der SOAP-Anforderung zugeordnet sind, folgen direkt auf das Body-Element, wobei jeweils ein Namespace angegeben ist.

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

    Die Ausgabeparameter werden, einschließlich des Rückgabewerts, XML-Elementen zugeordnet, die innerhalb der SOAP-Antwort auf das Body-Element folgen. Der Elementname des Rückgabewerts entspricht standardmäßig dem Namen der XML-Webdienstmethode mit dem angefügten Suffix 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>

Anpassen der von einer XML-Webdienstmethode erwarteten SOAP-Meldungen

Wenn Sie die SOAP-Meldung ändern müssen, die von einem mit ASP.NET erstellten XML-Webdienst erwartet wird, stehen für den mit ASP.NET erstellten XML-Webdienst dieselben Mechanismen zur Verfügung wie für den mit ASP.NET erstellten XML-Webdienstclient. Sie können die Zuordnung von Parametern zu XML-Elementen steuern, sowie das XML-Element, das die XML-Webdienstmethode darstellt, und ob die zugeordneten Elemente in einem Element gekapselt werden. Methodenweise können dieselben Attribute verwendet werden, und zwar die Attribute SoapDocumentMethod und SoapRpcMethod. Zusätzlich können Sie die Standardformatierungseinstellungen auf XML-Webdienstebene festlegen, indem Sie die entsprechenden Attribute SoapDocumentService und SoapRpcService auf den XML-Webdienst anwenden. Wenn Sie ein SoapDocumentService-Attribut auf einen XML-Webdienst anwenden, wird der standardmäßige Methodenformatierungsstil für dessen XML-Webdienstmethoden auf Document festgelegt. Entsprechend wird durch das SoapRpcService-Attribut standardmäßig RPC festgelegt.

So legen Sie den standardmäßigen Methodenformatierungsstil für einen XML-Webdienst fest

  • Wenden Sie entweder ein SoapRpcService-Attribut oder ein SoapDocumentService-Attribut auf die Klasse an, durch die der XML-Webdienst implementiert wird.

    Im folgenden Codebeispiel wird der Methodenformatierungsstil auf Document und die standardmäßige Parameterformatierung auf Literal festgelegt. Außerdem wird angegeben, dass die Parameter in einem einzelnen Element gekapselt sein müssen.

    <%@ 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

    Im Folgenden sehen Sie den XML-Bereich der SOAP-Anforderung, die von der XML-Webdienstmethode UseDefaultEncoding erwartet wird.

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

Anpassen der SOAP-Meldung mit XML-Serialisierung

Sie können nicht nur die Parameterformatierung und den Formatierungsstil für die XML-Webdienstmethode angeben und festlegen, ob die Parameter in einem Element eingeschlossen werden, sondern die SOAP-Meldung auch direkt mit der XML-Serialisierung anpassen. Dies wurde teilweise bereits durch das XmlElement-Attribut veranschaulicht, der System.Xml.Serialization-Namespace enthält jedoch zahlreiche Attribute für die Bearbeitung von XML. Wenn die SOAP-Meldung die von einem XML-Webdienst empfangenen und gesendeten Daten mit XML codiert, sind die Attribute im System.Xml.Serialization-Namespace der ideale Weg, um die vom XML-Webdienst empfangene und gesendete SOAP-Meldung anzupassen. Ausführliche Informationen erhalten Sie unter System.Xml.Serialization.

So geben Sie den Namen des XML-Elements an, das einen Parameter darstellt

  • Wenden Sie ein XmlElement-Attribut auf den Parameter an, indem Sie den gewünschten Elementnamen und bei Bedarf einen Namespace angeben, falls für die Parameterformatierung Literal festgelegt wurde. Wenn für die Parameterformatierung Encoded festgelegt wurde, wenden Sie ein SoapElement-Attribut auf den Parameter an.

    Im folgenden Codebeispiel wird erwartet, dass die Elementnamen, die die Parameter darstellen, MyAddressElement, MyZipElement und ReturnValueElement lauten. Außerdem wird erwartet, dass der Elementname, der den Rückgabewert darstellt, ReturnValueElement lautet. Die XML-Webdienstmethode im Beispiel hat den Formatierungsstil Document, was der Standardeinstellung in ASP.NET entspricht.

    <%@ 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

    Der XML-Webdienst erwartet die folgende SOAP-Anforderung. Anders als bei Parameternamen ist darauf zu achten, dass die Namen der Elemente mit den Angaben im XmlElement-Attribut übereinstimmen.

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

Siehe auch

Einführung in die XML-Serialisierung | System.Xml.Serialization-Namespace | Ändern der SOAP-Meldung mit SOAP-Erweiterungen | SoapDocumentMethodAttribute | SoapRpcMethodAttribute | SoapDocumentServiceAttribute | SoapRpcServiceAttribute | Erstellen von XML-Webdiensten mit ASP.NET | Erstellen von XML-Webdienstclients