Ein WCF-Service läuft nicht als eigenständiges Programm. Der Normalfall wird sein, dass ein Programm auf den konfigurierten Endpunkten lauscht, und sobald ein passender Request eines Clients angeschwemmt wird, eine Instanz der WCF-Service-Klasse erstellt und ihr die richtigen Parameter übergibt. Der Service befindet sich also in einer Umgebung, die weiß, wie sie zu lauschen hat, und die weiß, von welcher Klasse der Service ist, und wie er zu erzeugen ist. Diese Umgebung ist der ServiceHost, und um den passenden ServiceHost für unseren WCF-Service geht es im viertel Teil meiner Serie.

Wie überall in .NET, gibt es zwei Möglichkeiten, die Dinge anzugehen: die einfache Variante, die sich stark auf Konfiguration verlässt, oder die Variante, alles per Code selbst zu machen. Die einfache Variante, einen ServiceHost zu starten, ist wie folgt:

using (ServiceHost serviceHost = new ServiceHost(typeof(ServiceImplementationClass)))
{
   serviceHost.Open();
   Console.WriteLine("The service is ready.");
   Console.WriteLine("Press  to terminate service.");
   Console.ReadLine();
}

Dieser Codeschnipsel kann in jeder Anwendung eingefügt werden – sei es eine Konsolenanwendung, ein Windows-Dienst, eine WPF-Applikation oder was auch immer. Hauptsache, ausführbar. Welches Protokoll verwendet wird, wie die URI ist, auf der gelauscht wird, und all die anderen Einstellungen passieren werden dabei im system.serviceModel-Abschnitt der Konfigurationsdatei der Anwendung festgelegt.

ServiceHosts sind, wie zu sehen ist, an sich unabhängig von der Klasse des Services, dem sie eine Umgebung bieten. Dagegen muss man beim obigen Ansatz fest programmieren, welcher Service gehostet werden soll – nicht sehr gut wiederverwendbar in anderen Projekten. Wenn man mal darüber nachdenkt, liegt es also recht nahe, eine Factory-Klasse zu schreiben, die anhand einer Service-Klasse den passenden ServiceHost zurückliefert. Nun ist es nicht sehr überraschend, dass im .NET-Framework so eine Factory-Infrastruktur bereits vorhanden ist.

Die Factory-Klasse für ServiceHosts nennt sich – wieder keine wirkliche Überraschung – ServiceHostFactory und kann für beliebige Familien von ServiceHosts so überschrieben werden, wie das notwendig erscheint. Dabei gibt es bereits einige Implementierungen für verschiedene Szenarien: unter anderem auch das Szenario eines Webservice, das wir benötigen, nämlich WebServiceHostFactory. Die MSDN bietet einen kleinen, sehr treffenden Satz, der diese Klasse beschreibt:

A factory that provides instances of WebServiceHost in managed hosting environments where the host instance is created dynamically in response to incoming messages.

REST-Services sind nicht zuletzt, weil sie sich auf HTTP verlassen, natürlich prädestiniert dafür, im Kontext eines Webservers zu laufen (man könnte so weit gehen zu behaupten, dass sie nur dort einen Sinn ergeben). Unser REST-Web-Service wird also von einer WebServiceHost-Umgebung gehostet, die wiederrum von einer WebServiceHostFactory erzeugt wird. Wir haben die Wahl der Anwendung, die diese Klassen in ihrem ausführbaren Part benutzt. Wir werden später sowieso noch eine Webanwendung brauchen: sie soll ja unseren Client darstellen, der per Javascript auf den Service zugreift. Daher lassen wir unseren Service einfach gleich mit vom IIS hosten.

Das bietet uns noch einen weiteren Vorteil. Sagen wir, unsere Webseite (der Client) läuft später unter der Adresse

http://localhost/MyServiceClient/

(also auf Port 80). Dann müsste unser Service so konfiguriert werden, dass er auf derselben Adresse auf irgendeinem anderen Port lauscht – 80 ist bereits vom IIS besetzt. Das wiederum hätte alllerdings zur Folge, dass das Javascript auf localhost:80 zugreifen muss auf einen Service, der auf localhost:1223 (beliebiger anderer Port) lauscht. Und das wiederum eröffnet eine ganze Reihe von potentiellen Problemen, die darin begründet sind, dass Javascript (aus Sicherheitsgründen) nicht einfach auf Drittressourcen ungeprüft zugreifen können darf – Stichwort XSS.

Diesen ganzen Ärger umgehen wir, indem wir eine Webanwendung erstellen, und den Service innerhalb dieser Webanwendung hosten lassen.

Alles, was dazu nötig ist, ist eine Datei „MessageService.svc“ mit folgendem Inhalt:

<%@ ServiceHost
  Language="C#"
  Service="MessageService.MessageService"
  Factory="System.ServiceModel.Activation.WebServiceHostFactory"
%>

That’s it. Die Angabe beim Parameter „Service“ bezieht sich dabei auf den vollen Namen (Namespace + Klasse) der Service-Implementierung. Wenn die Webanwendung gestartet wird und die Adresse http://localhost:PORT/Webanwendungsname/ExampleService.svc im Browser aufgerufen wird, sollte bereits eine Antwort erfolgen – „Es wurde kein Endpunkt gefunden.“, was logisch ist, da keiner unserer Schnittstellenoperationen auf „/“ zugeordnet wurde.

Weiter geht’s im nächsten Teil mit der Programmierung des Zugriffs auf den neuen Service per Javascript.

Ardbeg bietet als Ausgleich noch ein kleines, aber witziges Flash-Spielchen, in dem man den blöden Engeln den Angel’s Share streitig machen darf.

Weg ist er, der Frust über monetäre Engpässe.

Die Implementierung unserer IMessageService-Schnittstelle geht in der Klasse MessageService vor sich. Wir haben in dieser Schnittstelle Methoden für Erstellen, Löschen, Verändern und Abrufen, sowie für das Abrufen einer Liste von einzelnen Instanzen der ChatMessage-Klasse deklariert.

In MessageService bereiten wir nun den Programmcode vor, der festlegen wird, wie diese Methoden auszuführen sind.

Die Service-Implementierung beinhaltet den Code, der auf gespeicherte Daten zugreift und sie abruft, oder verändert. Um nicht unnötig vom Wesentlichen – dem Service selbst – abzulenken, beschränke ich mich dabei auf die Speicherung in einer XML-Datei.

Für die Zugriffsschicht auf das XML muss LinQ To Xml herhalten: so blasen wir den Code nicht unnötig weiter auf.

Die Informationen über die XML-Datei, in der die Daten gespeichert werden sollen, werden durch zwei Membervariablen gehalten: m_XmlFileName beinhaltet den Namen der Datei, m_MessageXml bereits das XDocument, mit dessen Hilfe wir den Zugriff auf die Daten realisieren. Beide werden im Konstruktor des Service gefüllt:

public class MessageService : IMessageService
{
  private XDocument m_MessageXml;
  private string m_XmlFilename;

  public MessageService()
  {
    // ich gehe davon aus, dass in der app.config ein
    // Eintrag in den AppSettings vorhanden ist, der
    // "messagefile" heisst und den Namen der Datei
    // enthält - und davon, dass jene Datei auch im
    // Hauptverzeichnis der Applikation ist
    m_XmlFilename = AppDomain.CurrentDomain.BaseDirectory +
             ConfigurationManager.AppSettings["messagefile"];

    //Anlegen, falls nicht vorhanden
    if (!File.Exists(m_XmlFilename))
    {
      m_MessageXml = new XDocument(
        new XDeclaration("1.0", "utf-8", "yes"),
        new XElement("Messages")
      );
      m_MessageXml.Save(m_XmlFilename);
    }
    //Oder laden, falls vorhanden.
    else
      m_MessageXml = XDocument.Load(m_XmlFilename);
  }

Nachdem die Daten nun griffbereit in einem XDocument verfügbar sind, machen wir uns an das Auslesen einer Liste von ChatMessage-Objekten. Die Schnittstelle hat dafür die Methode ListMessages vorgesehen.

public List ListMessages()
{
  var result = m_MessageXml.Descendants("Message")
              .Select(p => new ChatMessage().Parse(p));
  return result.OrderByDescending(p => p.Time).ToList();
}

Dem kundigen Auge wird bereits die Methode Parse() aufgefallen sein. Keine Sorge, dazu kommen wir noch. Gut zu sehen dagegen ist, wieso ich mich für LinQ To Xml entschieden habe – sehr viel kürzer geht’s wirklich nicht mehr.

Der Zugriff auf einen einzelnen Datensatz, in der Schnittstelle durch die Methode GetMessage() deklariert, sieht ganz ähnlich aus. Allerdings gibt es einen kleinen Unterschied: wenn es den angeforderten Datensatz nicht gibt, geben wir nicht nur nichts zurück, sondern setzen den HTTP-Status der Antwort auf NotFound (Status Code 404). Sollte unser Client (also das Javascript im Browser) in der Lage sein, diese Status Codes auszuwerten, dann können wir sie auch benutzen, um den Grund eines Fehlschlags zu übermitteln.

public ChatMessage GetMessage(string messageId)
{
    XElement element = m_MessageList.Descendants("Message")
                      .FirstOrDefault(p =>
                        p.Attribute("id").Value == messageId
                      );
    if (element != null)
    {
        return new ChatMessage().Parse(element);
    }
    else
    {
        WebOperationContext.Current.OutgoingResponse.StatusCode =
                                              HttpStatusCode.NotFound;
        return null;
    }
}

Parse() wurde schon wieder verwendet, ich weiß. Merkt’s euch, die Liste mit den unbekannten Methoden wird noch zwei Einträge länger.

Die nächsten zwei Methoden – erstellen und löschen einer Nachricht – können ohne große Erläuterung für sich selbst sprechen:

public ChatMessage CreateMessage(ChatMessage message)
{
    ChatMessage saveMessage = new ChatMessage(
                     message.Author, message.Text);
    //Nachricht im XML speichern
    saveMessage.Save(m_MessageList);
    //und XML speichern
    m_MessageList.Save(m_XmlFilename);  

    WebOperationContext.Current.OutgoingResponse.StatusCode =
                                       HttpStatusCode.Created;
    return saveMessage;
}

public ChatMessage DeleteMessage(string messageId)
{
    ChatMessage removeMessage = GetMessage(messageId);
    if (removeMessage != null)
    {
        removeMessage.Remove(m_MessageList);
    }
    m_MessageList.Save(m_XmlFilename);
    return removeMessage;
}

Da beim Löschen einer Nachricht auf die Methode GetMessage() zurückgegriffen wird, ist bereits für den Fall gesorgt, dass eine Nachricht gelöscht werden soll, die gar nicht existiert: in diesem Fall setzt GetMessage() bereits wie gehabt den Status Code auf 404.

Zu Kommentieren bleibt bloss, dass von der übermittelten Nachricht beim Erstellen lediglich die Inhalte benutzt werden: ID und die Zeit des Eintrags übernimmt offenbar unser ChatMessage-Objekt.
Die letzte verbleibende Methode dienst dem Aktualisieren von Einträgen:

public ChatMessage ModifyMessage(string messageId,
                             ChatMessage messageToModify)
{
    if (GetMessage(messageId) != null)
    {
        messageToModify.MessageId = new Guid(messageId);
        messageToModify.Save(m_MessageList);
        m_MessageList.Save(m_XmlFilename);
        return messageToModify;
    }
    return null;
}

Auch das sollte einfach so verstanden werden – das einzig bemerkenswerte ist: die Nachricht wird anhand der übergebenen ID identifiziert, nicht etwa anhand der ID des übergebenen ChatMessage-Objekts: deshalb die Zuweisung der MessageId.

Na, die drei Methoden schon wieder vergessen, die neu waren? Wie versprochen, der überladene Konstruktur, die Save()-Methode, die Remove()-Methode, und die Parse()-Methode – alle drei zu ChatMessage gehörend. Im Wesentlichen erledigen sie das Mapping hin von einer Property von ChatMessage zu einem Knoten im XML.

public ChatMessage Parse(XElement xElement)
{
  MessageId = new Guid(xElement.Attribute("id").Value);
  Text = xElement.Element("text").Value;
  Time = DateTime.Parse(xElement.Element("time").Value);
  Author = xElement.Element("author").Value;
  return this;
}

public void Save(XDocument doc)
{
  XElement messageNode = doc.Descendants("Message")
          .FirstOrDefault(p =>
            p.Attribute("id").Value == MessageId.ToString());
  if (messageNode == null)
  {
    doc.Root.Add(
      new XElement("Message",
        new XAttribute("id", MessageId),
        new XElement("time",
                       Time.ToString("dd.MM.yy HH:mm:ss")),
        new XElement("author", Author),
        new XElement("text", Text)
      )
    );
  }
  else
  {
    messageNode.Element("text").Value = Text;
    messageNode.Element("author").Value = Author;
    messageNode.Element("time").Value =
                 Time.ToString("dd.MM.yy HH:mm:ss");
  }
  return this;
}

public ChatMessage Remove(XDocument doc)
{
  XElement messageNode = doc.Descendants("Message")
          .FirstOrDefault(p =>
            p.Attribute("id").Value == MessageId.ToString());
  if(messageNode != null) messageNode.Remove();
  return this;
}

Und damit kann der Service eigentlich bereits gestartet und durch einen Client angesprochen werden. Wie genau das funktioniert, wird im nächsten Teil geklärt.

Das vom Bundestag Mitte Juni beschlossene und vom Bundesrat am 10. Juli abgesegnete Gesetz befindet sich demnach noch auf dem Weg durch die Instanzen. Bevor es beim Bundespräsidialamt aufschlägt, wird es von den zuständigen Fachministerien noch einmal gegengelesen.

Damit es beim prophezeiten Aufschlag keine Verletzten gibt, hätte ich schon einen Vorschlag:

Wie wär’s mit einem großen, roten Stoppschild?

WCF unterstützt seit der .NET-Frameworkversion 3.5 das Erstellen von RESTful Webservices durch das WebInvokeAttribute. Auf die Properties dieses Attributs möchte ich kurz anhand von Beispielen eingehen.

UriTemplate

Dieses Property legt die Adresse für die Schnittstelle (also die URI) fest. Dabei können Platzhalter für Zeichenketten-Parameter hinterlegt werden.

[OperationContract]
[WebInvoke(RequestUri = "Message/{messageId}";)]
ChatMessage GetMessageDetails(string messageId); 

Wenn der Service unter der Adresse

http://service.example.com/MessageService/

veröffentlicht wird, wäre der Endpunkt für die Methode GetMessageDetails demnach

http://service.example.com/MessageService/Message/{messageId},

wobei {messageId} lediglich ein Platzhalter für eine Zeichenkette ist, die der Methode GetMessageDetails() als Parameter übergeben wird.

Method

RESTful Webservices veröffentlichen ihre Schnittstellen durch Uri und das HTTP-Verb. WCF stellt den Zugriff auf das HTTP-Verb, mit dem der Zugriff auf die Schnittstelle erfolgte, durch die Property "Method" des WebInvokeAttribute zur Verfügung. Deshalb stellt folgende Deklaration eine Schnittstelle bereit, die über "PUT" angesprochen wird:

[OperationContract]
[WebInvoke(
    RequestUri = "Message/{messageId}",
    Method = "PUT")]
ChatMessage ModifyMessage(
	string messageId,
	ChatMessage messageToModify);

RequestFormat / ResponseFormat

Diese Properties legen fest, wie die zu übertragenden Objekte serialisiert werden. Die möglichen Werte sind vom Typ WebMessageFormat, also XML oder Javascript Object Notation. Für ersteres wird für die Serialisierung die Klasse DataContractSerializer verwendet, für JSON folgerichtig DataContractJsonSerializer. Das Ergebnis der Serialisierung – und damit der Inhalt der Antwort einer Serviceanfrage – würde zum Beispiel so aussehen:

<chatmessage>
  <messageid>
    f1fe94db-f859-404e-bada-213f296b13a6
  </messageid>
  <time>21.04.2009 12:00:00.0000</time>
  <author>LaTino</author>
  <text>Beispieltext der Nachricht</text>
</chatmessage>

Oder für WebMessageFormat.Json:

{
  "Author":"LaTino",
  "MessageId":"f1fe94db-f859-404e-bada-213f296b13a6",
  "Text":"Beispieltext der Nachricht",
  "Time":"\/Date(1240320060000+0200)\/"
}

Erwähnenswert ist dabei vielleicht, dass durch die Einteilung in RequestFormat und ResponseFormat für die Deserialisierung von eingehenden Objekten durchaus andere Regeln gelten können als für die Serialisierung ausgehender Objekte.

BodyStyle

Dieses Property ist vom Typ WebMessageBodyStyle und legt fest, ob die serialisierten Daten noch einmal als Kindknoten (im Fall von XML) oder als Subobjekt (im Fall von Json) serialisiert werden.

WebMessageBodyStyle.Bare steht dabei für die oben angeführten Serialisierungen, Wrapped für das Wrappen – Bare ist die Voreinstellung, durch Auswahl der WrappedRequest und WrappedResponse-Werte kann diese Eigenschaft also einzeln für Anfragen und Antworten festgelegt werden.

Für eine ChatMessage, die wrapped nach JSON serialisiert wird, ergibt sich im Gegensatz dazu folgender Output:

{
  "GetMessageResult": {
    "Author":"LaTino",
    "MessageId":"f1fe94db-f859-404e-bada-213f296b13a6",
    "Text":"Beispieltext der Nachricht",
    "Time":"\/Date(1240320060000+0200)\/"
  }
}

Ein möglicher Nachteil dieses Formats ist, wie schon zu sehen ist, das mögliche Offenlegen der hinter dem Request stehenden Schnittstelle (hier: GetMessage). Im Beispiel werden wir daher auf das BodyStyle-Attribut verzichten und Nachrichten grundsätzlich unwrapped serialisieren.

Es ist an der Zeit, zu definieren, was für Nachrichten wir eigentlich hin- und herschicken möchten. Dafür benötigen wir eine (sehr einfache) Klasse ChatMessage, die wir mit Hilfe des DataContractAttribute und des DataMemberAttribute so markieren, dass der gewählte DataContractJsonSerializer seine Arbeit tun kann:

[DataContract]
public class ChatMessage
{
    [DataMember] public Guid MessageId { get; set; }
    [DataMember] public DateTime Time { get; set; }
    [DataMember] public string Author { get; set; }
    [DataMember] public string Text { get; set; }
}

Die fertige Schnittstelle unseres Beispieldienstes wird Json für die Kommunikation verwenden und stellt für die Ressource "Message" alle notwendigen Endpunkte mit den im ersten Teil erwähnten vier HTTP-Verben „GET“, „POST“, „PUT“ und „DELETE“ bereit.

[ServiceContract]
public interface IMessageService
{
  [OperationContract]
  [WebInvoke(
	UriTemplate = "Message",
	Method = "GET",
	RequestFormat = WebMessageFormat.Json,
	ResponseFormat = WebMessageFormat.Json)]
  List ListMessages(); 

  [OperationContract]
  [WebInvoke(
	UriTemplate = "Message/{messageId}",
	Method = "GET",
	RequestFormat = WebMessageFormat.Json,
	ResponseFormat = WebMessageFormat.Json)]
  ChatMessage GetMessage(string messageId); 

  [OperationContract]
  [WebInvoke(
	UriTemplate = "Message",
	Method = "POST",
	RequestFormat = WebMessageFormat.Json,
	ResponseFormat = WebMessageFormat.Json)]
  ChatMessage CreateMessage(ChatMessage message); 

  [OperationContract]
  [WebInvoke(
	UriTemplate = "Message/{messageId}",
	Method = "DELETE",
	RequestFormat = WebMessageFormat.Json,
	ResponseFormat = WebMessageFormat.Json)]
  ChatMessage DeleteMessage(string messageId); 

  [OperationContract]
  [WebInvoke(
	UriTemplate = "Message/{messageId}",
	Method = "PUT",
	RequestFormat = WebMessageFormat.Json,
	ResponseFormat = WebMessageFormat.Json)]
  ChatMessage ModifyMessage(
	string messageId,
	ChatMessage messageToModify);
}

Im nächsten Teil schauen wir uns die Implementierung des Service an, und überlegen, wie er am besten veröffentlicht wird.

Bevor wir richtig loslegen – und hoffentlich auch, bevor die ersten „show the code“ brüllen – ein kleines Vorwort.

REST steht für Representational State Transfer, ein Paradigma für den Zugriff auf Services. REST benutzt dabei grundsätzliche, teilweise vernachlässigte Technologien, die unter anderem das HTT-Protokoll zur Verfügung stellt. Der Begriff wurde von Roy Fielding geprägt, der zuvor auch an der Spezifikation von HTTP beteiligt war.
Webservices, die Schnittstellen per REST zur Verfügung stellen (auch RESTful Service genannt), veröffentlichen Daten unter Verwendung sogenannter Ressourcen. Jede Ressource erhält eine eindeutige Adresse (URI). Die durchzuführende Aktion ergibt sich aus der Kombination der URI einer Ressource und der Art und Weise, wie diese URI angesprochen wird.

<p<Im Gegensatz zu RPC (remote procedure call, ein anderes verbreitetes Paradigma) veröffentlichen RESTful Webservices keine Informationen über die Methode, die aufgerufen wird. Die Schnittstellen werden einzig und allein durch die veröffentlichten Ressourcen definiert.

Eine Webservice-Schnittstelle, die mit RPC-Adressierung so angesprochen wird:

http://example.com:8080/MessageService?op=GetMessage&id=7862

würde, wenn der Webservice RESTful ist, so angesprochen werden:

http://example.com/MessageService/Message/7862

HTTP, also das Protokoll, mit dem Webservices kommunizieren, unterstützt verschiedene so genannte „Verben“, die die Art und Weise des Zugriffs spezifizieren. GET und POST sind den meisten Webentwicklern gut bekannt, daneben existieren jedoch noch andere Verben, die sich REST zunutze macht:

• GET: Abruf von Inhalten
• POST: Übertragung von Daten
• HEAD: Anforderung eines reinen HTTP-Headers
• PUT: Aktualisierung von Daten
• DELETE: Löschen von Daten
• TRACE: liefert die Anfrage zurück, die der Server empfangen hat
• OPTIONS: Liste der unterstützten Methoden
• CONNECT: von Proxyservern unterstützt

Üblicherweise benutzen RESTful Webservices die Verben GET (Abruf), PUT (Ändern), POST (erstellen) und DELETE (löschen). Dem Benutzer des Webservice muss also nur mitgeteilt werden, welche Ressourcen zur Verfügung stehen. Abrufen und manipulieren kann er sie dann, indem er sie mit den entsprechenden HTTP-Methoden aufruft.

Folgendes Beispiel mit der Ressource „ChatMessage“ soll das verdeutlichen.

http://example.com:8080/MessageService/ChatMessage
//     POST: erzeugt eine neue Nachricht und liefert ihre URI zurück
//     PUT: kein Effekt
//     DELETE: kein Effekt
//     GET: liefert eine Liste mit Nachrichten

http://example.com:8080/MessageService/ChatMessage/7862
//     POST: kein Effekt
//     PUT: verändert die Nachricht mit der ID 7862
//     DELETE: löscht die Nachricht mit der ID 7862
//     GET: liefert die Nachricht mit der ID 7862

RESTful Webservices erzwingen eine ressourcenorientierte Servicearchitektur. Der Service ist vollkommen entkoppelt von jeglicher Anwendung, er ist leicht adressierbar, vollkommen zustandslos und bietet eine einheitliche, vorhersehbare Schnittstelle für Ressourcen. Im Gegensatz zu „dicken“ RPC-Webservices enthalten die versendeten und empfangenen Nachrichten das absolut notwendige Minimum – Metainformationen wie angesprochene Schnittstelle entfallen komplett. Das macht RESTful Services sowohl flexibler, als auch universeller einsetzbar. Der Client muss lediglich HTTP beherrschen, SOAP-Kommunikationsverträge und dergleichen können entfallen.

Gleichzeitig sind sie spezialisiert auf die Web-Infrastruktur, da sie wesentlich mehr Eigenschaften von HTTP nutzen als RPC. Antworten an den Client können bei „reinen“ RESTful Webservices lediglich aus HTTP-Statuscodes bestehen: 404 dürfte jedem bekannt sein, es existieren allerdings noch etliche andere, die dem Client bei einem Minimum an übertragenen Daten Auskunft über den Erfolg (oder den Grund eines Misserfolgs) einer Aktion geben können.

Wir fassen zusammen:

• schlank
• (dadurch) schnell
• erzwingen Entkopplung
• fördern leicht verständliche Interfaces
• universell abrufbar

Weiter geht’s im nächsten Teil, in dem wir uns heraussuchen, was unser Service machen soll, und die Datenverträge schreiben.