WCF REST Programming Object Model

The WCF REST Programming Model allows developers to expose Windows Communication Foundation (WCF) Web services through basic HTTP requests without requiring SOAP. The WCF REST Programming Model is built on top of the existing WCF extensibility model. It defines the following classes:

Programming Model:

• WebGetAttribute

• WebInvokeAttribute

• WebServiceHost

Channels and Dispatcher Infrastructure:

• WebHttpBinding

• WebHttpBehavior

Utility Classes and Extensibility Points:

• UriTemplate

• UriTemplateTable

• QueryStringConverter

• WebHttpDispatchOperationSelector

WebGetAttribute

The WebGetAttribute attribute is used to mark a service operation as one that responds to HTTP GET requests. It is a passive operation behavior (the IOperationBehavior methods do nothing) that adds metadata to the operation description. Applying the WebGetAttribute has no effect unless a behavior that looks for this metadata in the operation description (specifically, the WebHttpBehavior) is added to the service's behavior collection. The WebGetAttribute attribute takes the optional parameters in the following table.

WebHttpBinding

The WebHttpBinding incorporates support for XML, JSON, and raw binary data using the WebMessageEncodingBindingElement. It is composed of an HttpsTransportBindingElement, an HttpTransportBindingElement and a WebHttpSecurity object. The WebHttpBinding is designed to be used in conjunction with the WebHttpBehavior.

WebInvokeAttribute

The WebInvokeAttribute attribute is similar to the WebGetAttribute, but it is used to mark a service operation as one that responds to HTTP requests other than GET. It is a passive operation behavior (the IOperationBehavior methods do nothing) that adds metadata to the operation description. Applying the WebInvokeAttribute has no effect unless a behavior that looks for this metadata in the operation description (specifically, the WebHttpBehavior) is added to the service's behavior collection.

The WebInvokeAttribute attribute takes the optional parameters on the following table.

UriTemplate

The UriTemplate class allows you to define a set of structurally similar URIs. Templates are composed of two parts, a path and a query. A path consists of a series of segments delimited by a slash (/). Each segment can have a literal value, a variable value (written within curly braces [{ }], constrained to match the contents of exactly one segment), or a wildcard (written as an asterisk [*], which matches "the rest of the path"), which must appear at the end of the path. The query expression can be omitted entirely. If present, it specifies an unordered series of name/value pairs. Elements of the query expression can be either literal pairs (?x=2) or variable pairs (?x={value}). Unpaired values are not permitted. UriTemplate is used internally by the WCF REST Programming Model to map specific URIs or groups of URIs to service operations.

UriTemplateTable

The UriTemplateTable class represents an associative set of UriTemplate objects bound to an object of the developer's choosing. It lets you match candidate Uniform Resource Identifiers (URIs) against the templates in the set and retrieve the data associated with the matching templates. UriTemplateTable is used internally by the WCF REST Programming Model to map specific URIs or groups of URIs to service operations.

WebServiceHost

WebServiceHost extends the ServiceHost to make it easier to host a non-SOAP Web-style service. If WebServiceHost finds no endpoints in the service description, it automatically creates a default endpoint at the service's base address. When creating a default HTTP endpoint, the WebServiceHost also disables the HTTP Help page and the Web Services Description Language (WSDL) GET functionality so the metadata endpoint does not interfere with the default HTTP endpoint. WebServiceHost also ensures that all endpoints that use WebHttpBinding have the required WebHttpBehavior attached. Finally, WebServiceHost automatically configures the endpoint's binding to work with the associated Internet Information Services (IIS) security settings when used in a secure virtual directory.

WebServiceHostFactory

The WebServiceHostFactory class is used to dynamically create a WebServiceHost when a service is hosted under Internet Information Services (IIS) or Windows Process Activation Service (WAS). Unlike a self-hosted service where the hosting application instantiates the WebServiceHost, services hosted under IIS or WAS use this class to create the WebServiceHost for the service. The CreateServiceHost method is called when a incoming request for the service is received.

WebHttpBehavior

The WebHttpBehavior supplies the necessary formatters, operation selectors, and so on, required for Web-style service support at the Service Model layer. This is implemented as an endpoint behavior (used in conjunction with the WebHttpBinding) and allows formatters and operation selectors to be specified for each endpoint, which enables the same service implementation to expose both SOAP and POX endpoints.

Extending WebHttpBehavior

WebHttpBehavior is extensible by using a number of virtual methods: GetOperationSelector, GetReplyClientFormatter, GetRequestClientFormatter, GetReplyDispatchFormatter, and GetRequestDispatchFormatter. Developers can derive a class from WebHttpBehavior and override these methods to customize the default behavior.

The WebScriptEnablingBehavior is an example of extending WebHttpBehavior. WebScriptEnablingBehavior enables Windows Communication Foundation (WCF) endpoints to receive HTTP requests from a browser-based ASP.NET AJAX client. The HTML Form Handler Sample is an example of using this extensibility point.

WebHttpDispatchOperationSelector

The WebHttpDispatchOperationSelector uses UriTemplate and UriTemplateTable classes to dispatch calls to service operations.

Compatibility

The WCF REST Programming Model does not use SOAP-based messages and therefore does not support the WS-* protocols. You can however, expose the same contract by two different endpoints, one using SOAP and the other not using SOAP. See How to: Expose a Contract to SOAP and Web Clients for an example.

Security

Because the WCF REST Programming Model does not support the WS-* protocols the only way to secure a web service built on the WCF REST Programming Model is to expose your service using SSL. For more information about on setting up SSL with IIS 7.0 see How to implement SSL in IIS

See Also

Reference

WebHttpBinding
WebGetAttribute
WebInvokeAttribute
WebHttpBehavior
WebHttpDispatchOperationSelector

Concepts

WCF REST Programming Model Overview