.NET: Zugriff auf einen bestehenden SOAP Webservice (Bing Translator Service inkl. Beispielanwendung)

Im Beitrag SOA, HTTP, SOAP und REST wurden einigen Grundlagen zu SOA, HTTP und SOAP erläutert. In diesem Beitrag möchte ich nun zeigen wie man mit Hilfe von .NET und C# einen bestehenden SOAP-Webservice nutzen kann. Dafür wird eine kleine Beispielanwendung erstellt, die den Microsoft Bing-Translator Service verwendet. Diese kleine Beispielanwendung nutzt die SOAP-Schnittstelle des Webservice um eingegebene Texte in verschiedene Sprachen zu übersetzen.

Microsoft Translator API

Die Microsoft Translator API bietet eine Reihe von leistungsstarken Web-Service-APIs, die Entwickler zur maschinellen Übersetzung von Texten in ihren eigenen Anwendungen verwenden können. Es werden z.B. ein HTTP REST-Service und SOAP Webservice zur Verfügung gestellt (im folgenden Beispiel wird näher auf den SOAP Webservice eingegangen). Microsoft Translator API ist ein Online-Service und steht im Windows Azure Marketplace zur Verfügung. Die Microsoft Translator API wird als ein monatliches Abonnement verkauft. Der Monatsbeitrag berechnet sich nach der Anzahl der zu übersetzenden Zeichen des Textes. Für den Einsatz von bis zu 2 Millionen Zeichen pro Monat ist API ist auch kostenlos verfügbar (dieses Abonnement wird auch im Beispiel verwendet).

Eine Auswahl der Methoden, die die API für Entwickler bietet sind unten aufgeführt:

  • Translate — Übersetzt Text von einer Sprache in eine andere
  • TranslateArray — Übersetzt ein Array von Texten von einer Sprache in eine andere
  • Speak (Text To Speech) — Audioausgabe des Textes in der gewünschten Sprache
  • Detect — Erkennt die Sprache der Zeichenfolge

Wie man sich ein kostenloses Konto einrichtet wird im Beitrag genauer beschrieben. Im Verlauf des Registrierungsprozesses erhält man auch Zugangsdaten, die für die spätere Anwendung unbedingt erforderlich sind. Ohne die Angaben dieser Zugangsdaten ist kein Zugriff auf die Service-Funktionen möglich!

Projekterstellung und Hinzufügen der Service-Referenz

Die Web Service Description Language (WSDL) ist eine auf XML basierende Sprache zur formalen Beschreibung von Webservices. Ein WSDL-Dokument beschreibt die angebotenen Funktionen, Daten, Datentypen und Austauschprotokolle eines Webservice. Es werden im Wesentlichen die Operationen definiert, die von außen zugänglich sind, sowie die Parameter und Rückgabewerte dieser Operationen. WSDL-Dokumente werden von Webservice-Implementierungen genutzt, um Proxy-Klassen für einen zu konsumierenden Webservice zu erstellen. Die Proxy-Klasse, die zum Zusammensetzen der gesendeten Objekte auf der Client-Seite notwendig ist, kann automatisiert aus der WSDL-Datei generiert werden. Eine Proxy-Klasse ist eine Klasse, die dem Webservice gleicht, wobei die einzelnen Methoden unter Verwendung des gewählten Protokolls und Nachrichtenformats an den eigentlichen Service weiterdelegiert werden. Der Client nutzt die generierte Proxy-Klasse als lokale Komponente und muss sich nicht mit den Details der rechnerübergreifenden Kommunikation auseinandersetzen. Um eine solche Proxy-Klasse zu generieren geht man wie folgt vor:

Im ersten Schritt erstellt man ein einfaches WPF-Projekt oder auch WinForms-Projekt. Für dieses Beispiel wird die WPF verwendet.

MicrosoftTranslatorSample_NewProject

Ist das neue Projekt erstellt bindet man zunächst die Referenz auf den Microsoft Translator Service ein. Dies geschieht mit einem Rechtsklick auf das Projekt und dann über den Menüpunkt Hinzufügen | Service Referenz … .

MicrosoftTranslatorSample_AddServiceReference_01

Danach erscheint der folgende Dialog:

MicrosoftTranslatorSample_AddServiceReference_02

In diesem Dialog müssen nun einige Angaben gemacht werden:

  1. Adresse des Service: Für dieses Beispiel wird der Microsoft Translator Service eingebunden -> http://api.microsofttranslator.com/V2/Soap.svc
  2. Der Namespace in dem die Proxy-Klasse anhand der WSDL-Definition generiert werden. Hier kann man sich etwas entsprechendes ausdenken 😉

Über den Button „Erweitert …“ kann man weitere Einstellungen für den Generierungsprozess vornehmen:

MicrosoftTranslatorSample_AddServiceReference_03

Durch anklicken der Checkbox „Generate asynchronous operations“ generiert Visual Studio sowohl synchrone und asynchrone Methoden für den Datenzugriff. Ich habe diese Option für das Beispielprogramm angewählt und zeige später die Verwendung der asynchronen Methoden. Nachdem man alle Einstellungen vorgenommen hat erscheint die Service-Referenz auch im Projektmappen-Explorer (unter dem Namen, den man bei den Einstellungen für den Namespace vergeben hat):

MicrosoftTranslatorSample_AddServiceReference_04

Natürlich kann man sich die generierten Methoden der Proxy-Klasse auch im Objekt-Explorer von Visual Studio anschauen:

MicrosoftTranslatorSample_AddServiceReference_05

Damit wäre die Einbindung des Service soweit auch schon abgeschlossen. Jetzt geht es an die Verwendung der generierten Proxy-Klasse.

GUI

Bevor die Verwendung der generierten Proxy-Klasse beschrieben wird hier zunächst die Oberfläche der Anwendung.

MicrosoftTranslatorSample_GUI

Ich denke die Oberfläche ist selbsterklärend und von daher gehe ich hier jetzt nicht weiter darauf ein.

Verwendung des Service

Für das Beispiel werden lediglich drei Methoden des Service benötigt:

  • GetLanguagesForTranslate / GetLanguagesForTranslateAsync: Ermittelt die unterstützten Sprachkennzeichen z.B. de, en, …
  • GetLanguageNames / GetLanguageNamesAsync: Ermittelt die Namen der Sprachen in einer gewünschten Übersetzung (z.B. Deutsch, Englisch, … oder German, English, …
  • Translate / TranslateAsync: Methode für die eigentliche Übersetzung

Um diese Methoden verwenden zu können, benötigen wir zunächst eine ServiceClient-Instanz für den eigentlichen Service-Zugriff. Da in diesem Beispiel die asynchronen Methoden für den Zugriff verwendet werden müssen auch die entsprechenden Finished-Handler für die Methodenaufrufe registriert werden (hier werden dann die Eigenschaften für das DataBinding versorgt). Nachfolgend der Quellcode für die Erstellung der Service-Instanz und die Registrierung der Finished-Handler für die verwendeten asynchronen Methoden:

Die Finished-Handler sehen dann wie folgt aus:

Der Ablauf beim Programmstart sieht wie folgt aus:

  1. Im ersten Schritt werden die unterstützten Sprachen des Service ermittelt. Dies wird durch den Auruf der Methode GetLanguagesForTranslate-Methode realisiert. Diese Methode ermittelt jedoch nur die Sprachkennzeichen (z.B. de, en, …). Im Finished-Handler dieser Methode werden dann die Namen zu den Sprachkennzeichen ermittelt (Zeile 10)
  2. Aufruf der Methode GetLanguageNames zur Ermittlung der Namen zu den identifizierten Sprachkennzeichen. Die Methode erwartet als Parameter zum einen die ermittelten Sprachkennzeichen (Ergebnis der Methode GetLanguagesForTranslate) und die Sprache in welcher die entsprechenden Namen zurückgeliefert werden sollen. Im Finished-Handler dieser Methode wird dann eine Liste mit den Sprachkennzeichen und den entsprechenden Namen erstellt (Zeile 22 – 30)

Waren diese Methoden-Aufrufe erfolgreich sind die ComboBoxen, durch das DataBinding, mit den unterstützen Sprachen gefüllt!

MicrosoftTranslatorSample_SupportedLanguages

Gibt man nun den zu übersetzenden Text ein und drückt den Button „Translate“ wird die Translate-Methode des Service aufgerufen. Die Translate-Methode erwartet u.a. die folgenden Parameter:

  • den zu übersetzenden Text
  • die Ausgangssprache (wird aus der ComboBox versorgt)
  • die Zielsprache (wird aus der ComboBox versorgt)

Der Methodenaufruf sieht wie folgt aus:

Im Finished-Handler der Translate-Methode wird dann die Eigenschaft für den übersetzten Text gesetzt.

Beispiel-Anwendung

Für das erfolgreiche Ausführen der Beispielanwendung werden, wie oben schon geschrieben, Zugangsdaten für den Zugriff auf den Service benötigt. Wie man an diese Zugangsdaten kommt wir hier beschrieben: Walkthrough: Signing up for Microsoft Translator and getting your credentials

Diese Zugangsdaten können dann in der Anwendung hinterlegt werden:

MicrosoftTranslatorSample_ClientSecret

Die Zugangsdaten sind im ViewModel einzutragen! Werde keine gültigen Zugangsdaten hinterlegt ist die Anwendung nicht lauffähig!

[wpdm_file id=3]

Literaturverzeichnis und Weblinks

Abk.Quelle
[1]Walkthrough: Signing up for Microsoft Translator and getting your credentials
[2]MSDN reference for Microsoft Translator APIs
[3]SOAP API for the Microsoft Translator service
[4]Wikipedia: Web Services Description Language (WSDL)
Fork me on GitHub