Erstellen eines XML-Webdienstproxys

Mit XML-Webdiensten kann laut Definition über ein Netzwerk kommuniziert werden, das auf Industriestandardprotokollen basiert, z. B. SOAP. Ein Client und ein XML-Webdienst kommunizieren also über SOAP-Meldungen, in denen Eingabe- und Ausgabeparameter als XML eingeschlossen sind. Bei XML-Webdienstclients ist praktischerweise die Proxyklasse dafür zuständig, XML-Elementen Parameter zuzuordnen und die SOAP-Meldung dann über das Netzwerk zu senden.

So lange eine Dienstbeschreibung vorhanden ist, kann eine Proxyklasse erstellt werden, vorausgesetzt, die Dienstbeschreibung wurde in der Web Services Description Language (WSDL) geschrieben. In der Dienstbeschreibung wird definiert, wie die Kommunikation mit einem XML-Webdienst erfolgt. Bei Vorhandensein einer Dienstbeschreibung kann mit dem Tool Wsdl.exe eine Proxyklasse erstellt werden. Ein XML-Webdienstclient kann wiederum anschließend Methoden der Proxyklasse aufrufen, die über das Netzwerk mit einem XML-Webdienst kommunizieren. Für die Kommunikation werden die SOAP-Meldungen verarbeitet, die vom XML-Webdienst empfangen oder gesendet werden. Da die Proxyklasse mit dem XML-Webdienst über das Internet kommuniziert, empfiehlt es sich zu überprüfen, ob die Url-Eigenschaft der Proxyklasse auf ein vertrauenswürdiges Ziel verweist.

Die Proxyklasse verwendet SOAP standardmäßig über das HTTP-Protokoll, um mit dem XML-Webdienst zu kommunizieren. Wsdl.exe kann jedoch Proxyklassen erstellen, die die Kommunikation mit einem XML-Webdienst unterstützen; die Kommunikation erfolgt entweder über das HTTP-GET- oder das HTTP-POST-Protokoll. Um zu bestimmen, ob die Proxyklasse HTTP-GET oder HTTP-POST verwenden soll, legen Sie für das Tool Wsdl.exe den Schalter /protocol fest, wie in der folgenden Tabelle beschrieben.

So erstellen Sie eine Proxyklasse für einen XML-Webdienst

• Führen Sie an einer Eingabeaufforderung Wsdl.exe aus, um eine Proxyklasse zu erstellen. Geben Sie dabei (mindestens) den URL für einen XML-Webdienst oder eine Dienstbeschreibung bzw. den Pfad zu einer bereits gespeicherten Dienstbeschreibung an.

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

  Hinweis: Die oben aufgelisteten Argumente sind allgemein verwendete Argumente für das Tool Wsdl.exe. Die vollständige Syntax des Tools Wsdl.exe finden Sie unter Web Services Description Language-Tool (Wsdl.exe).

  Parameter	Wert
  <url or path>	Ein URL oder Pfad zu einer Dienstbeschreibung (einer Datei, in der ein XML-Webdienst in der Web Services Description Language (WSDL) beschrieben ist). Wenn Sie eine Datei angeben, stellen Sie eine Datei bereit, die die Dienstbeschreibung enthält. Beispiel: MeinWebdienst.wsdl Wenn Sie einen URL angeben, muss dieser auf eine ASMX-Seite verweisen oder eine Dienstbeschreibung zurückgeben. Bei XML-Webdiensten, die mit Hilfe von ASP.NET erstellt wurden, können Sie eine Dienstbeschreibung zurückgeben, indem Sie an den URL des XML-Webdienstes "?WSDL" anfügen. Beispiel: https://www.contoso.com/MeinWebdienst.asmx?WSDL
  /language:language	Die Sprache, in der die Proxyklasse erstellt wurde. Die verfügbaren Optionen lauten CS, VB und JS und stehen für C#, Visual Basic .NET bzw. JScript .NET. Die Standardsprache ist C#. (Optional).
  /protocol:protocol	Das Protokoll für die Kommunikation mit den XML-Webdienstmethoden. Die verfügbaren Optionen umfassen SOAP, HTTP-GET und HTTP-POST. Das Standardprotokoll ist SOAP. (Optional).
  /namespace:myNameSpace	Der Namespace des generierten Proxys. Der Standardwert ist der globale Namespace. (Optional).
  /out:filename	Der Name der zu erstellenden Datei, die die Proxyklasse enthält. Der Standardname basiert auf dem Namen der Klasse, durch die der XML-Webdienst implementiert wird. (Optional).
  /username:username	Der Benutzernamen für die Verbindung mit einem Webserver, für den eine Authentifizierung erforderlich ist. (Optional).
  /password:password	Das Kennwort für die Verbindung mit einem Webserver, für den eine Authentifizierung erforderlich ist. (Optional).
  /domain:domain	Die Domäne für die Verbindung mit einem Webserver, für den eine Authentifizierung erforderlich ist. (Optional).

Details zu erstellten Proxyklassen

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

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

Zwischen der in der XML-Webdienstmethode definierten und der in der verknüpften Methode der Proxyklasse definierten Parameterreihenfolge kann es Unterschiede geben. In den meisten Fällen stimmt die Parameterreihenfolge jedoch überein. Ein Beispiel für eine nicht übereinstimmende Parameterreihenfolge ist ein XML-Webdienst, der mit Document formatierte SOAP-Meldungen erwartet. Wenn in einer XML-Webdienstmethode vor einem Eingabeparameter Ausgabeparameter definiert sind, stehen die Ausgabeparameter in der Proxyklasse hinter allen anderen Parametern. Im folgenden Codebeispiel wurde für die XML-Webdienstmethode MyWebMethod beispielsweise der Ausgabeparameter outStr vor dem Eingabeparameter inStr deklariert. In der Proxyklasse wurde der inStr-Parameter jedoch vor outStr deklariert.

In einigen Fällen verwendet die von WSDL.exe erstellte Proxyklasse das Prinzip des kleinsten gemeinsamen Nenners zum Umwandeln von Objekten in einen in einer Dienstbeschreibung angegebenen Typ. Dadurch entspricht der in der Proxyklasse erzeugte Typ u. U. nicht den Vorstellungen oder Erwartungen des Entwicklers. Wenn WSDL.exe z. B. auf einen ArrayList-Typ in einer Dienstbeschreibung stößt, wird ein Objektarray in der erzeugten Proxyklasse erstellt. Um die korrekte Umwandlung von Objekttypen sicherzustellen, öffnen Sie die Datei mit der erstellten Proxyklasse, und ändern Sie alle falschen Objektypen in den erwarteten Objekttyp.

' Declare MyWebMethod in the XML 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)
[C#]
// Declare MyWebMethod in the XML 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 verwendet die von WSDL.exe erstellte Proxyklasse das Prinzip des kleinsten gemeinsamen Nenners zum Umwandeln von Objekten in einen in einer Dienstbeschreibung angegebenen Typ. Dadurch entspricht der in der Proxyklasse erzeugte Typ u. U. nicht den Vorstellungen oder Erwartungen des Entwicklers. Wenn WSDL.exe z. B. auf einen ArrayList-Typ in einer Dienstbeschreibung stößt, wird ein Object-Array in der erzeugten Proxyklasse erstellt. Um die korrekte Umwandlung von Objekttypen sicherzustellen, öffnen Sie die Datei mit der erstellten Proxyklasse, und ändern Sie alle falschen Objektypen in den erwarteten Objekttyp.

Durch "Wsdl.exe" ausgelöste Warnungen

Wenn Sie mehrere Dienstbeschreibungen für Wsdl.exe angeben, können die beiden folgenden Fehlermeldungen ausgegeben werden:

• Warnung: Doppelte Dienstbeschreibung mit TargetNamespace=<Schemanamespace> von <Schema-URI> wird ignoriert.

  Diese Warnung gibt an, dass der TargetNamespace für zwei oder mehrere der bereitgestellten Dienstbeschreibungen identisch ist. Da TargetNamespace ein eindeutiger Bezeichner für ein bestimmtes XML-Dokument, in diesem Fall eine Dienstbeschreibung, sein sollte, 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 XML-Webdienste, die mit ASP.NET erstellt wurden, können Sie ein WebService-Attribut anwenden, indem Sie eine eindeutige Namespace-Eigenschaft für die Klasse angeben, durch die der XML-Webdienst implementiert wird. Diese Namespace-Eigenschaft wird anschließend in der Dienstbeschreibung als TargetNamespace verwendet, um den XML-Webdienst eindeutig zu identifizieren. Weitere Informationen zum Festlegen der Namespace-Eigenschaft finden Sie unter Anwenden des WebService-Attributs.

• Warnung: Doppeltes Schema mit TargetNamespace=<Schemanamespace> von <Schema-URI> wird ignoriert.

  Diese Warnung gibt an, dass der TargetNamespace für zwei oder mehrere der XML-Schemas innerhalb der bereitgestellten Dienstbeschreibungen identisch ist. Da TargetNamespace ein eindeutiger Bezeichner für ein bestimmtes XML-Dokument, in diesem Fall das XML-Schema, sein sollte, geht Wsdl.exe davon aus, dass die beiden XML-Schemas identisch sind. Ausgehend von dieser Annahme erstellt Wsdl.exe nur für eines der Schemas eine Klasse. Wenn dies nicht beabsichtigt ist, muss der TargetNamespace für die einzelnen XML-Schemas in einen eindeutigen URI geändert werden. Wie genau der TargetNamespace geändert wird, hängt vom Ursprung der jeweiligen XML-Schemas ab.

Siehe auch

Erstellen von XML-Webdienstclients | Suchen von XML-Webdiensten | Erstellen von Clients für XML-Webdienste | Durchsuchen von vorhandenen mit ASP.NET erstellten XML-Webdiensten | Asynchrones Kommunizieren mit XML-Webdiensten | Zugreifen auf XML-Webdienste aus einem Browser