Share via

WCF Web HTTP Programming Model Overview

  • Article

The Windows Communication Foundation (WCF) WEB HTTP programming model provides the basic elements required to build WEB HTTP services with WCF. 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 and URI Processing URIs play a central role in the design of WEB HTTP services. The WCF WEB HTTP programming model uses the UriTemplate and UriTemplateTable classes to provide URI processing capabilities.

  • 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. 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.

  • Multiple data formats Web-style services process many kinds of data in addition to SOAP messages. 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.

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. For more information about AJAX and JSON services, see AJAX Integration and JSON Support. For more information about Syndication, see WCF Syndication Overview.

There are no extra restrictions on the types of data that can be returned from a WEB HTTP service. Any serializable type can be returned from an WEB HTTP service operation. Because WEB HTTP service operations can be invoke by a web browser there is a limitation on what datatypes can be specified in a URL. For more information on what types are supported by default see the UriTemplate Query String Parameters and URLs section below. 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. For more information, see QueryStringConverter

CautionCaution:
Services written with the WCF WEB HTTP programming model do not use SOAP messages. Because SOAP is not used, the security features provided by WCF cannot be used. You can, however use transport-based security by hosting your service with HTTPS. For more information about WCF security, see Security Overview

Warning Caution:
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. To work around this issue you can uninstall the WebDAV extension or disable the WebDAV extension for your web site. For more information, see IIS and WebDav

URI Processing with UriTemplate and UriTemplateTable

URI templates provide an efficient syntax for expressing large sets of structurally similar URIs. For 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

This template describes URIs like the following:

  • a/x/c

  • a/y/c

  • a/z/c

  • and so on.

In this template, the curly brace notation ("{segment}") indicates a variable segment instead of a literal value.

.NET Framework provides an API for working with URI templates called UriTemplate. UriTemplates allow you to do the following:

  • You can call one of the Bind methods with a set of parameters to produce a fully-closed URI that matches the template. This means all variables within the URI template are replaced with actual values.

  • 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() and Match() are inverses so that you can call Match( Bind( x ) ) and come back with the same environment you started with.

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 represents a set of URI templates and selects the best match given a set of templates and a candidate URI. This is not affiliated with any particular networking stack (WCF included) so you can use it wherever necessary.

The WCF Service Model makes use of UriTemplate and UriTemplateTable to associate service operations with a set of URIs described by a UriTemplate. A service operation is associated with a UriTemplate, using either the WebGetAttribute or the WebInvokeAttribute. For more information about UriTemplate and UriTemplateTable, see UriTemplate and UriTemplateTable

WebGet and WebInvoke Attributes

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). 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. The WebGetAttribute and the WebInvokeAttribute allow you to control how individual operations get bound to URIs and the HTTP methods associated with those URIs. 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 );
}

The preceding code allows you to make the following HTTP requests.

GET /GetCustomer

POST /UpdateCustomerName

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

To 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 Query String Parameters and URLs

Web-style services can be called from a Web browser by typing a URL that is associated with a service operation. These service operations may take query string parameters that must be specified in a string form within the URL. The following table shows the types that can be passed within a URL and the format used.

 

Type 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 (exponent notation is not required)

Double

-1.79769313486232e308 - 1.79769313486232e308 (exponent notation is not required)

Char

Any single character

Decimal

Any decimal in standard notation (no exponent)

Boolean

True or False (case insensitive)

String

Any string (null string is not supported and no escaping is done)

DateTime

MM/DD/YYYY

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

Month Day Year

Month Day Year HH:MM:SS [AM|PM]

TimeSpan

DD.HH:MM:SS

Where DD = Days, HH = Hours, MM = minutes, SS = Seconds

Guid

A GUID, for example:

936DA01F-9ABD-4d9d-80C7-02AF85C822A8

DateTimeOffset

MM/DD/YYYY HH:MM:SS MM:SS

Where DD = Days, HH = Hours, MM = minutes, SS = Seconds

Enumerations

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

Any of the individual enumeration values (or their corresponding integer values) may be specified in the query string.

Types that have a TypeConverterAttribute that can convert the type to and from a string representation.

Depends on the Type Converter.

Formats and the WCF WEB HTTP Programming Model

The WCF WEB HTTP programming model has new features to work with many different data formats. At the binding layer, the WebHttpBinding can read and write the following different kinds of data:

  • XML

  • JSON

  • Opaque binary streams

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 provides support for JSON data (AJAX) as well as Syndication feeds (including ATOM and RSS). For more information about these features, see WCF Web HTTP FormattingWCF Syndication Overview and AJAX Integration and JSON Support.

WCF WEB HTTP Programming Model and Security

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. For more information about setting up SSL with IIS 7.0, see How to implement SSL in IIS

Troubleshooting the WCF WEB HTTP Programming Model

When calling WCF WEB HTTP services using a ChannelFactory to create a channel, the WebHttpBehavior uses the EndpointAddress set in the configuration file even if a different EndpointAddress is passed to the ChannelFactory.

See Also

Concepts

WCF Web HTTP Programming Object Model

Other Resources

WCF Syndication
WCF Web HTTP Programming Model