Überblick über WCF-Web-HTTP-ProgrammiermodelleWCF Web HTTP Programming Model Overview

Das WEB-HTTP-Programmiermodell in Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) stellt die grundlegenden Elemente zur Erstellung von WEB-HTTP-Diensten mit WCFWCF bereit.The Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) WEB HTTP programming model provides the basic elements required to build WEB HTTP services with WCFWCF. WEB-HTTP-Dienste in WCFWCF wurden für den Zugriff von vielen möglichen Clients aus entwickelt, einschließlich Webbrowsern, und weisen folgende eindeutige Anforderungen auf:WCFWCF WEB HTTP services are designed to be accessed by the widest range of possible clients, including Web browsers and have the following unique requirements:

  • URIs und URI-Verarbeitung URIs spielen eine zentrale Rolle in den Entwurf WEB-HTTP-Dienste.URIs and URI Processing URIs play a central role in the design of WEB HTTP services. Das WCF-Webprogrammiermodell in WCFWCF verwendet die UriTemplate-Klasse und die UriTemplateTable-Klasse, um URI-Verarbeitungsfunktionen bereitzustellen.The WCFWCF WEB HTTP programming model uses the UriTemplate and UriTemplateTable classes to provide URI processing capabilities.

  • Unterstützung für GET und Post-ANFORDERUNGEN WEB-HTTP-Dienste machen die Verwendung von GET-Verb für den Datenabruf von, zusätzlich zu den verschiedenen aufrufverben für datenbearbeitung und Remoteaufrufe.Support for GET and POST operations WEB HTTP services make use of the GET verb for data retrieval, in addition to various invoke verbs for data modification and remote invocation. Das Webprogrammiermodell in WCFWCF verwendet die WebGetAttribute- und WebInvokeAttribute-Attribute, um Dienstoperationen sowohl das GET-Verb als auch andere HTTP-Verben wie PUT, POST oder DELETE zuzuordnen.The WCFWCF WEB HTTP programming model uses the WebGetAttribute and WebInvokeAttribute to associate service operations with both GET and other HTTP verbs like PUT, POST, and DELETE.

  • Mehrere Datenformate Webdienste viele Arten von Daten, zusätzlich zu SOAP-Nachrichten zu verarbeiten.Multiple data formats Web-style services process many kinds of data in addition to SOAP messages. Im WEB-HTTP-Programmiermodell von WCFWCF 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.The WCFWCF WEB HTTP programming model uses the WebHttpBinding and WebHttpBehavior to support many different data formats including XML documents, JSON data object, and streams of binary content such as images, video files, or plain text.

Das WEB-HTTP-Programmiermodell von WCFWCF erweitert den Einsatzbereich von WCFWCF um Webszenarien, wie beispielsweise WEB-HTTP-Dienste, AJAX- und JSON-Dienste sowie Syndication-Feeds (ATOM/RSS).The WCFWCF WEB HTTP programming model extends the reach of WCFWCF to cover Web-style scenarios that include WEB HTTP services, AJAX and JSON services, and Syndication (ATOM/RSS) feeds. Weitere Informationen finden Sie unterFor more information aboutAJAX- und JSON-Dienste finden Sie unter AJAX-Integration und JSON-Unterstützung. AJAX and JSON services, see AJAX Integration and JSON Support. Weitere Informationen finden Sie unterFor more information aboutSyndication finden Sie unter Übersicht über WCF Syndication. Syndication, see WCF Syndication Overview.

Es gibt keine zusätzlichen Einschränkungen bei den Datentypen, die von einem WEB-HTTP-Dienst zurückgegeben werden können.There are no extra restrictions on the types of data that can be returned from a WEB HTTP service. Jeder serialisierbare Typ kann von einem WEB-HTTP-Dienstvorgang zurückgegeben werden.Any serializable type can be returned from an WEB HTTP service operation. 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.Because WEB HTTP service operations can be invoke by a web browser there is a limitation on what data types can be specified in a URL. Welche Typen standardmäßig unterstützt werden weitere Informationen finden Sie unter der UriTemplate-Abfragezeichenfolgenparameter und URLs Abschnitt weiter unten.For more information on what types are supported by default see the UriTemplate Query String Parameters and URLs section below. 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.The default behavior can be changed by providing your own T:System.ServiceModel.Dispatcher.QueryStringConverter implementation which specifies how to convert the parameters specified in a URL to the actual parameter type. Weitere Informationen finden Sie unterFor more information, see QueryStringConverter QueryStringConverter

Achtung

Im WEB-HTTP-Programmiermodell von WCFWCF geschriebene Dienste verwenden keine SOAP-Nachrichten.Services written with the WCFWCF WEB HTTP programming model do not use SOAP messages. Da SOAP nicht verwendet wird, können die von WCFWCF bereitgestellten Sicherheitsfunktionen nicht genutzt werden.Because SOAP is not used, the security features provided by WCFWCF cannot be used. Sie können jedoch transportbasierte Sicherheit verwenden, indem Sie den Dienst mit HTTPS hosten.You can, however use transport-based security by hosting your service with HTTPS. Weitere Informationen finden Sie unterFor more information aboutWCFWCF Sicherheit, finden Sie unter Sicherheit (Übersicht) WCFWCF security, see Security Overview

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.Installing the WebDAV extension for IIS can cause Web HTTP services to return an HTTP 405 error as the WebDAV extension attempts to handle all PUT requests. Um dieses Problem zu umgehen, können Sie die WebDAV-Erweiterung deinstallieren oder für Ihre Website deaktivieren.To work around this issue you can uninstall the WebDAV extension or disable the WebDAV extension for your web site. Weitere Informationen finden Sie unterFor more information, seeIIS und WebDav IIS and WebDav

URI-Verarbeitung mit UriTemplate und UriTemplateTableURI Processing with UriTemplate and UriTemplateTable

URI-Vorlagen stellen eine rationelle Syntax zur Angabe großer Sätze strukturell ähnlicher URIs bereit.URI templates provide an efficient syntax for expressing large sets of structurally similar URIs. 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}/cFor example, the following template expresses the set of all three-segment URIs that begin with "a" and end with "c" without regard to the value of the intermediate segment: a/{segment}/c

Diese Vorlage beschreibt URIs wie die Folgenden:This template describes URIs like the following:

  • a/x/ca/x/c

  • a/y/ca/y/c

  • a/z/ca/z/c

  • und so weiter.and so on.

In dieser Vorlage gibt die Notation mit geschweiften Klammern ("{segment}") ein variables Segment statt eines Literalwerts an.In this template, the curly brace notation ("{segment}") indicates a variable segment instead of a literal value.

.NET Framework stellt eine API mit dem Namen UriTemplate zum Arbeiten mit URI-Vorlagen bereit..NET Framework provides an API for working with URI templates called UriTemplate. Mit UriTemplates können Sie Folgendes ausführen:UriTemplates allow you to do the following:

  • Rufen Sie eine der der Bind Methoden mit einer Reihe von Parametern zum Erstellen einer vollständig geschlossenen URI , die mit die Vorlage übereinstimmt.You can call one of the Bind methods with a set of parameters to produce a fully-closed URI that matches the template. Dies bedeutet, dass alle Variablen innerhalb der URI-Vorlage durch Istwerte ersetzt werden.This means all variables within the URI template are replaced with actual values.

  • 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.You can call Match() with a candidate URI, which uses a template to break up a candidate URI into its constituent parts and returns a dictionary that contains the different parts of the URI labeled according to the variables in the template.

  • Bind() und Match() sind Gegenstücke, sodass Sie Match( Bind( x ) ) aufrufen können und wieder zur Ausgangsumgebung zurückkehren.Bind() and Match() are inverses so that you can call Match( Bind( x ) ) and come back with the same environment you started with.

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.There are many times (especially on the server, where dispatching a request to a service operation based on the URI is necessary) that you want to keep track of a set of UriTemplate objects in a data structure that can independently address each of the contained templates. 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.UriTemplateTable represents a set of URI templates and selects the best match given a set of templates and a candidate URI. Da diese Methode an keinen bestimmten Netzwerkstapel (einschließlich WCFWCF) gebunden ist, können Sie sie an allen erforderlichen Positionen einsetzen.This is not affiliated with any particular networking stack (WCFWCF included) so you can use it wherever necessary.

Das Dienstmodell in WCFWCF verwendet UriTemplate und UriTemplateTable, um Dienstvorgänge mit einer Reihe von URIs zu verknüpfen, die durch ein UriTemplate-Objekt beschrieben werden.The WCFWCF Service Model makes use of UriTemplate and UriTemplateTable to associate service operations with a set of URIs described by a UriTemplate. Ein Dienstvorgang wird mithilfe von UriTemplate oder WebGetAttribute mit einer WebInvokeAttribute verknüpft.A service operation is associated with a UriTemplate, using either the WebGetAttribute or the WebInvokeAttribute. Weitere Informationen finden Sie unterFor more information aboutUriTemplate und UriTemplateTable, finden Sie unter UriTemplate und UriTemplateTable UriTemplate and UriTemplateTable, see UriTemplate and UriTemplateTable

WebGet- und WebInvoke-AttributeWebGet and WebInvoke Attributes

WEB-HTTP-Dienste in WCFWCF nutzen neben den verschiedenen Aufrufverben (beispielsweise HTTP POST, PUT oder DELETE) Verben zum Abruf von Daten (z. B. WEB-HTTP).WCFWCF WEB HTTP services make use of retrieval verbs (for example HTTP GET) in addition to various invoke verbs (for example HTTP POST, PUT, and DELETE). Das WCFWCF-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.The WCFWCF WEB HTTP programming model allows service developers to control the both the URI template and verb associated with their service operations with the WebGetAttribute and WebInvokeAttribute. 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.The WebGetAttribute and the WebInvokeAttribute allow you to control how individual operations get bound to URIs and the HTTP methods associated with those URIs. Beispielsweise durch Hinzufügen von WebGetAttribute und WebInvokeAttribute im folgenden Code.For example, adding WebGetAttribute and WebInvokeAttribute in the following 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.The preceding code allows you to make the following HTTP requests.

GET /GetCustomer

POST /UpdateCustomerName

Für WebInvokeAttribute wird standardmäßig POST eingesetzt, aber Sie können das Attribut auch für andere Verben verwenden.WebInvokeAttribute defaults to POST but you can use it for other verbs too.

[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 );  
}  

Um ein vollständiges Beispiel finden Sie unter eine WCFWCF Dienst, verwendet der WCFWCF WEB-HTTP-Programmiermodell, finden Sie unter wie: Erstellen einer grundlegenden WCF-Web-HTTP-DienstsTo see a complete sample of a WCFWCF service that uses the WCFWCF WEB HTTP programming model, see How to: Create a Basic WCF Web HTTP Service

UriTemplate-Abfragezeichenfolgenparameter und URLsUriTemplate Query String Parameters and URLs

Webdienste können aus einem Webbrowser heraus aufgerufen werden, indem eine URL eingegeben wird, die mit einem Dienstvorgang verknüpft ist.Web-style services can be called from a Web browser by typing a URL that is associated with a service operation. Diese Dienstvorgänge verarbeiten möglicherweise Abfragezeichenfolgenparameter, die in Form einer Zeichenfolge innerhalb der URL angegeben werden müssen.These service operations may take query string parameters that must be specified in a string form within the URL. In der folgenden Tabelle sind die Typen, die innerhalb einer URL übergeben werden können, und das hierfür verwendete Format aufgeführt.The following table shows the types that can be passed within a URL and the format used.

TypType FormatFormat
Byte 0 - 2550 - 255
SByte -128 - 127-128 - 127
Int16 -32768 - 32767-32768 - 32767
Int32 -2,147,483,648 - 2,147,483,647-2,147,483,648 - 2,147,483,647
Int64 -9,223,372,036,854,775,808 - 9,223,372,036,854,775,807-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807
UInt16 0 - 655350 - 65535
UInt32 0 - 4,294,967,2950 - 4,294,967,295
UInt64 0 - 18,446,744,073,709,551,6150 - 18,446,744,073,709,551,615
Single -3.402823e38 - 3.402823e38 (Exponentennotation nicht erforderlich)-3.402823e38 - 3.402823e38 (exponent notation is not required)
Double -1.79769313486232e308 - 1.79769313486232e308 (Exponentennotation nicht erforderlich)-1.79769313486232e308 - 1.79769313486232e308 (exponent notation is not required)
Char Ein beliebiges einzelnes ZeichenAny single character
Decimal Eine beliebige Dezimalzahl in Standardnotation (kein Exponent)Any decimal in standard notation (no exponent)
Boolean True oder False (Groß-/Kleinschreibung wird nicht berücksichtigt)True or False (case insensitive)
String Beliebige Zeichenfolge (leere Zeichenfolgen werden nicht unterstützt, und es werden keine Escapezeichen hinzugefügt)Any string (null string is not supported and no escaping is done)
DateTime MM/TT/JJJJMM/DD/YYYY

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

Monat Tag JahrMonth Day Year

Monatstag Jahr hh: mm: [Uhr | PM]Month Day Year HH:MM:SS [AM|PM]
TimeSpan TT.HH:MM:SSDD.HH:MM:SS

Wobei TT = Tage, HH = Stunden, MM = Minuten, SS = SekundenWhere DD = Days, HH = Hours, MM = minutes, SS = Seconds
Guid Ein GUID, beispielsweise:A GUID, for example:

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

Wobei TT = Tage, HH = Stunden, MM = Minuten, SS = SekundenWhere DD = Days, HH = Hours, MM = minutes, SS = Seconds
EnumerationenEnumerations Beispielsweise der Enumerationswert, der die Enumeration definiert, wie im folgenden Code gezeigt.The enumeration value for example, which defines the enumeration as shown in the following code.

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.Any of the individual enumeration values (or their corresponding integer values) may be specified in the query string.
Typen, die über ein TypeConverterAttribute verfügen, mit dem der Typ in eine Zeichenfolgendarstellung bzw. aus einer Zeichenfolgendarstellung konvertiert werden kann.Types that have a TypeConverterAttribute that can convert the type to and from a string representation. Hängt vom Typkonverter ab.Depends on the Type Converter.

Formate und das WCF-WEB-HTTP-ProgrammiermodellFormats and the WCF WEB HTTP Programming Model

Das WEB-HTTP-Programmiermodell in WCFWCF umfasst neue Funktionen, die die Verwendung von vielen verschiedenen Datenformaten ermöglichen.The WCFWCF WEB HTTP programming model has new features to work with many different data formats. Auf der Bindungsebene kann WebHttpBinding die folgenden anderen Arten von Daten lesen und schreiben:At the binding layer, the WebHttpBinding can read and write the following different kinds of data:

  • XMLXML

  • JSONJSON

  • Nicht transparente binäre StreamsOpaque binary streams

Das heißt, dass das WEB-HTTP-Programmiermodell in WCFWCF jeden Datentyp verarbeiten kann, aber unter Umständen die Programmierung mit Stream erfordert.This means the WCFWCF WEB HTTP programming model can handle any type of data but, you may be programming against Stream.

.NET Framework 3,5.NET Framework 3.5 stellt Unterstützung für JSON-Daten (AJAX) sowie Syndication-Feeds (einschließlich ATOM und RSS) bereit. provides support for JSON data (AJAX) as well as Syndication feeds (including ATOM and RSS). Weitere Informationen finden Sie unterFor more information aboutDiese Funktionen finden Sie unter WCF Web-HTTP-FormatierungÜbersicht über WCF Syndication und AJAX-Integration und JSON-Unterstützung. these features, see WCF Web HTTP FormattingWCF Syndication Overview and AJAX Integration and JSON Support.

WCF-WEB-HTTP-Programmiermodell und SicherheitWCF WEB HTTP Programming Model and Security

Da das WEB-HTTP-Programmiermodell in WCFWCF die WS--Protokolle nicht unterstützt, ist die einzige Möglichkeit zur Absicherung eines WEB-HTTP-Diensts in WCFWCF das Verfügbarmachen des Diensts über HTTPS mithilfe von SSL.Because the WCFWCF WEB HTTP programming model does not support the WS- protocols, the only way to secure a WCFWCF WEB HTTP service is to expose the service over HTTPS using SSL. Weitere Informationen finden Sie unterFor more information aboutEinrichten von SSL mit IIS 7.0IIS 7.0, finden Sie unter Gewusst wie: Implementieren von SSL auf IIS setting up SSL with IIS 7.0IIS 7.0, see How to implement SSL in IIS

Fehlerbehebung im WCF-WEB-HTTP-ProgrammiermodellTroubleshooting the WCF WEB HTTP Programming Model

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.When calling WCF WEB HTTP services using a ChannelFactoryBase<TChannel> to create a channel, the WebHttpBehavior uses the EndpointAddress set in the configuration file even if a different EndpointAddress is passed to the ChannelFactoryBase<TChannel>.

Siehe auchSee Also

WCF SyndicationWCF Syndication
Objektmodell für WCF-Web-HTTP-ProgrammierungWCF Web HTTP Programming Object Model
WCF-Web-HTTP-ProgrammiermodellWCF Web HTTP Programming Model