WCF Web HTTP Programming Object Model

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

Programming Model:

Channels and Dispatcher Infrastructure:

Utility Classes and Extensibility Points:

AspNetCacheProfileAttribute

The AspNetCacheProfileAttribute, when applied to a service operation, indicates the ASP.NET output cache profile in the configuration file that should be used by to cache responses from the operation in the ASP .NET Output Cache. This property takes only one parameter, the cache profile name that specifies the cache settings in the configuration file.

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 shown in the following table.

Parameter Description
BodyStyle Controls whether to wrap requests and responses sent to and received from the service operation the attribute is applied to.
RequestFormat Controls how request messages are formatted.
ResponseFormat Controls how response messages are formatted.
UriTemplate Specifies the URI template that controls what HTTP requests get mapped to the service operation the attribute is applied to.

WebHttpBinding

The WebHttpBinding class incorporates support for XML, JSON, and raw binary data using the WebMessageEncodingBindingElement. It is composed of an HttpsTransportBindingElement, 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 shown in the following table.

Parameter Description
BodyStyle Controls whether to wrap requests and responses sent to and received from the service operation the attribute is applied to.
Method Specifies the HTTP method the service operation is mapped to.
RequestFormat Controls how request messages are formatted.
ResponseFormat Controls how response messages are formatted.
UriTemplate Specifies the URI template that controls what GET requests get mapped to the service operation the attribute is applied to.

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 WEB HTTP 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 WEB HTTP 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(Type, Uri[]) method is called when a incoming request for the service is received.

WebHttpBehavior

The WebHttpBehavior class 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(ServiceEndpoint), GetReplyClientFormatter(OperationDescription, ServiceEndpoint), GetRequestClientFormatter(OperationDescription, ServiceEndpoint), GetReplyDispatchFormatter(OperationDescription, ServiceEndpoint), and GetRequestDispatchFormatter(OperationDescription, ServiceEndpoint). 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 AJAX Service Using HTTP POST is an example of using this extensibility point.

Warning

When using the WebScriptEnablingBehavior, UriTemplate are not supported within WebGetAttribute or WebInvokeAttribute attributes.

WebHttpDispatchOperationSelector

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

Compatibility

The WCF WEB HTTP 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 endpoint: 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 WEB HTTP Programming Model does not support the WS-* protocols the only way to secure a Web service built on the WCF WEB HTTP Programming Model is to expose your service using SSL. For more information about setting up SSL with IIS 7.0 see How to implement SSL in IIS.

See also