Erstellen eines XML-Webdienstproxys

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

Mit Webdiensten kann definitionsgemäß unter Verwendung von Standardprotokollen, einschließlich SOAP, über ein Netzwerk kommuniziert werden. Ein Client und ein Webdienst kommunizieren also über SOAP-Nachrichten, in denen Eingabe- und Ausgabeparameter als XML-Elemente gekapselt sind. Bei Webdienstclients ist die Proxyklasse dafür zuständig, Parameter den XML-Elementen zuzuordnen und die SOAP-Nachricht dann über das Netzwerk zu senden.

Sofern eine Dienstbeschreibung vorhanden ist, die in WSDL (Web Services Description Language) geschrieben wurde, kann eine Proxyklasse erstellt werden. In der Dienstbeschreibung wird definiert, wie mit einem Webdienst kommuniziert werden muss. Bei Vorhandensein einer Dienstbeschreibung kann mit dem Tool Wsdl.exe eine Proxyklasse erstellt werden. Ein Webdienstclient kann anschließend Methoden der Proxyklasse aufrufen, die für die Kommunikation mit einem Webdienst über das Netzwerk die SOAP-Nachrichten verarbeiten, die vom Webdienst empfangen und gesendet werden. Da die Proxyklasse über das Internet mit dem Webdienst kommuniziert, sollte überprüft werden, ob die Url-Eigenschaft der Proxyklasse auf ein vertrauenswürdiges Ziel verweist.

Standardmäßig verwendet die Proxyklasse SOAP über HTTP, um mit dem Webdienst zu kommunizieren. Wsdl.exe kann aber auch Proxyklassen erstellen, mit denen die Kommunikation mit einem Webdienst unter Verwendung des HTTP-GET-Protokolls oder HTTP-POST-Protokolls erfolgen kann. Um anzugeben, dass die Proxyklasse HTTP-GET oder HTTP-POST verwenden soll, legen Sie für das Tool Wsdl.exe den /protocol-Schalter wie in der folgenden Tabelle beschrieben fest.

Verwenden von Wsdl.exe zum Generieren einer Proxyklasse für einen XML-Webdienst

Sie können mit dem WSDL-Tool (Wsdl.exe) eine Proxyklasse erstellen, indem Sie das Tool an einer Eingabeaufforderung ausführen und (mindestens) die URL für einen Webdienst oder eine Dienstbeschreibung bzw. den Pfad zu einer gespeicherten Dienstbeschreibung angeben.

Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

Hinweis:
Nachfolgend werden die gängigen Argumente für Wsdl.exe aufgelistet. Die vollständige Syntax von Wsdl.exe finden Sie unter Web Services Description Language-Tool (Wsdl.exe).

Details zu den generierten Proxyklassen

Wenn Sie mit Wsdl.exe eine Proxyklasse erstellen, wird eine einzelne Quelldatei in der angegebenen Programmiersprache erzeugt. Diese Datei enthält eine Proxyklasse, die sowohl synchrone als auch asynchrone Methoden für die einzelnen Webdienstmethoden des Webdiensts verfügbar macht. Wenn ein Webdienst beispielsweise eine Webdienstmethode namens Add enthält, verfügt die Proxyklasse über folgende Methoden zum Aufrufen der Add-Webdienstmethode: Add, BeginAdd** und EndAdd. Die Add-Methode der Proxyklasse wird für die synchrone Kommunikation mit der Add-Webdienstmethode verwendet, während die Methoden BeginAdd und EndAdd für die asynchrone Kommunikation mit einer Webdienstmethode verwendet werden. Weitere Informationen über finden Sie unter Asynchrones Kommunizieren mit XML-Webdiensten.

Jede Methode der generierten Proxyklasse enthält den erforderlichen Code für die Kommunikation mit der Webdienstmethode. Wenn ein Fehler während Kommunikation mit dem Webdienst und der Proxyklasse auftritt, wird eine Ausnahme ausgelöst. Weitere Informationen über das Behandeln von Ausnahmen finden Sie unter Behandeln und Auslösen von Ausnahmen in XML-Webdiensten.

Die in der Webdienstmethode definierte Parameterreihenfolge kann sich von der in der zugehörigen Methode der Proxyklasse definierten Parameterreihenfolge unterscheiden. Meist stimmt die Parameterreihenfolge jedoch überein. Wenn der Webdienst jedoch mit Document formatierte SOAP-Nachrichten erwartet, ist dies ein Fall, in dem die Parameterreihenfolge nicht übereinstimmt. Wenn in einer Webdienstmethode vor einem in-Parameter out-Parameter definiert sind, stehen die out-Parameter in der Proxyklasse hinter allen in-Parametern. Im folgenden Beispiel wurde in der Webdienstmethode MyWebMethod beispielsweise der outStr-Parameter vor dem inStr-Parameter deklariert. In der Proxyklasse wurde der inStr-Parameter jedoch vor outStr deklariert.

' Declare MyWebMethod in the Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)

// Declare MyWebMethod in the Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

In einigen Fällen geht die von Wsdl.exe erstellte Proxyklasse beim Umwandeln von Objekten in einen in einer Dienstbeschreibung angegebenen Typ nach dem Prinzip des kleinsten gemeinsamen Nenners vor. Dadurch entspricht der in der Proxyklasse erzeugte Typ u. U. nicht den Vorstellungen oder Erwartungen des Entwicklers. Wenn das Tool Wsdl.exe in einer Dienstbeschreibung beispielsweise auf einen ArrayList-Typ stößt, erstellt es in der generierten Proxyklasse ein Object-Array. Um die korrekte Umwandlung von Objekttypen sicherzustellen, öffnen Sie die Datei mit der erstellten Proxyklasse, und ändern Sie alle falschen Objekttypen in den erwarteten Objekttyp.

Von Wsdl.exe ausgelöste Warnungen

Wenn mehrere Dienstbeschreibungen an Wsdl.exe übergeben werden, können die beiden folgenden Fehlermeldungen ausgegeben werden:

• Warnung: Doppelte Dienstbeschreibung mit TargetNamespace=<schema namespace> von <schema URI> wird ignoriert.

  Diese Warnung gibt an, dass TargetNamespace bei mindestens zwei der angegebenen Dienstbeschreibungen identisch ist. Da TargetNamespace ein eindeutiger Bezeichner für ein bestimmtes XML-Dokument, hier eine Dienstbeschreibung, sein soll, geht Wsdl.exe davon aus, dass die beiden Dienstbeschreibungen identisch sind. Ausgehend von dieser Annahme erstellt Wsdl.exe nur eine Proxyklasse für eine der Dienstbeschreibungen. Wenn dieses Verhalten nicht beabsichtigt ist, können Sie es ändern. Auf Dienstbeschreibungen für Webdienste, die mit ASP.NET erstellt wurden, können Sie ein WebService-Attribut anwenden, das eine eindeutige Namespace-Eigenschaft für die Klasse angibt, durch die der Webdienst implementiert wird. Die Namespace-Eigenschaft wird anschließend in der Dienstbeschreibung als TargetNamespace verwendet, um den Webdienst eindeutig zu identifizieren.

• Warnung: Doppeltes Schema mit TargetNamespace=<schema Namespace> von <schema URI> wird ignoriert.

  Diese Warnung gibt an, dass TargetNamespace bei mindestens zwei XML-Schemas in den angegebenen Dienstbeschreibungen identisch ist. Da TargetNamespace ein eindeutiger Bezeichner für ein bestimmtes XML-Dokument, hier ein XML-Schema, sein soll, geht Wsdl.exe davon aus, dass die beiden XML-Schemas identisch sind. Ausgehend von dieser Annahme erstellt Wsdl.exe nur eine Klasse für eines der Schemas. Wenn dies nicht das gewünschte Ergebnis ist, muss TargetNamespace für die einzelnen XML-Schemas in einen eindeutigen URI geändert werden. Wie die TargetNamespace-Angabe im Einzelnen geändert wird, hängt vom Ursprung der jeweiligen XML-Schemas ab.

Siehe auch

Aufgaben

Vorgehensweise: Untersuchen von vorhandenen mit ASP.NET erstellten Webdiensten
Vorgehensweise: Zugreifen auf XML-Webdienste von einem Browser aus

Konzepte

Erstellen von XML-Webdienstclients
Webdiensterkennung
Asynchrones Kommunizieren mit XML-Webdiensten

Weitere Ressourcen

Erstellen von Clients für XML-Webdienste