Freigeben über


Überblick über WCF-Web-HTTP-Programmiermodelle

Das Web-HTTP-Programmiermodell der Windows Communication Foundation (WCF) stellt die grundlegenden Elemente bereit, die zur Erstellung von Web-HTTP-Diensten mit WCF erforderlich sind. Web-HTTP-Dienste von WCF wurden für den Zugriff über eine möglichst breite Vielfalt von Clients (einschließlich Webbrowsern) entwickelt und weisen folgende besondere Anforderungen auf:

  • URIs und URI-Verarbeitung: URIs spielen bei der Entwicklung von Web-HTTP-Diensten eine zentrale Rolle. Das Web-HTTP-Programmiermodell von WCF verwendet die UriTemplate- und die UriTemplateTable-Klasse, um URI-Verarbeitungsfunktionen bereitzustellen.

  • Unterstützung für GET- und POST-Operationen: Web-HTTP-Dienste nutzen neben den verschiedenen Aufrufverben für Datenbearbeitung und Remoteaufrufe das GET-Verb für den Datenabruf. Das Web-HTTP-Programmiermodell von WCF verwendet WebGetAttribute und WebInvokeAttribute, um Dienstoperationen sowohl das GET-Verb als auch andere HTTP-Verben wie PUT, POST oder DELETE zuzuordnen.

  • Mehrere Datenformate: Webdienste verarbeiten zusätzlich zu SOAP-Nachrichten viele weitere Arten von Daten. Im Web-HTTP-Programmiermodell von WCF werden durch den Einsatz von WebHttpBinding und WebHttpBehavior viele verschiedene Datenformate unterstützt. Hierzu gehören XML-Dokumente, JSON-Datenobjekte und Streams mit Binärdaten wie z. B. Bilder, Videodateien oder Nur-Text.

Das Web-HTTP-Programmiermodell von WCF erweitert den Einsatzbereich von WCF um Webszenarien wie beispielsweise Web-HTTP-Dienste, AJAX- und JSON-Dienste sowie Syndication-Feeds (ATOM/RSS). Weitere Informationen zu AJAX- und JSON-Diensten finden Sie unter AJAX-Integration und JSON-Unterstützung. Weitere Informationen zu Syndication finden Sie in der Übersicht über WCF Syndication.

Es gibt keine zusätzlichen Einschränkungen bei den Datentypen, die von einem WEB-HTTP-Dienst zurückgegeben werden können. Jeder serialisierbare Typ kann von einem WEB-HTTP-Dienstvorgang zurückgegeben werden. Da WEB-HTTP-Dienstvorgänge durch einen Webbrowser aufgerufen werden können, gibt es eine Einschränkung in Bezug auf Datentypen, die in einer URL angegeben werden können. Weitere Informationen zu den standardmäßig unterstützten Typen finden Sie im nachfolgenden Abschnitt UriTemplate-Abfragezeichenfolgenparameter und URLs. Das Standardverhalten kann geändert werden, indem eine eigene T:System.ServiceModel.Dispatcher.QueryStringConverter-Implementierung bereitgestellt wird, die angibt, wie die in einer URL angegebenen Parameter in den tatsächlichen Parametertyp konvertiert werden. Weitere Informationen finden Sie unter QueryStringConverter.

Achtung

Im Web-HTTP-Programmiermodell von WCF geschriebene Dienste verwenden keine SOAP-Nachrichten. Da SOAP nicht verwendet wird, können die von WCF bereitgestellten Sicherheitsfunktionen nicht genutzt werden. Sie können jedoch transportbasierte Sicherheit verwenden, indem Sie den Dienst mit HTTPS hosten. Weitere Informationen zur WCF-Sicherheit finden Sie in der Sicherheitsübersicht.

Warnung

Die Installation der WebDAV-Erweiterung für IIS kann dazu führen, dass Web-HTTP-Dienste den HTTP-Fehler 405 zurückgeben, da die WebDAV-Erweiterung versucht, alle PUT-Anforderungen zu verarbeiten. Um dieses Problem zu umgehen, können Sie die WebDAV-Erweiterung deinstallieren oder für Ihre Website deaktivieren. Weitere Informationen finden Sie unter IIS und WebDav.

URI-Verarbeitung mit UriTemplate und UriTemplateTable

URI-Vorlagen stellen eine rationelle Syntax zur Angabe großer Sätze strukturell ähnlicher URIs bereit. Beispielsweise wird mit der folgenden Vorlage der Satz aller aus drei Segmenten bestehenden URIs angegeben, die mit "a" beginnen, mit "c" enden und im mittleren Segment einen beliebigen Wert enthalten können: a/{segment}/c

Diese Vorlage beschreibt URIs wie die Folgenden:

  • a/x/c

  • a/y/c

  • a/z/c

  • usw.

In dieser Vorlage gibt die Notation mit geschweiften Klammern ("{segment}") ein variables Segment statt eines Literalwerts an.

.NET Framework stellt eine API mit dem Namen UriTemplate zum Arbeiten mit URI-Vorlagen bereit. Mit UriTemplates können Sie Folgendes ausführen:

  • Sie können eine der Bind-Methoden mit einem Satz von Parametern aufrufen, um einen der Vorlage entsprechenden vollständig geschlossenen URI zu erzeugen. Dies bedeutet, dass alle Variablen innerhalb der URI-Vorlage durch Istwerte ersetzt werden.

  • Sie können Match() mit einem potenziellen URI aufrufen. Diese Methode schlüsselt den potenziellen URI mithilfe einer Vorlage in seine Bestandteile auf und gibt ein Wörterbuch zurück, in dem die verschiedenen URI-Teile mit den zugehörigen Variablen aus der Vorlage verzeichnet sind.

  • Bind() und Match() sind Gegenstücke, sodass Sie Match( Bind( x ) ) aufrufen können und wieder zur Ausgangsumgebung zurückkehren.

Es ist häufig wünschenswert (insbesondere auf dem Server, wo es erforderlich ist, eine Anforderung basierend auf dem URI an einen Dienstvorgang weiterzuleiten), einen Satz von UriTemplate-Objekten in einer Datenstruktur zu verfolgen, die unabhängig voneinander die einzelnen darin enthaltenen Vorlagen darstellen können. UriTemplateTable stellt einen Satz von URI-Vorlagen dar und wählt aus einem gegebenen Vorlagensatz die beste Übereinstimmung für den zu prüfenden URI aus. Da diese Methode an keinen bestimmten Netzwerkstapel (einschließlich WCF) gebunden ist, können Sie sie an allen erforderlichen Positionen einsetzen.

Das WCF-Dienstmodell verwendet UriTemplate und UriTemplateTable, um Dienstvorgänge mit einem Satz URIs zu verknüpfen, die durch eine UriTemplate beschrieben werden. Ein Dienstvorgang wird mithilfe von UriTemplate oder WebGetAttribute mit einer WebInvokeAttribute verknüpft. Weitere Informationen zu UriTemplate und UriTemplateTable finden Sie unter UriTemplate und UriTemplateTable.

WebGet- und WebInvoke-Attribute

Web-HTTP-Dienste von WCF nutzen neben den verschiedenen Aufrufverben (beispielsweise HTTP POST, PUT oder DELETE) Verben zum Abruf von Daten (z. B. WEB-HTTP). Über das Web-HTTP-Programmiermodell von WCF können Entwickler*innen von Diensten sowohl die URI-Vorlage als auch das mit den Dienstvorgängen verknüpfte Verb mithilfe von WebGetAttribute und WebInvokeAttribute steuern. Mit WebGetAttribute und WebInvokeAttribute können Sie steuern, wie einzelne Vorgänge an die URIs und die mit diesen URIs verknüpften HTTP–Methoden gebunden werden. Beispielsweise durch Hinzufügen von WebGetAttribute und WebInvokeAttribute im folgenden Code.

[ServiceContract]
interface ICustomer
{
  //"View It"

  [WebGet]
  Customer GetCustomer():

  //"Do It"
    [WebInvoke]
  Customer UpdateCustomerName( string id,
                               string newName );
}

Der vorangehende Code ermöglicht es Ihnen, die folgenden HTTP-Anforderungen zu formulieren.

GET /GetCustomer

POST /UpdateCustomerName

Für WebInvokeAttribute wird standardmäßig POST eingesetzt, aber Sie können das Attribut auch für andere Verben verwenden.

[ServiceContract]
interface ICustomer
{
  //"View It" -> HTTP GET
    [WebGet( UriTemplate="customers/{id}" )]
  Customer GetCustomer( string id ):

  //"Do It" -> HTTP PUT
  [WebInvoke( UriTemplate="customers/{id}", Method="PUT" )]
  Customer UpdateCustomer( string id, Customer newCustomer );
}

Ein vollständiges Beispiel für einen WCF-Dienst, der das Web-HTTP-Programmiermodell von WCF verwendet, finden Sie unter Gewusst wie: Erstellen eines grundlegenden WCF-Web-HTTP-Diensts.

UriTemplate-Abfragezeichenfolgenparameter und URLs

Webdienste können aus einem Webbrowser heraus aufgerufen werden, indem eine URL eingegeben wird, die mit einem Dienstvorgang verknüpft ist. Diese Dienstvorgänge verarbeiten möglicherweise Abfragezeichenfolgenparameter, die in Form einer Zeichenfolge innerhalb der URL angegeben werden müssen. In der folgenden Tabelle sind die Typen, die innerhalb einer URL übergeben werden können, und das hierfür verwendete Format aufgeführt.

Typ Format
Byte 0–255
SByte -128 - 127
Int16 -32768 - 32767
Int32 -2,147,483,648 - 2,147,483,647
Int64 -9,223,372,036,854,775,808 - 9,223,372,036,854,775,807
UInt16 0 - 65535
UInt32 0 - 4,294,967,295
UInt64 0 - 18,446,744,073,709,551,615
Single -3.402823e38 - 3.402823e38 (Exponentennotation nicht erforderlich)
Double -1.79769313486232e308 - 1.79769313486232e308 (Exponentennotation nicht erforderlich)
Char Ein einzelnes Zeichen
Decimal Eine beliebige Dezimalzahl in Standardnotation (kein Exponent)
Boolean True oder False (Groß-/Kleinschreibung wird nicht berücksichtigt)
String Beliebige Zeichenfolge (leere Zeichenfolgen werden nicht unterstützt, und es werden keine Escapezeichen hinzugefügt)
DateTime MM/TT/JJJJ

MM/TT/JJJJ HH:MM:SS [AM|PM]

Monat Tag Jahr

Monat Tag Jahr HH:MM:SS [AM|PM]
TimeSpan TT.HH:MM:SS

Wobei TT = Tage, HH = Stunden, MM = Minuten, SS = Sekunden
Guid Ein GUID, beispielsweise:

936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset MM/TT/JJJJ HH:MM:SS MM:SS

Wobei TT = Tage, HH = Stunden, MM = Minuten, SS = Sekunden
Enumerationen Beispielsweise der Enumerationswert, der die Enumeration definiert, wie im folgenden Code gezeigt.

public enum Days{ Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday };

Jeder der einzelnen Enumerationswerte (bzw. der entsprechenden ganzzahligen Werte) kann in der Abfragezeichenfolge angegeben werden.
Typen, die über ein TypeConverterAttribute verfügen, mit dem der Typ in eine Zeichenfolgendarstellung bzw. aus einer Zeichenfolgendarstellung konvertiert werden kann. Hängt vom Typkonverter ab.

Formate und das WCF-WEB-HTTP-Programmiermodell

Das Web-HTTP-Programmiermodell von WCF umfasst neue Features, die die Verwendung vieler verschiedener Datenformate ermöglichen. Auf der Bindungsebene kann WebHttpBinding die folgenden anderen Arten von Daten lesen und schreiben:

  • XML

  • JSON

  • Nicht transparente binäre Streams

Daher kann das Web-HTTP-Programmiermodell von WCF jeden Datentyp verarbeiten, erfordert aber unter Umständen die Programmierung mit Stream.

.NET Framework 3.5 stellt Unterstützung für JSON-Daten (AJAX) sowie Syndication-Feeds (einschließlich ATOM und RSS) bereit. Weitere Informationen zu diesen Features finden Sie unter WCF-Web-HTTP-Formatierung, Übersicht über WCF Syndication und AJAX-Integration und JSON-Unterstützung.

WCF-WEB-HTTP-Programmiermodell und Sicherheit

Da das Web-HTTP-Programmiermodell von WCF die WS-*-Protokolle nicht unterstützt, ist die einzige Möglichkeit zur Absicherung eines Web-HTTP-Diensts von WCF das Verfügbarmachen des Diensts über HTTPS mithilfe von SSL. Weitere Informationen zum Einrichten von SSL mit IIS 7.0 finden Sie unter Implementieren von SSL in IIS.

Fehlerbehebung im WCF-WEB-HTTP-Programmiermodell

Beim Aufrufen der WCF-WEB-HTTP-Dienste mit einer ChannelFactoryBase<TChannel> zur Erstellung eines Kanals verwendet das WebHttpBehavior den EndpointAddress-Satz in der Konfigurationsdatei, selbst wenn eine andere EndpointAddress an die ChannelFactoryBase<TChannel> weitergegeben wird.

Siehe auch