Überblick über WCF-Web-HTTP-Programmiermodelle

  • Artikel

Das WEB-HTTP-Programmiermodell in Windows Communication Foundation (WCF) stellt die grundlegenden Elemente zur Erstellung von WEB-HTTP-Diensten mit WCF bereit. WEB-HTTP-Dienste in WCF wurden für den Zugriff von vielen möglichen Clients aus entwickelt, einschließlich Webbrowsern, und weisen folgende eindeutige Anforderungen auf:

  • URIs und URI-Verarbeitung: URIs spielen eine zentrale Rolle in der Entwicklung von WEB-HTTP-Diensten. Das WCF-Webprogrammiermodell in WCF verwendet die UriTemplate-Klasse 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 Webprogrammiermodell in WCF verwendet die WebGetAttribute- und WebInvokeAttribute-Attribute, 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 Klartext.

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 über zu AJAX- und JSON-Diensten finden Sie unter AJAX-Integration und JSON-Unterstützung. Weitere Informationen über zur Syndication finden Sie unter Ü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 Abschnitt UriTemplate-Abfragezeichenfolgenparameter und URLs weiter unten. 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

Bb412172.Caution(de-de,VS.100).gifVorsicht:
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 über die Sicherheit in WCF finden Sie unter Sicherheitsübersicht

Bb412172.Warning(de-de,VS.100).gif Vorsicht:
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

  • und so weiter.

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 die folgenden Aktionen 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 Dienstmodell in WCF verwendet UriTemplate und UriTemplateTable, um Dienstvorgänge mit einer Reihe von URIs zu verknüpfen, die durch ein UriTemplate-Objekt beschrieben werden. Ein Dienstvorgang wird mithilfe von WebGetAttribute oder WebInvokeAttribute mit einer UriTemplate verknüpft. Weitere Informationen über zu UriTemplate und UriTemplateTable erhalten Sie unter UriTemplate und UriTemplateTable.

WebGet- und WebInvoke-Attribute

WEB-HTTP-Dienste in WCF nutzen neben den verschiedenen Aufrufverben (beispielsweise HTTP POST, PUT oder DELETE) Verben zum Abruf von Daten (z. B. WEB-HTTP). Das WCF-WEB-HTTP-Programmiermodell ermöglicht den Entwicklern von Diensten, sowohl die URI-Vorlage als auch das mit den Dienstvorgängen verknüpfte Verb mithilfe von WebGetAttribute und WebInvokeAttribute festzulegen. 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 vorhergehende Code ermöglicht 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 eines WCF-Diensts, der das WCF-WEB-HTTP-Programmiermodell verwendet finden Sie unter Vorgehensweise: 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 beliebiges 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 in WCF umfasst neue Funktionen, die die Verwendung von vielen verschiedenen Datenformaten ermöglichen. Auf der Bindungsebene kann WebHttpBinding die folgenden anderen Arten von Daten lesen und schreiben:

  • XML

  • JSON

  • Nicht transparente binäre Streams

Das heißt, dass das WEB-HTTP-Programmiermodell in WCF jeden Datentyp verarbeiten kann, aber unter Umständen die Programmierung mit Stream erfordert.

.NET Framework 3.5 stellt Unterstützung für JSON-Daten (AJAX) sowie Syndication-Feeds (einschließlich ATOM und RSS) bereit. Weitere Informationen über zu diesen Funktionen 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 in WCF die WS-*-Protokolle nicht unterstützt, ist die einzige Möglichkeit zur Absicherung eines WEB-HTTP-Diensts in WCF das Verfügbarmachen des Diensts über HTTPS mithilfe von SSL. Weitere Informationen über zum Einrichten von SSL in IIS 7.0 finden Sie unter So implementieren Sie SSL in IIS

Fehlerbehebung im WCF-WEB-HTTP-Programmiermodell

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

Siehe auch

Konzepte

Objektmodell für WCF-Web-HTTP-Programmierung

Weitere Ressourcen

WCF Syndication
WCF-Web-HTTP-Programmiermodell