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

Der Windows Communication Foundation (WCF)-WEB-HTTP-Programmiermodell bietet die grundlegenden Elemente, die zum Erstellen von WEB-HTTP-Diensten mit WCF erforderlich.The Windows Communication Foundation (WCF) WEB HTTP programming model provides the basic elements required to build WEB HTTP services with WCF. WCF-WEB-HTTP-Dienste wurden entwickelt, um den Zugriff von vielen möglichen Clients, einschließlich Webbrowsern zugegriffen werden, und weisen folgenden eindeutige Anforderungen:WCF 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. Die WCF-WEB-HTTP-Programmiermodell verwendet die UriTemplate und UriTemplateTable Klassen, die URI-Verarbeitungsfunktionen bereitzustellen.The WCF 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. Die WCF-WEB-HTTP-Programmiermodell verwendet die WebGetAttribute und WebInvokeAttribute auf Dienstvorgänge mit GET und andere HTTP-Verben wie PUT, POST oder DELETE zuzuordnen.The WCF 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. Die WCF-WEB-HTTP-Programmiermodell verwendet die WebHttpBinding und WebHttpBehavior zur Unterstützung von vielen verschiedenen Datenformaten, einschließlich XML-Dokumente, JSON-Datenobjekte und Streams mit Binärdaten wie Bilder, Videodateien oder Klartext.The WCF 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.

Die WCF-WEB-HTTP-Programmiermodell erweitert den Einsatzbereich von WCF Webstil Szenarien abdecken, die WEB-HTTP-Dienste, AJAX- und JSON-Dienste und (ATOM/RSS)-Syndication-Feeds enthalten.The WCF WEB HTTP programming model extends the reach of WCF to cover Web-style scenarios that include WEB HTTP services, AJAX and JSON services, and Syndication (ATOM/RSS) feeds. Weitere Informationen zu AJAX- und JSON-Diensten finden Sie unter AJAX-Integration und JSON-Unterstützung.For more information about AJAX and JSON services, see AJAX Integration and JSON Support. Weitere Informationen zu Syndication, finden Sie unter Übersicht über WCF Syndication.For more information about 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 unter QueryStringConverterFor more information, see QueryStringConverter

Achtung

Mit dem WCF-WEB-HTTP-Programmiermodell geschriebene Dienste verwenden die SOAP-Nachrichten nicht.Services written with the WCF WEB HTTP programming model do not use SOAP messages. Da SOAP nicht verwendet wird, können den Sicherheitsfeatures von WCF nicht verwendet werden.Because SOAP is not used, the security features provided by WCF 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 zu WCF-Sicherheit, finden Sie unter Sicherheit (Übersicht)For more information about WCF 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 unter IIS und WebDavFor more information, see 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. Dies ist zugeordnet keinen bestimmten Netzwerkstapel (WCF enthalten), damit Sie es allen erforderlichen verwenden können.This is not affiliated with any particular networking stack (WCF included) so you can use it wherever necessary.

Das WCF-Dienstmodell verwendet UriTemplate und UriTemplateTable, um Dienstvorgänge mit einem Satz URIs zu verknüpfen, die durch eine UriTemplate beschrieben werden.The WCF 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 zu UriTemplate und UriTemplateTable, finden Sie unter UriTemplate und UriTemplateTableFor more information about UriTemplate and UriTemplateTable, see UriTemplate and UriTemplateTable

WebGet- und WebInvoke-AttributeWebGet and WebInvoke Attributes

WCF-WEB-HTTP-Dienste stellen Verwendung von Verben (z. B. HTTP GET) neben den verschiedenen aufrufverben (beispielsweise HTTP POST, PUT und DELETE).WCF 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). Die WCF-WEB-HTTP-Programmiermodell ermöglicht Entwicklern-Steuerelement der sowohl die URI-Vorlage und mit Dienstvorgängen verknüpfte Verb mithilfe der WebGetAttribute und WebInvokeAttribute.The WCF 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 );  
}  

Ein vollständiges Beispiel eines WCF-Diensts, der den WCF-WEB-HTTP-Programmiermodell verwendet, finden Sie unter Vorgehensweise: Erstellen einer grundlegenden WCF-Web-HTTP-DienstsTo see a complete sample of a WCF service that uses the WCF 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

Die WCF-WEB-HTTP-Programmiermodell hat neue Funktionen, mit vielen verschiedenen Datenformaten ermöglichen.The WCF 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

Dies bedeutet, dass der WCF-WEB-HTTP-Programmiermodell kann jeden Datentyp verarbeiten, aber Sie möglicherweise Programmieren Stream.This means the WCF 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 zu diesen Funktionen finden Sie unter WCF Web-HTTP-FormatierungÜbersicht über WCF Syndication und AJAX-Integration und JSON-Unterstützung.For more information about 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 die WCF-WEB-HTTP-Programmiermodell die WS-nicht unterstützt *-Protokolle, die einzige Möglichkeit, einen WCF-WEB-HTTP-Dienst sichern ist, um den Dienst über HTTPS mit SSL verfügbar zu machen.Because the WCF WEB HTTP programming model does not support the WS-* protocols, the only way to secure a WCF WEB HTTP service is to expose the service over HTTPS using SSL. Weitere Informationen zum Einrichten von SSL mit IIS 7.0IIS 7.0, finden Sie unter Gewusst wie: Implementieren von SSL auf IISFor more information about 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