The WCF REST Starter Kit is a set of .NET Framework classes and Visual Studio features and templates that enable users to create and access REST-style Windows Communication Foundation (WCF) services. These services are based on the WCF web programming model available in .NET 3.5 SP1. The starter kit also contains the full source code for all features, detailed code samples, and unit tests.
The first set of features in the starter kit is server-side features for building WCF REST services, which enable or simplify various aspects of using the REST capabilities in WCF. These include declarative caching, security, error handling, help page support, conditional PUT, push style streaming, type based dispatch and semi-structured XML support. This functionality is exercised by a set of Visual Studio templates for creating REST services such as an Atom Feed service, a REST-RPC hybrid service, a resource singleton or collection service, and an Atom Publishing Protocol service.
The second set of features is client-side features for accessing WCF and third-party REST services from within .Net applications. The new Http Client class provides the REST developer with a uniform extensible model for sending HTTP requests and processing HTTP responses, in a variety of formats. The new "Paste Xml As Type" Visual Studio add-in enhances the serialization support in HttpClient by generating serializable types based on XML examples or XSD schema
REST Service Development using the WCF REST Starter Kit
The WCF REST Starter Kit provides functionality to make it easier to develop service-oriented applications employing the REST architectural style, which encourages developers to create services that leverage the HTTP protocol’s capabilities more fully, while conforming to the constraints that make the web successful.
Server side features include:
- Help Page: In the programmable web, most REST-style services publish a help page that describes the allowed HTTP verbs, the URI templates and examples of request and response messages in common representation formats. The starter kit provides the capability to automatically generate help pages when you append "/help" to the service address. See the Caching1 sample for how you can enable this. This feature is also enabled in the relevant templates.
- Representation Formats: Another common problem on the web is to support multiple representations, such as XML and JSON.
When sending a request to a service, you can use the Accepts HTTP request header to ensure the right content type is returned. For example, if you specify "text/xml" in the Accepts request header on a GET, the return value will be in the XML format, and if you specify "application/json", the return value will be in JSON format. See the ContentTypeBasedDispatch sample to see how to use this feature. - Declarative Caching: One of the powerful features of the web is the ability to cache messages to minimize roundtrips. HTTP provides several capabilities, and RESTful services use some of these capabilities to enable a caching policy in services.
You can easily set up a service method so that its response is cached for a fixed duration of time, as demonstrated by the Caching1 sample. Another common scenario is caching the service response unless data changes in a server-side database, and this scenarios is enabled in the Caching2 sample. The starter kit provides a set of helper extension methods (for example, to generate an ETag from the hash of an object’s serialized form) that make it easy to implement such scenarios. - HTTP Verbs: While most firewalls and web clients allow for the HTTP GET and POST verbs, some of them do not support PUT, DELETE, and other verbs. To enable the invocation of such unsupported verbs, a common practice is to use the X-HTTP-Method-Override HTTP header on a POST request to specify the method you wish to call. The XHttpMethodOverride sample describes how to implement this functionality.
In REST services HTTP PUT and DELETE calls need to be idempotent. The ConditionalPut sample implements optimistic concurrency using ETags and if-match headers to deal with conflicts. - Security: The starter kit provides key capabilities to enable creation of secure services. HTML Forms Authentication and other ASP .NET authentication modes work out of the box, as demonstrated by the FormsAuth sample.
Many services require the user to provide an application/API key in the URL query string to allow access and this scenario is implemented in the ApiKeyVerification sample. The RequestInterceptor feature in the starter kit allows for a rich set of security capabilities, such as verifying URL signatures in schemes like OAuth, throttling usage by API key, etc. - Error Handling: The starter kit allows returning exceptions as a string or any serializable .Net type. The WebException sample shows how you can return a string or a custom type, and have it serialized as XML or JSON.
- Hosting Settings: The starter kit optimizes for a zero-configuration experience. In .NET 3.5, the WebServiceHost class was added to WCF that enables a zero-config experience for some basic scenarios. However the user needed to fall back to advanced configuration when tweaking any of the deployment time settings such as the maximum message size. The starter kit preserves the zero configuration experience while still allowing adjusting common deployment settings using the .svc file. Users can change properties on the WebServiceHost2 class to adjust maximum message size, XML reader quotas, throttling settings, transfer mode (buffered or streaming), principal permission mode, request interceptors, service credentials, and so forth.
The .svc file in the XHttpMethodOverride sample illustrates how a request interceptor can be added using this approach. The project templates set up the .svc file to allow modification of deployment settings in this same manner. - Other Features: The starter kit also provides some additional enhancements:
- submitting HTML forms using POST works out of the box as demonstrated by the FormsPost sample
- writing directly to the response Stream is supported as shown in the PushStyleStreaming sample
- working with System.Xml.Linq.XElement to receive semi-structured XML on the wire, and convert to and from the native types in your service as showin in the UntypedXml sample.
- New to Preview 2 of the WCF REST Starter Kit, all features can now be hosted in Medium Trust hosting environments.
Visual Studio Templates
The starter kit contains Visual Studio project and item templates to guide users on how to build RESTful services using WCF. To use the templates you can create new Web projects or include the service item inside of ASP.NET Web Site projects.
- The Atom Feed WCF Service template allows users to create a service that returns a collection as a feed in the Atom Syndication Format. See the TasksFeed sample.
- The REST Singleton WCF Service template allows users to create a service that represents a single instance of a resource, and expose it as XML or JSON. See the Counter sample, which shows how to have a single instance of a counter that clients can change in a RESTful way.
- The REST Collection WCF Service template allows users to create a service that represents a collection of resources exposed as XML or JSON. See the TasksCollection sample.
- The Atom Publishing Protocol WCF Service template allows users to create a service that manages a collection of resources using the Atom Publishing Protocol. The service allows users to get a Service Document that represents the types of collections managed by the service, as well as what content types it supports and other information. The user then uses HTTP verbs like GET, PUT, POST and DELETE to manage the items in the collection. The collection is returned as an Atom feed. Each collection can contain a single type of content (JPEG images for example) or multiple content types. You can also set the size of each page to be returned in the feed easily within the template. See the AtomPubTaskService sample for an example that manages a collection of tasks over Atom Publishing Protocol.
- Many services that leverage http extensively also use the URI to specify an action that gets implemented in the service. For instance, a picture feed service can have a searchPictures query to find pictures by a keyword. This is enabled by the HTTP Plain XML WCF Service template. See the TasksService template for an example.
Download WCF REST Starter Kit Preview 2
