My Technobabble

Integrating MVC routes and Web API routes

Glenn Block MSFT — Fri, 05 Aug 2011 05:57:50 GMT

Several folks have been complaining for a while about Action Links not being properly generated when MVC routes are mixed with Service Routes in the same site.

It turns out there is a solution.....don't use ServiceRoute :-) Instead, create a derived route below and use it. [Kudos to Phil Haack and Clemens Vasters for this]

public class WebApiRoute : ServiceRoute
{
     public AppServiceRoute(string routePrefix, 
       ServiceHostFactoryBase serviceHostFactory, Type serviceType)
     : base(routePrefix, serviceHostFactory, serviceType)
     {
     }
      
     public override VirtualPathData GetVirtualPath(
       RequestContext requestContext, RouteValueDictionary values)
     {
       return null;
     }
}

The link gen functionality uses the GetVirtualPath method to generate links. If you set it to null you are opting web api routes out of link gen and everything should work.

Now to register your routes using this model, don't use MapServiceRoute.

Instead, in add to your route table manually this way:

var config = new HttpHostConfiguration() ///create your config object
var factory = new HttpConfigurableServiceHostFactory(config);
routes.Add(new WebApiRoute("Foo", factory, typeof(Foo)));

It's a little bit more code, but not too much and hey, it fixes the problem. This will be fixed in the next drop, which YES, we are working on.

REST In Practice the book, RestBucks the sample

Glenn Block MSFT — Mon, 06 Jun 2011 20:11:48 GMT

The book

If you’ve watched any of my recent talks, one book you may have heard me mention quite a bit is “REST In Practice” by Jim Webber, Savas Parastatidas and Ian Robinson. The thing I really like about this book that differentiates it from others on REST is that it broaches the concept of REST in the enterprise. This book is essential for those building RESTful business systems. It’s a book that has helped my own understanding tremendously and one that I find practically by my bedside. It covers topics that are of concern for folks taking business systems and moving them to a RESTFul architecture style. It also gradually takes people across the chasm from traditional RPC style services, to HTTP CRUD services and then finally to RESTful services. It is by no means the only book on the topic, as there are other good resources which I would also recommend like Subbu’s work, RESTful Web Services Cookbook.

RestBucks, the sample

One of the cornerstones of the book is a reference application called RestBucks, an application which takes the process of ordering coffee and exposes it electronically over HTTP using a set of RESTful services. The sample provides a great reference point for folks building RESTful systems to see how to address various concerns in a RESTful way. One key thing it addresses is the topic of hypermedia constraints / driving business processes through linking. Throughout the book we see various aspects of the sample implemented in various languages including Java and .NET. The .NET pieces utilize WCF 4.

Now available for WCF Web API thanks to the community

Since we announced WCF Web API, several folks have been asking for a port of RestBucks using our new web api. I actually started working on one, but due to other constraints never got around to making much progress. Fortunately folks from the community have stepped up to the plate! Several months back, Szymon Pobiega went and ported the RestBucks code to use web api: https://github.com/SzymonPobiega/restbucks-wcf. Checking the site, Szymon just recently updated the bits to Preview 4.

More recently, José Romaniello of Tellago released another port of RestBucks which he blogged about. One nice thing about this port is it includes documentation pages for the various links as well as some good content via his growing blog series which you can access here: http://joseoncode.com/category/restbucks/. Jose and I have chatted and he is committed to really fleshing out the docs and keep the sample alive. Another cool thing is that José has deployed RestBucks on App Harbour so you can access it live here! restbuckson.net. Remember these are RESTful apis, not web pages. You’ll want to use something like Fiddler to navigate the app. If you want to get the source, you can download it at the codeplex site here: http://restbucks.codeplex.com/. BTW, he’s looking for commtters

Big thanks to Szymon and José for the port!

Get the book, get the samples!

Message Handlers vs Operation Handlers which one to use?

Glenn Block MSFT — Tue, 17 May 2011 20:46:58 GMT

In WCF Web API we have 2 extensibility points which seem very similar. They both are designed for very different reasons. Recently the question of which to use when popped up on our forums. Below is some guidance.

Message Handlers

Message handlers (Currently DelegatingChannel but will be renamed to DelegatingHandler) only deal with http messages (hence the name), you can use them to modify the request or the response or to stop the request and immediately return a response. So in general you use message handlers for addressing http specific concerns, for example:

Logging each request (logging the uri)
Checking for if-match / if-non-match headers and returning a 304 (not modified)
Embedding an ETag header in the response
Setting accept headers based on the uri (I do this in the ContactManager)
Checking for API keys as in Pablo's (@cibrax) Handler here, or handling other security concerns like OAuth. (Our OAuth integration in the future will sit here.)

A few things to note about message handlers

They are configured per host not per operation
They sit very low in the WCF stack in the channel layer making them ideal for security level concerns.
They are arranged in a russian doll model meaning each handler calls to it's inner handler. This lets you do plug in pre-post handling before the handler is called.
They only support async (Task<T>)

Operation Handlers

Opeation handlers (HttpOperationHandler) deal with taking the message and manufacturing the parameters for an operation or vice versa. It is the responsibility of the operation handler pipeline to ensure that for every parameter in the method there is a corresponding value it is also the responsibility of the pipeline to take any return/out values and modify the message appopriately with the correct representation. Those values can either be pulled from the message itself (such as parsing the uri into an object) or from custom logic like talking to a respository. The exception here is the value that represents the content of the message. It is the responsibility of the Formatters to handle taking the body and turning into an object or vice versa. Common use cases:

Taking a portion of the URI and manufacturing an object. An example of this would be taking a uri like http://maps.com/location/100,00 and turning it into a Location object with latitude / longitude properties.
Taking the content and compressing / decompressing it with gzip. Darrel Miller (@darrel_miller) has a nice example of this
Logging specific parameters of an operation
Validating the body, i.e. someone posts a customer in one of multiple formats. The formatter runs and turns it into a customer (based on conneg) and then the handler validates the model to see that the value are correct.

Here's the things to note about operation handlers.

They are configured per operaiton not per host
Manufacture values which are used by other handlers in the pipeline or by the operation
They are arranged in a pipeline where each handler is called in succession but one handler does not call the other.
They only support sync in the box
They can stop the pipeline by throwing an HttpResponseException<T>

Which to use really depends on your scenarios. If you are trying to address pure http concerns use message handlers, if you are trying to address application level concerns that work with models etc, use operation handlers.

Using DataContracts with WCF Web API

Glenn Block MSFT — Sun, 15 May 2011 02:45:37 GMT

A few folks have been asking if it is possible to serialize/deserialize using the DataContractSerializer. Rest assured, yes it is possible. Now whether or not it is the easiest/most intuitive model well that it is a different question.

If you read to the end the post you will see a bunch of extensions which have been pushed to webapicontrib and make this all MUCH easier (at least I think). If you don’t jump you’ll read below what you need to do if you do it yourself.

It stars with the SetSerializer<T> method which is expose on the XmlMediaTypeFormatter. You can call this method and pass a DataContractSerializer for T. That tells the formatter use this serializer not the default. You need to give it the exact information, for example if you are returning List<Contact> then make T List<Contact> NOT T. If you want to support both, you need to register both.

To allow you to get to the formatter, the MediaTypeFormatterCollection exposes an XmlFormatter property. You might now be thinking, “Oh that’s easy, but how do I get a hold of the formatter collection?”

Good question. It depends on whether you are on the server or on the client.

On the Server

The easiest way to configure things on the server is to annotate your service/resource with a [DataContractFormat] attribute. Once you do then we will automatically use the DataContractSerializer.

If you do not want to annotate your service, the alternative option is to do it in code. If you are using HttpHostConfiguration you can get to the formatters by accessing the OperationHandlerFactory property on the config class. If you are using the fluent API, you’ll want to cast to HttpHostConfiguration in order to access it. For example see the code below

var config = new HttpHostConfiguration();
var formatter = OperationHandlerFactory.XmlFormatter;
formatter.SetSerializer<Contact>(
  new DataContractSerializer(typeof(Contact)));
formatter.SetSerializer<List<Contact>>(
  new DataContractSerializer(typeof(List<Contact>)));

The code above is setting the formatter to use the DCS for Contact and List<Contact> both for reading and writing.

On the client

On the client side how you configure depends on if you are reading or writing. In either case both steps involve calling SetSerializer<T> on the XmlMediaTypeFormatter.

For reading you will create the formatter and pass it to the ReadAs<T> method of the HttpContent which is accessed off of the Content property on HttpResponseMessage.

var formatter = new XmlMediaTypeFormatter();
formatter.SetSerializer<List<Contact>>>(
  new DataContractSerializer(typeof(List<Contact>))));
var contact = response.Content.ReadAs<T>(
  new List<MediaTypeFormatter> { formatter });

If you are writing to the request, you will access the formatters collection on the ObjectContent<T> instance.

var content = new ObjectContent<Contact>();
content.Formatters.SetSerializer<Contact>(
  new DataContractSerializer(typeof(Contact)));
client.Post(content);

New extension methods in webapicontrib to make life easier

Now that we’ve seen how you can do it, we can wrap this up in a bunch of helper extension methods and life gets a whole lot easier. I did that and pushed them to webapicontrib

Check the code below from the new DataContractExample in webapicontrib.

var config = HttpHostConfiguration.Create();
config.UseDataContractSerializer<Contact>();
var host = new HttpConfigurableServiceHost<ContactsResource>(
  config, new Uri("http://localhost:8080/"));
host.Open();
var client = new HttpClient("http://localhost:8080/");
var newContact = new Contact {FirstName = "Brad", LastName = "Abrams"};
var content = new ObjectContent<Contact>(newContact,
  "application/xml").UseDataContractSerializer();
var response = client.Post("contacts", content);
response = client.Get("contacts");
var contacts = response.Content.ReadAsDataContract<Contact[]>();
foreach (var contact in contacts)
{
  Console.WriteLine(string.Format(
    "Contact: FirstName={0}, LastName={1}", 
    contact.FirstName, contact.LastName));
}
Console.ReadLine();

I’ve highlighted the important parts

UseDataContractSerializer<T> on the config will set the formatter to serialize T using DCS. In order to make life easier the extension method also registers for List<T> and T[].
For reading on the client call the ReadAsDataContract<T> extension method on HttpContent.
For writing on the client create an ObjectContent<T> instance and call the UseDataContractSerializer() extension metho

Download the bits in wcfwebapi contrib here

Hypermedia and forms

Glenn Block MSFT — Mon, 09 May 2011 00:45:59 GMT

Updated (with a lot of new content)

One challenge when building REST based systems is how can the client determine what it can do next? There can be any number of clients each which need to interact with a system. How do they know HOW to interact? The WSDL approach is to offer a static snapshot of method calls on an API. That approach couples the client heavily to knowing everything about the server, including being coupled as to how things get processed. It inhibits evolvability. A change to the server usually results in breaking all clients. In a world where there are many 3rd party apps across devices consuming your server application this can be detrimental making it extremely difficult to move forward.

Hypermedia

Hypermedia (also referred to as Hypertext) is an answer. The word may sound scary but it basically means use links. When Tim Berners Lee, Roy Fielding, and others (Al Gore :-) ) were envisioning the Web, linking was a key component of that design. We’re used to seeing links in UI contexts like a browser, i.e. using a web based ordering system you can click on an “Add Item” link to add the item. But what about in a non-UI context? Well guess what, you can use links there as well.

With a hypermedia approach your server doesn’t only return data. It returns data + links. Those links provide a means for the client to discover the available sets of options that make sense based on where the client is at in the application. A link has 2 standard components, a url for the link and a rel. REL in this case stands for relation and describes to the client how the link relates to the current resource. For example, let’s take a catalog / shopping cart experience exposed in a RESTful way. When browsing the catalog, you get back a list of items. Each item can have links for adding the item to a cart. Below is one such item.

<item>
  <productNo>1</itemNo>
  <description>An item</description>
  <price>$19.95</price>
  <sku>123456789</sku>
  <link rel="rc:additem" url="/cart/12456/items"/>
</item>

Above the server returned a link for adding an item. Unlike an operation in a WSDL, that link it not static, and hardcoded as part of the contract. The server is offering the links that make sense at specific point in time based on the application and resource state. Assuming for example that “An Item” is out of stock, the client will not get a link for adding and item. Instead it may get a link to place the item on backorder. The client however doesn’t have any knowledge of the rules on the server. It doesn’t know that because the item is out of stock, it can’t add it. All it knows is that rel=”rc:additem” is not present. The server logic might be more sophisticated, maybe there are limits set on how much I can order of a specific item. From the client perspective though all it knows is the link is not present. That’s decoupling.

What about evolvability? The beauty of linking is that clients only care about the links they know, they don’t care about the links they don’t. That means as the server evolves it can offer additional links. For example we may decide to offer clients the ability to put an item in a wish-list rather than in the shopping cart. That means an additional link is returned such as the following:

<link rel="rc:addtowishlist" url="/wishlist/gblock"/>

Older clients won’t know about the wish list. They will however continue to function. Newer clients will easily consume the new functionality. If you imagine a world with many different clients consuming (which is real), that is huge! There’s a further benefit for the older clients. The server has advertised the fact that there are new capabilities. Clients can be designed to track links they don’t know such that they can log that there are new capabilities available.

An additional benefit of the link approach has to do with the urls themselves. Clients are agnostic to to building urls, thus the server can completely change the format of the url, or even where the urls point to without the client being impacted _at_all.

Jon Moore, a Technical Fellow at Comcast has a great talk / demonstration on how this works which he delivered at Oredev. I highly recommend it.

What to with a link and why forms are interesting?

So now we have links. But there’s one problem, how does the client know what to do them? Which HTTP method should be used, is it an HTTP GET, POST, etc? If it is a POST what type of content should be sent and in what form? Another challenge is around versioning, once a service has been updated, how do the clients know know how to upgrade that client to take advantage of the new functionality.

One solution is simple, read the spec. When you build hypermedia based systems you aren’t simply returning a media type (Content-Type header value) of “application/xml” or “application/json”. Rather you are returning something more specific such as “application/atom+xml” or something even more domain specific such as in tje new “REST in Practice book” where the system uses the media type of “application/vnd-restbucks+xml”. Each media type has an RFC/spec associated with it. Thus if a client author reads the spec, it should document what to expect from a links perspective and which method / media type to use.

That is one approach and it absolutely works. The downside of that approach is the client has to be encoded with specific knowledge of how to work with each link.

That is not the only approach however and one really interesting one is Forms.

Forms

If we look to HTML we can see some hints on how to address these issues. In a web page, if you click a link such as “Add Item”, the common paradigm is for the server to return an HTML form (the client may also display one through some client script). That form provides information to the human who is reading the site to help them move forward. The Form contains an action that points to uri, and method, as well as other fields which may be either prefilled by the server, or require input from the user. The model works basically in a seem-less fashion. The site can freely evolve as it can offer different forms to different users based on a number of factors including what “version” of the app they are using, their user profile etc.

Now imagine there is no human. There’s a machine client that is consuming some resources over HTTP. That machine may be jQuery code running in a browser, maybe be code executing in a rich client app such as WPF, Silverlight, Flash, or even a Java applet. Or it may be headless server code that is accessing that information. Ultimately the information will be likely surfaced to some human, but that is after some initial processing has taken place. For example there might be an agent that automatically processors orders using a 3rd party fulfillment service.

We can design electronic forms which our servers offer to clients to guide them on how to use the link to transition to the next state.

With this approach, each link is a GET that returns an electronic form. That form specifies url, method as well as pre-filled information from the server such as Item details. The form may also specify required fields such as a Quantity field.

The advantage of forms is they allow the client to be less coupled to knowledge of how to work with links, which yields greater evolvability.

For example for adding item '1' to a shopping cart, the server may return the client a link such as the following.

<link rel="rc:AddItem" url="/restcart/forms/additem/1" />

The client then automatically does a GET on the link and retrieves an AddItem form that looks like the following.

<form>
  <url>/restcart/cart/12456</url>
  <method>POST</method>
  <mediatype>vnd-restcart+xml</mediatype> 
  <item>
    <productNo>1</itemNo>
    <description>An item</description>
    <price>$19.95</price>
    <sku>123456789</sku>
  </item>
  <required>
    <quantity>1</quantity>
  </required> 
</form>

This form offers the client everything it needs to move forward. It does not have to build up the item information to POST as it has already been sent by the server. The server also specifies the media type for the client to use. This form additionally specifies that the client must provide a quantity.

To move forward, the client will POST to the specified url using the included item as the body. As required fields are specified, the client must supply those as well.

The server can also embed a token in the response in order to ensure the price of the item is valid for a period of time (say 2 hours). If there is no such guarantee or the time has expired, the server can return a status code of 409 (Conflict) to the client indicating that it needs to refresh the form.

*Note: There are alternative approaches to exposing the cart as a resource, for example the CART state could be maintained on the client and sent with the POST. In either case it would not rely on session state.

Summary

Hypermedia allows clients and servers to independently evolve. In this approach the server offers clients well known links at every stage of the client/server interaction in order to to guide the client as to what they can do next.

There are various approaches to implementing a hypermedia based system, including using electronic forms.

You mileage may vary as to whether you need this or not.

Interested in your thoughts.

WebSockets, RIA/JS and WCF Web API at MIX, a whole lotta love for the web

Glenn Block MSFT — Sun, 24 Apr 2011 09:52:23 GMT

MIX was indeed a busy time for the WCF Team. We delivered several talks, and released several shiny new toys to the community for folks that are building web-based systems.

WebSockets

Craig Kitterman of our Interoperability group, and Paul Batum, whom you might know of from his work on Fluent NHibernate gave a talk: Hot from the Labs: HTML5 WebSockets

In the talk they spoke about new explorations we are doing into supporting WebSockets in the Microsoft Stack. WebSockets is basically sockets for the web, i.e. a way to have a much more responsive in-browser experience. In the talk you’ll learn about the work going on in the W3C/IETF around WebSockets and you’ll see the exploratory work we’ve been doing both at the browser level and on the server to enable a WebSockets experience. I highly recommend this talk, as you’ll see is a pattern for the other talks I mention below.

Here’s a sneak peak of what the coding experience looks like, which I hope you agree is pretty clean.

On the client you have code such as the following:

conn.onopen = function () {
  state.className = 'success';
  state.innerHTML = 'Socket open';
};
conn.onmessage = function (event) {
  var message = JSON.parse(event.data);
  if (typeof message == 'string') {
    log.innerHTML = '<li class="them">' + 
    message.replace(/[<>&]/g, function (m) 
    { return entities[m]; }) + '</li>' + log.innerHTML; 
  } else {
    connected.innerHTML = message;
  }
};
conn.onclose = function (event) {
  state.className = 'fail';
  state.innerHTML = 'Socket closed';
};

The on the server you have a WebSocket service:

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession, 
  ConcurrencyMode = ConcurrencyMode.Multiple)]
public class ChatService : WebSocketsService
{
  ...
  
  public override void OnMessage(string value)
  {
    ChatService.sessions.RelayMessage(this, value);
  }
  public override int GetHashCode()
  {
    return this.id; 
  }
  protected override void OnClose(object sender, EventArgs e)
  {
    ChatService.sessions.Remove(this);
  }
}

You can download the latest bits of the WebSockets work at the HTML 5 labs WebSockets page.

RIA/JS

Brad Olenick of the RIA team delivered a talk: Building Data-centric N-tier Applications with jQuery.

In the talk he unveiled new work the RIA team is doing is to allow consuming RIA services in jQuery! Watch the talk. Brad demonstrates how you can build a rich jQuery front end that dynamically pulls down all of it’s data to the client using RIA. RIA/JS then integrates all the state-tracking/validation richness and such using jQuery validators. If you are building data-centric jQuery based applications then RIA can take care of a lot of the dirty work for you making your job easier*. This also highlights the value of RIA in that I can reuse my existing domain services now both across Silverlight and Javascript! I know my previous boss (who is deeply missed) Brad Abrams must be very happy seeing that this is being developed!

*We’re not saying RIA/JS is the panacea for all evils, but it certainly is for some :-)

Here are some of the key scenarios being supported in the first preview.

Query support with sorting, paging, filtering
Changeset submission with two edit modes:
1. “Implicit Commit” or “write-thru edits” where updates to field values are automatically submitted to your DomainService. This can enable a Netflix.com or Mint.com experience where field changes are submitted to the server as soon as the user tabs out of the field.
2. “Buffered Changes” mode, where your code must call commitChanges() to submit your changeset to the DomainService. Those that have used the Silverlight client will be most familiar with this mode - a submit button is often used to trigger the commit.
Data change events including collection changes
Client-side change tracking with an entity state API for determining what entities and properties have been edited
Entity data model support that allows you to navigate through associated entity properties and collections
Client-side validation by exposing your server-side validation metadata in jQuery validation format

And here is a snippet of the new RIA/JS syntax. This is a great example of how we are looking to take advantage of awesome OSS solutions for delivering value. It’s about time!

<script type="text/javascript">
  $(function () {
	var serviceUrl = "/CustomerApp-CustomerService.svc";
	var customers = [];
	var render = function (loadedCustomers) {
	  $("#customerForm input[name='CustomerName']").
	    val(loadedCustomers[0].CustomerName);
	  $("#customerForm").link(loadedCustomers[0]);
	};
	$([customers]).dataSource({
	  serviceUrl: serviceUrl,
	  queryName: "GetCustomers",
	  refresh: render
	}).refresh();
  });
</script>
<div id="customerForm">
    Name: <input type="text" name="CustomerName" />
</div>

After the talk, the RIA team shipped new bits (as in js files) to Codeplex and a new RIA Service jQuery Nuget package! allowing you to start to play with the RIA/JS stuff now. Go get-em here.

WCF Web API and Preview 4

Continuing along the path web goodness, I delivered a talk: WCF Web APIs: There’s a URI for that.

In the talk I covered the evolution of systems that are now making their capabilities directly available over HTTP including social sites and line of business / enterprise apps. I showed progress we’ve made since PDC on our new WCF addition. The advances have been significant including greatly improving the out of the box experience, enhancing the fidelity you can have when working with HTTP, improving the configuration story and improving testability.

For example I demonstrated how using our new nuget package, you quickly you can build a simple service that can return and consume xml, json as well as consume form url encoding content. I then throw an existing jQuery front end on top without having to touch the server side configuration. I then demonstrated how I could easily take my existing service and quickly refactor it to use an IoC container, in this case Autofac, by taking advantage of a new fluent api (which is still a work in progress).

In the second part of my talk, I demonstrated how having rich control of formats/media types can benefit you. This includes showing my resource returning OData, as well a vcard implementation which I use to import contacts directly into gmail. Try that with SOAP, or plain-old XML/JSON, I dare you!

Here’s a snippet of some of the HTTP fidelity I am talking about. Below my service takes advantage of our new HttpResponseMessage<T> and HttpResponseException to return a model AND work with HTTP at the same time.

[WebGet(UriTemplate = "{id}")]
public HttpResponseMessage<Contact> Get(int id)
{
  var contact = this.repository.Get(id);
  if (contact == null)
  {
    var response = new HttpResponseMessage();
    response.StatusCode = HttpStatusCode.NotFound;
    response.Content = new StringContent("Contact not found");
    throw new HttpResponseException(response);
   }
   var contactResponse = 
     new HttpResponseMessage<Contact>(contact);
   //set it to expire in 5 minutes
   contactResponse.Content.Headers.Expires = 
     new DateTimeOffset(DateTime.Now.AddSeconds(30));
   return contactResponse;
}

The Get method returns a contact and sets caching headers. If the contact is not found however it throws an HttpResponseException passing in an HttpResponseMessage. In this case I am just returning a string, but you have full access to set the response headers/content to whatever you want. Also you might not have caught it, but the id parameter is now passed in as integer. In previous drops as well as in WCF HTTP you had to use a string. Well now we do automatic type conversion. You asked for it, and you got it!

Nuget and Preview 4

After my talk, I am happy to announce that we pushed our next release of WCF Web API (yes drop the s) to Codeplex along with a new set of Nuget packages (webapi.all will get all of ours). You’ll notice a 6th package, WebApi.CrudHttpSample from Steve Michelotti. Rock on Steve! Here’s a link to more on that package.

Preview 4 is loaded with new features much of which is based on your feedback! We’ve been developing them for a while and finally are able to get them out there. All of our apis have been significantly evolved in this release.

Here is a summary of the major things you will find:

New message classes HttpResponseMessage<T> / HttpRequestMessage<T> allows accessing headers and using a strongly typed model.
Uri parameters can now autocast to primtiive types, i.e. a uri template of "{id}" can map to an integer parameter of id.
Matching of parameters is now by type if there is no match on name, ie. HttpRequestMessage req will work.
New Operation Handlers which replace processors and dramatically improve the authoring
New Formatters for plugging in custom media types
New Message Handlers for low level control over HTTP
Newer HttpClient
Support for Form Url Encoding / Json and Xml out of the box.
Support for HTTPs
IQueryable support with IQueryable<T> and without requiring attributes
Overhauled fluent API for configuration !!!!
Unit tests
New samples
ContactManager is now a fully client based AJAX / JQuery application

New ContactManager_Simple illustrates the bare basics.

new HelloResource sample
Acceptance and Unit tests for some of the samples

I am planning to do some follow up posting detailing all these changes, but this should be enough to keep you guys happy for a while

Go road test this stuff and give us your feedback. We want it, we’re not done yet!

Adding vcard support and bookmarked URIs for specific representations with WCF Web Apis

Glenn Block MSFT — Mon, 07 Mar 2011 14:51:11 GMT

REST is primarily about 2 things, Resources and Representations. If you’ve seen any of my recent talks you’ve probably seen me open Fiddler and how our ContactManager sample supports multiple representations including Form Url Encoded, Xml, Json and yes an Image. I use the image example continually not necessarily because it is exactly what you would do in the real world, but instead to drive home the point that a representation can be anything. Http Resources / services can return anything and are not limited to xml, json or even html though those are the most common media type formats many people are used to.

One advantage of this is your applications can return domain specific representations that domain specific clients (not browsers) can understand. What do I mean? Let’s take the ContactManager as an example. The domain here is contact management. Now there are applications like Outlook, ACT, etc that actually manage contacts. Wouldn’t it be nice if I could point my desktop contact manager application at my contact resources and actually integrate the two allowing me to import in contacts? Turns out this is where media types come to the rescue. There actually is a format called vcard that encapsulates the semantics for specifying an electronic business card which includes contact information. rfc2425 then defines a “text/directory” media type which clients can use to transfer vcards over HTTP.

A sample of how a vcard looks is below (taken form the rfc)

begin:VCARD
source:ldap://cn=bjorn%20Jensen, o=university%20of%20Michigan, c=US
name:Bjorn Jensen
fn:Bj=F8rn Jensen
n:Jensen;Bj=F8rn
email;type=internet:bjorn@umich.edu
tel;type=work,voice,msg:+1 313 747-4454
key;type=x509;encoding=B:dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK
end:VCARD

Notice, it is not xml, not json and not an image :-) It is an arbitrary format thus driving the point I was making about the flexibility of HTTP.

Creating a vcard processor

So putting two and two together that means if we create a vcard processor for our ContactManager that supports “text/directory” then Outlook can import contacts from the ContactManager right?

OK, here is the processor for VCARD.

public class VCardProcessor : MediaTypeProcessor
{
    public VCardProcessor(HttpOperationDescription operation)
        :base(operation, MediaTypeProcessorMode.Response)
    {
    }
    public override IEnumerable<string> SupportedMediaTypes
    {
        get
        {
            yield return "text/directory";
        }
    }
    public override void WriteToStream(object instance, 
      Strea stream, HttpRequestMessage request)
    {
        var contact = instance as Contact;
        if (contact != null)
        {
            var writer = new StreamWriter(stream);
            writer.WriteLine("BEGIN:VCARD");
            writer.WriteLine(string.Format(
                "FN:{0}", contact.Name));
            writer.WriteLine(string.Format(
                 "ADR;TYPE=HOME;{0};{1};{2}", 
                 contact.Address, contact.City, 
                 contact.Zip));
            writer.WriteLine(string.Format(
                 "EMAIL;TYPE=PREF,INTERNET:{0}", 
                 contact.Email));
            writer.WriteLine("END:VCARD");
            writer.Flush();
        }
    }
    public override object ReadFromStream(Stream stream, 
        HttpRequestMessage request)
    {
        throw new NotImplementedException();
    }
}

The processor above does not supporting posting vcard, but it actually could.

Right. However there is one caveat, Outlook won’t send Accept headers , all it has a “File-Open” dialog. There is hope though. It turns out that the dialog supports uris, thus as long as I can give it uri which is a bookmark to a vcard representation we’re golden.

This is where in the past it gets a bit hairy with WCF. Today to do this means I need to ensure that my UriTemplate has a variable i.e. {id} is fine, but then I have to parse that ID to pull out the extension. It’s ugly code point blank. Jon Galloway expressed his distaste for this approach (which I suggested as a shortcut) in his post here (see the section Un-bonus: anticlimactic filename extension filtering epilogue).

In that post, I showed parsing the ID inline. See the ugly code in bold?

[WebGet(UriTemplate = "{id}")] 
public Contact Get(string id, HttpResponseMessage response) 
{ 
    int contactID = !id.Contains(".")  
        ? int.Parse(id, CultureInfo.InvariantCulture)  
        : int.Parse(id.Substring(0, id.IndexOf(".")), 
        CultureInfo.InvariantCulture); 
  
    var contact = this.repository.Get(contactID); 
    if (contact == null) 
    { 
        response.StatusCode = HttpStatusCode.NotFound; 
        response.Content = HttpContent.Create("Contact not found"); 
    } 
    return contact; 
}

Actually that only solves part of the problem as I still need the Accept header to contain the media type or our content negotiation will never invoke the VCardProcessor!

Another processor to the rescue

Processors are one of the swiss army knives in our Web Api. We can use processors to do practically whatever we want to an HTTP request or response before it hits our operation. That means we can create a processor that automatically rips the extension out of the uri so that the operation doesn’t have to handle it as in above, and we can make it automatically set the accept header based on mapping the extension to the appropriate accept header.

And here’s how it is done, enter UriExtensionProcessor.

public class UriExtensionProcessor : 
   Processor<HttpRequestMessage, Uri>
{
    private IEnumerable<Tuple<string, string>> extensionMappings;
    public UriExtensionProcessor(
      IEnumerable<Tuple<string, string>> extensionMappings)
    {
        this.extensionMappings = extensionMappings;
        this.OutArguments[0].Name = HttpPipelineFormatter.ArgumentUri;
    }
    public override ProcessorResult<Uri> OnExecute(
      HttpRequestMessage httpRequestMessage)
    {
        var requestUri = httpRequestMessage.RequestUri.OriginalString;
        var extensionPosition = requestUri.IndexOf(".");
        if (extensionPosition > -1)
        {
            var extension = requestUri.Substring(extensionPosition + 1);
            var query = httpRequestMessage.RequestUri.Query;
            requestUri = string.Format("{0}?{1}", 
                requestUri.Substring(0, extensionPosition), query);;
            var mediaType = extensionMappings.Single(
                map => extension.StartsWith(map.Item1)).Item2;
            var uri = new Uri(requestUri);
            httpRequestMessage.Headers.Accept.Clear();
            httpRequestMessage.Headers.Accept.Add(
                new MediaTypeWithQualityHeaderValue(mediaType));
            var result = new ProcessorResult<Uri>();
            result.Output = uri;
            return result;
        }
        return new ProcessorResult<Uri>();
    }
}

Here is how it works (note how this is done will change in future bits but the concept/appoach will be the same).

First UrlExtensionProcessor takes a collection of Tuples with the first value being the extension and the second being the media type.
The output argument is set to the key “Uri”. This is because in the current bits the UriTemplateProcessor grabs the Uri to parse it. This processor will replace it.
In OnExecute the first thing we do is look to see if the uri contains a “.”. Note: This is a simplistic implementation which assumes the first “.” is the one that refers to the extension. A more robust implementation would look after the last uri segment at the first dot. I am lazy, sue me.
Next strip the extension and create a new uri. Notice the query string is getting tacked back on.
Then do a match against the mappings passed in to see if there is an extension match.
If there is a match, set the accept header to use the associated media type for the extension.
Return the new uri.

With our new processors in place, we can now register them in the ContactManagerConfiguration class first for the request.

public void RegisterRequestProcessorsForOperation(
   HttpOperationDescription operation, IList<Processor> processors,
   MediaTypeProcessorMode mode)
{
    var map = new List<Tuple<string, string>>();
    map.Add(new Tuple<string, string>("vcf", "text/directory"));
    processors.Insert(0, new UriExtensionProcessor(map));
}

Notice above that I am inserting the UriExtensionProcessor first. This is to ensure that the parsing happens BEFORE the UriTemplatePrcoessor executes.

And then we can register the new VCardProcessor for the response.

public void RegisterResponseProcessorsForOperation(
   HttpOperationDescription operation, 
   IList<Processor> processors, 
   MediaTypeProcessorMode mode)
{
    processors.Add(new PngProcessor(operation, mode));
    processors.Add(new VCardProcessor(operation));
}

Moment of truth – testing Outlook

Now with everything in place we “should” be able to import a contact into Outlook. First we have Outlook before the contact has been imported. I’ll use Jeff Handley as the guinea pig. Notice below when I search through my contacts he is NOT there.

Now after launching the ContactManager, I will go to the File->Open->Import dialog, and choose to import .vcf.

Click ok, and then refresh the search. Here is what we get.

What we’ve learned

Applying a RESTful style allows us evolve our application to support a new vcard representation.
Using representations allows us to integrate with a richer set of clients such as Outlook and ACT.
WCF Web APIs allows us to add support for new representations without modifying the resource handler code (ContactResource)
We can use processors for a host of HTTP related concerns including mapping uri extensions as bookmarks to variant representations.
WCF Web APIs is pretty cool

I will post the code. For now you can copy paste the code and follow my direction using the ContactManager. It will work

What’s next.

In the next post I will show you how to use processors to do a redirect or set the content-location header.

WCF Web APIs Roundup–Volume 2

Glenn Block MSFT — Mon, 07 Mar 2011 00:37:52 GMT

Been a while since our last roundup and since my last blog post for that matter! Fortunately there’s been a bunch of cool stuff going on in the community with our Web APIs that I can point you to. Great to see the community momentum pick up as we cross the 5000 download mark on Codeplex!

Blogs

WCF Web API general

A new Web for .NET: WCF Web APIs – Ryan Riley talks about the new Web APIs and work he is doing in F# to offer a Sinatra like experience using them.
WCF HTTP – Start Using It – Gustavo walks through the basics of setting up an HTTP Service and adding Media Type support.

HttpClient

Url shortening with WCF Web Apis HttpClient - Paul Jenkins of MahTweets fame posts on using our new Http client API for calling a url shortening service
Consuming WCF Web (REST) Apis in Silverlight – Joe Mcbride blogs about a new SimpleHttpClient he created for accessing WCF Web API services and other services.

Processors

WCF HTTP – Processors under the hood – Gustavo gives a deep overview of how processors work. He also shows how to build several processors including a processor that will convert uri parameters into native types.
Middleware in the WCF Web APIs – Ryan posts on how you can use our new Processor api for plugging in Middleware like different view engines.
Extensions – WCF HTTP Services – Funnel Web is an OSS blog engine. This post shows you how you can plug in services which are hosted in FunnelWeb and which have DI support through Autofac via the new IoC extensions in Preview 3.
WCF HTTP – Cool processor for Navigation – Gustavo shows us how a custom processor can simplify handling sub-resources.

Security

Authenticating clients in the WCF HTTP Stack – In this Pablo Cibraro introduces some extensions for WCF Web APIs based on previous interceptors he had for the REST Start Kit which are used for authenticating clients. He says he believes the new Web APIs offer much richer support for building HTTP oriented services in NET. We agree :-)
Using WCF Web APIs / WCF Http with ASP.NET Forms Authentication – Alex Zeitler shows us how to use WCF Web APIs with ASP.NET forms authentication!

ASP.NET MVC

JSON, ASP.NET MVC and JQuery – Working with Untyped JSON made easy – Ana posts on how you can access untyped Json via a custom model binder in MVC which uses the new JsonValue that we ship in WCF Web APIs

Podcasts / Videos

Take some REST with WCF – My talk at MVCConf on our new APIs including exposing OData, and usage with MVC.
endpoint.tv – WCF Web API – Content Types – Ron Jacobs and I look at the new media type support in WCF Web APIs which enables building great browser apps that use JQuery to talk to HTTP Services.
Yet Another Podcast #25-Glenn Block/WCF – Jesse Liberty and I kick it about HTTP, REST and the new Web APIs. That is after I finish interviewing him. :p

WCF Web API team

I’ve moved – Howard Dierking (formerly of MSDN Magazine) announces that he has joined our team!

WCF Web APIs Roundup - Volume 1

Glenn Block MSFT — Mon, 13 Dec 2010 06:31:20 GMT

A little over a month ago we launched our new WCF Web Apis on Codeplex. Since then a bunch of folks in the community (and some internal folks) have been posting about their own explorations / thoughts of the new bits. it’s great to see the work that they are doing! I am going to start aggregating these and periodically (I am not committing to a cadence but am aiming for monthly) post pointers to whatever I find. Appreciate any suggestions to the format.

Blogs

On WCF Web Apis
- Microsoft WCF gets serious about HTTP – Darrel Miller shares his thoughts on the new WCF Web Apis, it’s importance, and how it compares aganst other offerings within the .NET stack.
- Okay, WCF we can be friends now – Jon Galloway gives an overview of the new features in WCF Web Apis including HTTP enhancements and jQuery support..
- New IQueryable Support for HTTP Services in WCF – Pablo Cibraro explores the new query composition feature we’re adding to enable LINQ to WCF type scenarios.
Using Processors
- Http Processors in the new WCF Programming Model – Pablo describes the new processor api that we’ve introduced for addressing HTTP specific concerns in a cross-cutting fashion. He demonstrates how to use processors for transforming a portion of the URI into a CultureInfo object.
- Versioning REST services with WCF HTTP Processors – Pablo describes an approach for versioning with media types. Processors are used to transform a portion of the media type into a version with the operation uses to returned a versioned response.
- Combine WCF MedaTypeProcessors with a Custom Razor Host – Steve Michelotti describes how you can create a processor which uses the new ASP.NET Razor engine to render an HTML response.
- WCF Media Processor + Speech API = SpeechProcessor fun – Jon Galloway illustrates how to plug in a custom processor for rendering a representation using the .NET Speech API. Using the processor allows one to use the new HTML 5 Audio tag or to point windows media player at a resource and have it literally "say” the response. Jon also does a great overview of how MediaTypeProcessors work and the value of supporting multiple formats.
- Using JSON.NET as a default serializer in WCF HTTP/Web/REST (vNext) – Christian Weyer shows how to replace the default JSON serializer in WCF Web APIs with a custom serializer that uses the popular Json.NET library. In addition to supporting JSON,he also shows how to support BSON (binary JSON)

Other cool things to note

WCF Http Contrib – A new codeplex site for contributions to WCF Web Apis.
WCF Web Apis are on nuget! – If you want to quickly get going with using the new APIs in your projects, nuget is the answer! We’ve posted two nuget packages. Note: Run both packages from the nuget command shell as they execute powershell scripts for registering gaced WCF assemblies.
- WcfWebApis – This package contains binaries for WcfWebApis. Installing it will add appropriate project references for WCF and the new apis and will update the web.config.
- WcfResource – This package depends on WcfWebApis and contains the convention based resource model prototype I blogged about recently. The model supports conventions, code-based configuration and provides hooks for using an IoC containers.

Streaming over HTTP with WCF

Glenn Block MSFT — Wed, 24 Nov 2010 23:23:00 GMT

Recently I had a customer email me looking for information on how to send and receive large files with a WCF HTTP service. WCF supports streaming specifically for these types of scenarios. Basically with streaming support you can create a service operation which receives a stream as it’s incoming parameter and returns a stream as it’s return value (a few other types like Message and anything implementing IXmlSerializable are also supported). MSDN describes how streaming in WCF works here, and how to implement it here. There’s a few gotchas however if you are dealing with sending large content with a service that is hosted in ASP.NET. If you scour the web you can find the answers, such as in the comments here.

In this post I’ll bring everything together and walk you through building a service exposed over HTTP and which uses WCF streaming. I’ll also touch on supporting file uploads with ASP.NET MVC, something I am sure many are familiar with. The sample which we will discuss requires .NET 4.0 and ASP.NET MVC 3 RC. If you don’t have MVC you can skip right to the section “Enabling streaming in WCF”. Also it’s very easy to adopt the code to work for web forms.

The scenario

For the sample we’re going to use a document store. To keep things simple and stay focused on the streaming, the store allows you to do two things, post documents and retrieve them through over HTTP. Exposing over HTTP means I can use multiple clients/devices to talk to the repo. Here are more detailed requirements.

1. A user can POST documents to the repository with the uri indicating the location where the document will be stored using the uri format “http://localhost:8000/documents/{file}”. File in this case can include folder information, for example the following is a valid uri, “http://localhost:8000/documents/pictures/lighthouse.jpg”.

Below is what the full request looks like in Fiddler. Note: You’ll notice that the uri (and several below) has a “.” in it after localhost, this is a trick to get Fiddler to pick up the request as I am running in Cassini (Visual Studio’s web server).

And the response

2. On a POST, the server creates the necessary folder structure to support the POST. This means if the Pictures sub-folder does not exist it will get created.

3. A user can GET a document from the repository using the same uri format for the POST. Below is the request for retrieving the document we just posted.

And the response: (To keep thing simple I am not wrestling with setting the appropriate content type thus application/octet-stream is the default).

4. The last requirement was I needed a simple front end for uploading the file. For this I decided to use ASP.NET MVC3 to create a really simple front end. That also gave me a chance to dip my feet in the new Razor syntax.

Creating the application

The first thing I did was create a new MVC 3 application in Visual Studio. I called the application “DocumentStore” and selected to create an empty application when prompted.

Next thing I did was was add a HomeController and a new view Index.cshtml which I put in the Views/Home folder. The view which is below allows me to upload a document and specify the folder. I did tell you it was simple right?

Next I added an Upload view also in the View/Home folder. That view show she result of the upload.

Then in the HomeController I implemented the Upload action which contains the logic for POSTing to the service. I used HttpClient form the Rest Starter Kit to do the actual post.

Here’s the flow

Grab the uploaded file and the path.
Create the uri for the resource I am going to post.
Post the resource using HttpClient.
Set the filename info to return in the view.

Up until this point I’ve simply created the front end for uploading the document. Now we can get to the streaming part.

Enabling streaming over HTTP

Streaming is enabled in WCF through the transferMode property on the binding. In this case I set transferMode to “Streamed” as I want to support it bi-directionally. The setting accepts other values which can be used to enable streaming on the request OR the response. I also set the maxReceivedMessageSize to the maximum size that I want to allow for transfers. Finally I also also set the maxBufferSize, though this is not required. WCF 4.0 introduced default bindings which greatly simplifies this configuration. In this case because I’m going to use WCF HTTP, I can use the standard webHttpBinding as is shown.

If you read the MSDN articles I cited above, you might think I’m done, however because I’m hosting our service on ASP.NET, there’s one more critical setting I need to mess with. This one definitely threw me for a loop.

ASP.NET doesn’t know about WCF and it has it’s own limits for the request size which I have now increased to match my limit. Without setting this the request will be killed if it exceeds the limits. This setting and the previous settings have to be kept in sync. If not, either ASP.NET will kill the request, or WCF will return a Status 400: Invalid Request. Service tracing is definitely your friend in figuring out any issues on the WCF side.

Building the DocumentsResource

Now that streaming is enabled, I can build the resource. First I created a DocumentsResource class which I marked as a ServiceContract and configured to allow hosting in ASP.NET.

Registering the resource through routes (.NET 4.0 Goodness!)

Because I am using .NET 4.0, I can take advantage of the new ASP.NET routing integration to register my new resource without needing an .SVC file. To do this, I create a ServiceRoute in the Global.asax specifying the base uri and the service type (resource).

Document retrieval (GET)

Our document store has to allow retrieval of documents. Below is the implementation.

As I mentioned earlier, when you enable streaming your operations only work with a limited set of input / return values. In this case my GET method returns a stream which represents the document. Notice the method is has no parameters. When building a streamed service, the method can only have a single parameter which is either of type stream, message or which implements IXmlSerializable. This forces me to jump through a small hoop to get access to the path info for the document, but it’s manageable.

Here’s the logic in the method.

The method is annotated with a WebGetAttribute to indicate that it is a GET. The UriTemplate is set to “*” in order to match against any uri that matches the base uri for this service..
Next I grab all the uri segments and concatenate in order to create the relative file location. For example for the uri “http://localhost:8080/documents/pictures/lighthouse.jpg” this will result in “pictures\lighthouse.jpg” assuming the base address is “documents'”.
If a file path was actually passed in, I then create a the relative file path by concatenating the relative location with the server root and the relative path for the doc store.
Finally I create a stream pointing to the file on disk and I return it. The resulting stream is then returned back to the client.

Document upload (POST)

Whereas in the Get method we return a stream, in the POST case we simply accept a stream. In this case we need to create the directory if it does not exist and write the document to disk so there’s a bit more work.

Here’s the logic:

The method is annotated with WebInvoke with the method set to POST. Similar to the GET, the UriTemplate is set to “*” to match everything.
Next I grab on to the uri of the request so that I can return it later as part of the Location header in the response. This is appropriate according to the HTTP spec. It’s important that I grab it before I actually stream the file as I found if I wait till after, the request is disposed and I get an exception.
Similar to the GET I also grab the path segments to create the file name and create the local path.
Next I check to see if the directory that was requested actually exists. If it does not, I create it.
I create a stream to write the file to disc and use the convenient CopyTo method to copy the incoming stream to it.
Finally I set the status code to Created and set the location header.

Testing out the app

That’s it, the app is done. Now all there is to do is launch it and see the streaming in action as well.

Like I said, simple UI. . Go press “Browse” and then grab an image or a video. In this case I’ll grab the sample wildlife.wmv included in win7.

Next enter “Videos” for the folder. You can also put a deep hierarchy if you want like Foo/Bar/Baz.

Select Upload and you will see the following once it completes.

Now that the file is uploaded, it can be retrieved from the browser.

Which in this case will cause Windows media player to launch and show our video,….w00t!

Now that our document store is in place, we can use different clients to access it. In this example we used a browser / MVC application to keep things simple. The same store can also be accessed from a mobile device line an IPad,, a Silverlight application, or from a desktop application. All it needs is a way to talk HTTP.

Why not just MVC?

I know some folks are going to see this and say “why didn’t you just use MVC?'”. I could have accomplished the upload / retrieval completely through MVC. The main point of this post however was to show how you can use streaming with WCF. Let’s move on

Get the code here: http://cid-f8b2fd72406fb218.office.live.com/self.aspx/blog/DocumentStore.zip

Are you using WCF within your organization?

Glenn Block MSFT — Tue, 16 Nov 2010 21:06:28 GMT

Do you use WCF within your organization either for internal apis for exposing services and functionality to 3rd parties? We’re looking to connect with customers using our stuff in the real world so we can understand your use cases, the things you’ve liked about WCF and where you’d like to see us improve / go further. If interested, please contact me.

We look forward to hearing from you.

WCF Web APIs, HTTP your way

Glenn Block MSFT — Mon, 01 Nov 2010 10:13:06 GMT

At PDC in my session “Building Web APIs for the Highly Connected Web” we announced WCF Web APIs, new work we are doing to make HTTP first class in WCF. In this post I am going to describe what we are doing and why. If you are saying, “just show me the bits”, then just head on over to wcf.codeplex.com our new site that we just launched!

Why HTTP?

HTTP is ubiquitous and it’s lightweight. Every consumer that connects to the web understands it, every browser supports it, and the infrastructure of the world wide web is built around it. That means when you travel HTTP, you get carte blanche status throughout the world wide web. It’s like a credit card that is always accepted everywhere. In the past, HTTP’s primary usage was for serving up HTML pages. Over time however our web applications have evolved. These newer breed are much more dynamic, aggregating data not only from the company server but from a multitude of services that are hosted in the cloud. Many of those services themselves are now being exposed directly over HTTP in order to have maximum reach.

Whereas in the past the primary consumer was a desktop / laptop PC, we’ve now moved into the age of devices including phones like IPhone, Android and Windows Phone as well as other portable tablets like the iPad and the upcoming Slate. Each of these devices (including the PC) have different capabilities, however one thing is consistent, they all talk HTTP.

WCF and HTTP, we’re going much further.

As the industry evolves, our platform needs to evolve. Since .NET 3.5, we have been continually evolving WCF to provide better support for surfacing services and data over HTTP. We’ve made good progress but there is more we can do. Developers using WCF have said they want more control over HTTP. We’ve also heard developers asking for better support for consuming WCF services with web toolkits like jQuery. Additionally, we’ve heard requests about simplifying configuration, removing ceremony, more testability, and just an overall simplified model. We hear you and we’re taking action. We’re making significant enhancements to our platform to address the concerns. Below is a list of some of the improvements we are focusing on specific to HTTP which we just made available on Codeplex (available in WCF HTTP Preview 1.zip). For the jQuery work check out these excellent posts by Tomek and Yavor..

Our HTTP focus areas

Media Types and Formats

HTTP is extremely flexible allowing the body to be presented in many different media types (content type) with html, pure xml and json, atom and OData being just a few. With WCF Web APIs we’re going to make it very easy for services to support multiple formats on a single service. Out of the box, we are planning to support xml, json and OData however we’re also making it very easy to add on support for additional media types including those that contain hypermedia (see my talk for an exampe). This gives WCF the flexibility to service a variety clients based on their needs and capabilities.

Below is a snippet which demonstrates taking a contact returned from an operation and representing it as a png file stored in an images folder. PngProcessor derives from MediaTypeProcessor. Processors are a new extensibility point in WCF Web APIs. MediaTypeProcessor is a special processor that you derive from to support a new format.

public class PngProcessor : MediaTypeProcessor
{
    public PngProcessor(HttpOperationDescription operation, 
        MediaTypeProcessorMode mode)
        : base(operation, mode)
    {
    }
    public override IEnumerable<string> SupportedMediaTypes
    {
        get
        {
            yield return "image/png";
        }
    }
    public override void WriteToStream(object instance, 
        Stream stream, HttpRequestMessage request)
    {
        var contact = instance as Contact;
        if (contact != null)
        {
            var path = string.Format(CultureInfo.InvariantCulture, 
                @"{0}bin\Images\Image{1}.png", 
                AppDomain.CurrentDomain.BaseDirectory, 
                contact.ContactId);
            using (var fileStream = new FileStream(path, FileMode.Open))
            {
                byte[] bytes = new byte[fileStream.Length];
                fileStream.Read(bytes, 0, (int)fileStream.Length);
                stream.Write(bytes, 0, (int)fileStream.Length);
            }
        }
    }
    public override object ReadFromStream(Stream stream, 
        HttpRequestMessage request)
    {
        throw new NotImplementedException();
    }
}

This same Png formatter can sit side by side with formatters for other media types like json, xml, and atom. WCF will automatically select the right processor based on matching the request accept headers passed from the client against the SupportedMediaTypes.

To see different media types in action, check the ContactManager sample that ships with WCF Web APIs.

Registering formatters / processors

In order to register processors, we’re exploring a new programmatic configuration model which allows you to configure all processors (including formatters) at a single place within your application. To configure processors, you derive from a HostConfiguration class and override a few methods. You then pass your custom configuration class to the WebHttpServiceHost or WebHttpServiceHostFactory.

In the ContactManager sample we’re shipping on Codeplex you wll see the following in the Global.asax.

protected void Application_Start(object sender, EventArgs e)
{
    var configuration = new ContactManagerConfiguration();
    RouteTable.Routes.AddServiceRoute<ContactResource>(
        "contact", configuration);
    RouteTable.Routes.AddServiceRoute<ContactsResource>(
        "contacts", configuration);
}

Both the ContactResource and ContactsResource are configured with a ContactManagerConfiguration instance. That class registers the processors for each operation.

public class ContactManagerConfiguration : HostConfiguration
{
    public override void RegisterRequestProcessorsForOperation(
        HttpOperationDescription operation, 
        IList<Processor> processors, MediaTypeProcessorMode mode)
    {
        processors.Add(new JsonProcessor(operation, mode));
        processors.Add(new FormUrlEncodedProcessor(operation, mode));
    }
    public override void RegisterResponseProcessorsForOperation(
        HttpOperationDescription operation, 
        IList<Processor> processors, MediaTypeProcessorMode mode)
    {
        processors.Add(new JsonProcessor(operation, mode));
        processors.Add(new PngProcessor(operation, mode));
    }
}

Notice above the request is configured to support Json and FormUrlEncoding while the response supports Json and Png. These Register methods are called per operation thus configuration of processors can even be more fine grained. Plus you can reuse your configuration classes even across applications.

JsonProcessor / FormUrlEncodedProcessor.

In addition to supporting representing types in multiple formats, we also can support untyped operations with the new Json primitives that come out of our jQuery work which I mentioned above. The JsonValueSample we’ve included illustrates how this works.

[ServiceContract]
public class ContactsResource
{
    private static int nextId = 1;
    [WebInvoke(UriTemplate = "", Method = "POST")]
    public JsonValue Post(JsonValue contact)
    {
        var postedContact = (dynamic)contact;
        var contactResponse = (dynamic)new JsonObject();
        contactResponse.Name = postedContact.Name;
        contactResponse.ContactId = nextId++;
        return contactResponse;
    }
}

In the snippet above you can see that the Post method accepts a JsonValue and returns a JsonValue. Within it casts the incoming parameter to dynamic (there actually is an extension method AsDynamic which you can use) pulls out the name and then creates a new JsonObject which it sets some properties on and returns.

If you look in the JsonValueSampleConfiguration you will see that it accepts Form Url Encoding (something not previously possible in WCF without a lot of work) for the request and returns Json.

public class JsonValueSampleConfiguration : HostConfiguration
{
    public override void RegisterRequestProcessorsForOperation(
        HttpOperationDescription operation, 
        IList<Processor> processors, 
        MediaTypeProcessorMode mode)
    {
        processors.Add(new FormUrlEncodedProcessor(operation, mode));
    }
    public override void RegisterResponseProcessorsForOperation(
        HttpOperationDescription operation, 
        IList<Processor> processors, 
        MediaTypeProcessorMode mode)
    {
        processors.ClearMediaTypeProcessors();
        processors.Add(new JsonProcessor(operation, mode));
    }
}

This is extremely powerful for folks solely working with Uri Form Encoding and Json and who are comfortable/prefer working without a concrete type.

Queryability

One challenge when exposing data over HTTP is how to allow clients to filter that data. In WCF Web APIs we’re introducing IQueryable support on the client and server for addressing these challenges.

Making the service queryable

On the server side, your service operation returns an IQueryable<T> and you annotate it with a [QueryComposition] attribute. Once you do that, your service lights up and is now queryable using the OData uri format.

We’ve included a QueryableSample which illustrates how this works. Below is a snippet from the CoontactsResource in that sample.

[WebGet(UriTemplate = "")]
[QueryComposition]
public IEnumerable<Contact> Get()
{
    return contacts.AsQueryable();
}

The Get method above returns an IQueryable of contacts. (Today the method must return IEnumerable<Contact> but this will be fixed in the near future).

With the query composition enabled, the host will now accept requests like “http://localhost:8081/contacts?$filter=Id%20eq%201” which says “find me the contact with an ID equal to 1”.

Note: Currently this feature is not compatible with our new WebHttpServiceHost / Processors, it only works with our existing WebServiceHost. This is temporary as we are planning to migrate over to the new host / processor model.

Querying the service, LINQ to WCF

On the client side we’re introducing the ability to do LINQ queries directly to resources which are exposed through query composition. We’ve added a CreateQuery<T> extension method which you can use with the new HttpClient (next section) to create a WebQuery<T>. Once you have that query, you can then apply a Where, or an Order by. Once you start to iterate through the result, we will automatically do a Get request to the server using the correct URI based on the filter. The results will come back properly ordered and filtered based on your query.

Below is a snippet that shows querying an Orders resource

public IEnumerable<Order> GetApprovedOrders()
{
    string address = "http://contoso.com/orders";
    HttpClient client = new HttpClient(address);
    WebQuery<Order> orders = client.CreateQuery<Contact>();
    return orders.Where<Order>(o=>o.State == OrderState.Approved).
        OrderBy(o=o.OrderID);    
}

Getting first class support for HTTP

HTTP is more than a transport, it is a rich application layer protocol. There’s a lot more interesting information than just the body which lives in the headers. It is the headers that most of the web infrastructure actually cares about. For example if you want to allow requests to be cached throughout the web, you need to use entity tags which live where? In the headers. Point blank, if you want to access the full richness of HTTP you need to access those headers.

HTTP Messages

We’re introducing support for HttpRequestMessage and HttpResponseMessage. These classes which originally shipped in the REST starter kit allow unfettered and strongly typed access to the underlying HTTP request and response. With these new apis you can access HTTP wherever you are, whether you are authoring a service, or extending the stack and whether you are on the server or the client. Another nice thing about these messages is they are easy to use in unit testing. They don’t have any implicit dependencies to WCF as WebOperationContext does nor are they statically called. They are lightweight data containers that are very easy to create.

For example, you can author a service which receives the HttpRequestMessage and HttpResponseMessage, and which directly accesses the headers and the body. The HelloWorldResource below supports caching on the client side, as it returns an entity tag “HW” which the client can send in an IfNoneMatch header in subsequent requests. The resource can then then return a status 304 to tell the client to use it’s cached copy. The client in this case might not be the browser but a proxy server sitting in the middle.

[ServiceContract]
public class HelloWorldResource {
  [WebGet(UriTemplate="")]
  public void Get(HttpRequestMessage req, HttpResponseMessage resp) {
    if (req.IfNoneMatch.Contains("HW")) {
      resp.StatusCode = HttpStatusCode.NotModified;
      return;
    }
    
    resp.HttpContent.Create("Hello World Resource", "text/html");
    resp.StatusCode = HttpStatusCode.OK;
    resp.Headers.Tag = "HW"; //set the tag
  }
}

The code above would likely be factored into a common set of utility functions rather than being redundantly coded for each operation. The important thing is we’re providing the messages which enables that refactoring.

You can also mix and match using messages with strongly typed objects representing the body. For example you might want to do a redirect on a Get request for a document that has moved.

[ServiceContract]
public class DocumentResource
{
    [WebGet(UriTemplate="{name}")]
    public Document Get(string name, HttpResponseMessage resp)
    {
        Document doc;
        //foo has moved
        if (name == "Foo")
        {
            resp.StatusCode = HttpStatusCode.MovedPermanently;
            resp.Headers.Location = new Uri("http://someplace/Foo");
            return null;
        }
        //find the document
        return doc;
    }
}

Within the ContactManager sample you will see other examples of mixing messages with concrete types.

HTTP Client

Providing a client for consuming HTTP is equally as important as being able to expose it. For that reason we’re also bringing the HttpClient we shipped in the REST starter kit forward. You can use the new client within desktop applications or within services themselves in order to consume other HTTP services. We’re also providing extensions to the client for supporting queryability, which I will cover in the next section.

Below is a simple example of using HttpClient.

var client = new HttpClient();
client.DefaultHeaders.Accept.Add("text/xml");
var resp = client.Get("http://contoso.com/contacts/1");
resp.Content.ReadAsXmlSerializable<Contact>();

Request and response processing

When you work with HTTP, there are various parts of the request and response which need to be processed or transformed . With HttpRequestMessage and HttpResponseMessage we’re allowing you to do this processing within the actual operation as there are places where this is appropriate. However, there are other cases that are concerns that are cross-cutting which don’t belong in the operation. Take formatting for example. It’s very convenient to have the ContactResource simply return and accept a contact, rather than it have to drop down to a message and manually do the formatting. In the same way the ContactResource operation may depend on certain values extracted from segments of the request URI like the ID. In the past we dealt with each of these concerns in a one-off basis. With WCF Web APIs we’re exploring a more general purpose way to handle these concerns. We’re introducing a request and response pipeline of what we’re currently calling Processors. A Processor has a simple execute method with takes inputs and provides outputs. The inputs could be things like the request or response, or outputs from other processors. In this way processors are composable.

Out of the box we use processors today mainly for extracting values from the uri, for content negotation (selecting the format) and for media type formatters. However processors are extensible, and you can introduce your own for adding custom processing within the request or the response.

We’ve already seen above how to create processors specific for formatting. Here is an example of a different kind of processor that takes a latitude and longitude in a URI for example “http://contoso/map/12.3456,-98.7654” and converts it into Location object. Once the location processor is registered, the MapResource.Get method will automatically get a location object passed in.

public class Location
{
    public double Latitude { get; set; }
    public double Longitude { get; set; }
}
public class LocationProcessor : Processor<string, string, Location>
{
    public LocationProcessor()
    {
        this.OutArguments[0].Name = "Location";
    }
    public override ProcessorResult<Location> OnExecute(
        string latitude, 
        string longitude)
    {
        var lat = double.Parse(latitude);
        var lon = double.Parse(longitude);
        return new ProcessorResult<Location> { Output = 
            new Location { Latitude = lat, Longitude = lon } };
    }
}
[ServiceContract]
public class MapResource {
  [UriTemplate="{latitude},{longitude}"]
  public Stream Get(Location location) {
    //return the map
  }
}

The processor above inherits from Processor<T1, T2, TOutput> meaning that it takes two inputs (strings in this case) and it outputs a location. In the execute method the parameter names conventionally match against outputs coming from other processors in this case the method expects “latitude” and “longitude” params. You might be wondering where these parameters come from. If you look on the MapResource.Get method you see that it has 2 parameters named latitude and longitude respectively. A special processor UriTemplateHttpProcessor automatically extracts values from the uri and returns those values as outputs. In this case it returns latitude and longitude thus making those values available to the LocationProcessor (or any other processor).

The logic above is very simple in that it parses numbers. However, you could imagine expanding the processor to do more. For example it could be rewritten to also accept a more expressive uri like “http://contoso/map/12 deg 34’ 56” N, 98 deg 76’ 54” W ”.

This is just a small illustration of the kinds of things you can do with processors. You could imagine handling concerns related to entity tags like IfMatch / IfNonMatch in processors for example.

There’s a lot more to say about processors and their configuration. Look for more on both topics in future posts. Darrel Miller also has a nice post where he talks about processors here.

Conventions, Resources and Testability

We’ve heard plenty of feedback from folks in the community that they would like to see us offer configuration alternatives to attributes and provide more out of the box conventions. We’ve also heard developers asking for us to ensure that we provide better support for test driven development, and using tools like IoC containers. As we move forward we are definitely thinking about all of the above.

Our current focus for the platform has been to enhance the existing Web HTTP programming model to provide richer support for HTTP. These enhancements will likely roll into the framework soon and will provide a very smooth migration path for existing WCF HTTP customers.

Longer term, we are also exploring a new convention based programming model for configuring HTTP resources (services). With this new model we are also looking at how we can enhance it to be more resource oriented, for example allowing specification of child resources so that URIs can be constructed dynamically rather than being hardcoded. This new model will make it’s way to Codeplex soon where we’d like to incubate it with the community.

With the new bits we are delivering we are also being intentional about designing things in a more testable manner for example HttpRequestMessage and HttpResponseMessage allow developers to move away from static calls which are difficult to test. Processors are also easy to test as they each do a single thing, and do not have static dependencies. In addition to the new bits, we are looking at investments we can make into our existing bits to better support testability. For example we are exploring allowing you to plug in an IoC container for service instantiation.

It’s still early, we want your help

We’re still early in the development of these new features! Not all of these features will make it in the box, but many definitely will. You can help us prioritize by checking out our new bits on Codeplex, participating in the forums and adding work items so others can vote.

OK, what are you waiting for? Head on over to wcf.codeplex.com. The future awaits!!!

Taking HTTP support in WCF to the next level

Glenn Block MSFT — Tue, 26 Oct 2010 05:01:00 GMT

If you are building for the web and the cloud, then you know that HTTP is important. WCF is no stranger to HTTP. Since .NET 3.5, we’ve been continually delivering capabilities in the platform to enable developers to expose services as resources over HTTP. Now we’re looking to raise the bar several notches.

At PDC, I’ll be showing work we are doing to unlock the full richness of HTTP within your network based applications.

We’re going to let you have complete control over HTTP.
Support a multitude of media types (formats) i..e XML, JSON, ATOM, OData, and custom formats including those that are hypermedia driven
Give you full access to your Uri and headers,
Provide richer support for web frameworks like JQuery
Provide a more simplified configuration story.

That is just the beginning. We want you to have it your way with HTTP!

Want to hear more? Watch my talk

Building Web APIs for the Highly Connected Web

Friday, 9:00 AM-10:00 AM (GMT-7)

Room: Kodiak

Yet another simplification of Prism’s EventAggregator syntax part II–mocking extension methods

Glenn Block MSFT — Mon, 11 Oct 2010 05:27:51 GMT

After my last post, I had quite a healthy discussion with Alex Hung (@alexhung) on you guessed it, testability and mocking. Alex’s observation was although my extension methods were easy to use, they were difficult to test. He had gone and implemented a similar user experience but through using a custom wrapper which added Publish and Subscribe methods but called to EA under the covers. His wrapper implements an interface that is easy to mock.

The question then was how can you mock the new extension methods? Before getting into the how lets first answer the question of why?

Here are unit tests that should illustrate what I want to do.

[TestFixture]
public class When_SelectOrder_is_invoked {
  [Test]
  public void then_controller_publishes_OrderSelected() 
  {
    //mock out the event aggregator;  
    var mock = new Mock<IEventAggregator>() 
    var controller = new OrderController(mock.Object);
    var order=new Order();
    controller.SelectOrder(order);
    mock.Verify(ea=>ea.Publish(order));
  }
}
[TestFixture]
public class When_OrderViewModel_is_created {
  [Test]
  public void then_subscribes_to_OrderSelected() {
    //mock out the event aggregator;  
    var mock = new Mock<IEventAggregator>() 
    var vm = new OrderViewModel(mock.Object);
    mock.Verify(ea=>ea.Subscribe(vm.OnOrderSelected));
  }
}

Looks simple enough right? I am creating a mock EventAggregator, passing it in and then verifying that the Publish and Subscribe methods are called. Both Alex and I originally though that would work. Though Alex was a bit skeptical.

However the reality is that it cannot work. The reason is because I am creating a mock of IEventAggregator but the methods I want to mock are not on the event aggregator itself, they are extension methods! Yet another proof that what looks like it will work in the blackboard of your mind, often doesn’t hold up any water in the real world.

There is hope though. Extension methods CAN be mocked, but it takes a bit of refactoring. Daniel Cazzulino (@kzu) has a great post on this here. The approach I came up with is based on his. For my extension methods here are the steps I went through in that refactoring.

Created an IEventAggregatorExtensionsProvider interface. This interface has all the methods from my EventAggregatorExtensions class however, the methods are all non-static (obviously) and I removed this from the first param. Other than that the signatures are the same.
Created EventAggregatorExtensionsProvider which implements IEventAggregatorExtensionsProvider. I ripped the implementation of each method out of EventAggregatorExtenions and then moved it into this provider.
Added a private static variable _Provider of type IEventAggregatorExtensionsProvider to EventAggregatorExtensions. The variable initializes itself to a new instance of EventAggregatorExtensionsProvider.
Changed all public methods in EventAggregatorExtensions to delegate directly to the _provider instance.
Added a static SetProvider method which accepts an IEventAggregatorExtensionsProvider which it then overrides _provider with.

Here’s what the resulting code now looks like (which has grown a bit from my first Codepaste): http://codepaste.net/woqq1d

With these changes I can now pass in a mock of IEventAggregatorExtensionsProvider to do exactly what I want. Now my unit tests read like this:

[TestFixture]
public class When_SelectOrder_is_invoked {
  [Test]
  public void then_controller_publishes_OrderSelected()
  {
    //mock out the provider
    var mock = new Mock<IEventAggregatorExtensionsProvider>();
    var ea = new EventAggregator();
    EventAggregatorExtensions.SetProvider(mock.Object);
    var controller = new OrderController(ea);
    var order = new Order();
    controller.SelectOrder(order);
    mock.Verify(p=>p.Publish(ea, order));
}
[TestFixture]
public class When_OrderViewModel_is_created {
  [Test]
  public void then_subscribes_to_OrderSelected()
  {
    //mock out the provider
    var mock = new Mock<IEventAggregatorExtensionsProvider>();
    var ea = new EventAggregator();
    EventAggregatorExtensions.SetProvider(mock.Object);
    var vm = new OrderViewModel(ea);
    mock.Verify(p=>p.Subscribe(ea, vm.OnOrderSelected));
    
  }
}

The main difference is that I am now creating a mock of the extensions provider rather than the event aggregator itself. That means that my mock is the thing that will get invoked by the classes under test.

Actually the EA instance I create in the unit tests is just a dummy and could even be null as extensions methods can be invoked on null instances. That’s because my classes under test are only accessing the extension methods. However I passed it in because it is entirely conceivable one might want to access the actual instance methods.

To be fair there is more ceremony here than the approach that Alex was suggesting as you have to mock the provider and pass in an event aggregator. However the difference I think is marginal, and it works nicely and is completely testable.

What do you think?

Yet another simplification of Prism’s EventAggregator syntax

Glenn Block MSFT — Mon, 11 Oct 2010 05:24:00 GMT

It’s been quite a while since I worked with Prism’s EventAggregator. Today however I need to use it. As soon as I started to write my code, I heard my friend Jeremy Miller in my head saying how much he hates the ceremony of GetEvent<> pattern that Prism’s EA introduces. What he is talking about is code like the following

//publisher
public class OrderController {
  private IEventAggregator _ea;
  
  public OrderController(IEventAggregator ea) {
    _ea = ea;
  }
  public void SelectOrder(Order order) {
    _ea.GetEvent<OrderSelected>().Publish(order);
  }
}
//subscriber
public class OrderViewModel {
  public OrderViewModel(IEventAggregator ea) {
    ea.GetEvent<OrderSelected>().Subscribe(OnOrderSelected());
  }
  public void OnOrderSelected(Order o) {
  }
}

As you can see above, that each time I need to publish or subscribe, I am calling GetEvent<T>

I then found my way back to my buddy Ward’s post on the subject here: http://neverindoubtnet.blogspot.com/2009/07/simplify-prism-event-aggregator.html. In that post, Ward suggested that a way to deal with this was to create an event say OrderSelected which derives from CompositePresentationEvent<OrderSelected>and in so doing removes the need for a special payload class as the event is the payload. He then adds a set of extension methods directly to EA for handling Publish and Subscribe. Using my example above the code would now look like this with his extensions.

//publisher
public class OrderController {
  private IEventAggregator _ea;
  
  public OrderController(IEventAggregator ea) {
    _ea = ea;
  }
  public void SelectOrder(Order o) {
    _ea.Publish<OrderSelected>();
  }
}
//subscriber
public class OrderViewModel {
  private IEventAggregator _ea;
  
  public OrderViewModel(IEventAggregator ea) {
    ea.Subscribe<OrderSelected>(OnOrderSelected);
  }
  public void OnOrderSelected(Order o) {
  }
}

Which is much much cleaner. There’s no longer any need for calling GetEvent<T>(). However, there’s two parts about the approach that I just had a hard time digesting. I am not saying it is a bad approach but:

It requires the event class to inherit from CompositePresentationEvent<T> when I would prefer not having to carry any base class requirement.
It requires that the T that it inherits from is itself.

And so over a year later, I decided to take another crack at it with a slightly different approach. This one doesn’t require any base class so it removes the 2 constraints above. It basically uses extension methods to wrap / unwrap the passed in parameter with CompositePresentationEvent. It removes you from having to know about that event at all.

Rather than chop it up to make it fit the narly CodeBetter column constraints, go grab it at CodePaste here

Makes the code nice and clean. Now my event classes are just simple pocos. It also also maintains the nice syntax that Ward achieved in his pioneering approach that led me down this path.

Next step is we need an IoC autowireup facility for EventAggregator, that would make Jeremy very happy

Being fueled by developer passion

Glenn Block MSFT — Tue, 24 Aug 2010 07:47:00 GMT

Tonite I came across this really nice post from Kelly (@kellabyte) on how passion drives her to continually learn and explore. She also talks about how a simple idea ends up igniting the fires and quickly spawns into putting in a lot of late nights :-) Kelly also talks about the challenge of finding an environment that lets you fulfill those desires as part of your day job rather than just in the off hours. I really appreciate Kelly’s honesty and passion, it shines through in her article.

As a side note, I can totally resonate with what Kelly’s saying. I was there for over 10 years. At each place I was trying to find my “groove”, but none of the places felt quite right. Flash forward and I can say that persistence, resilience and relentlessness finally did pay off (fortunately). Certainly there were many tradeoffs in getting where I wanted to be. And although your employer might not like this, for me it meant jumping around until I found the thing that made me happy.

It can happen….I am living proof!

Check out Kelly’s post. How does it resonate with you?

Let’s meet for Dinner in London!

Glenn Block MSFT — Tue, 13 Jul 2010 22:29:00 GMT

As I mentioned in my previous post, I am in the UK for the week. Sebastian Lambla (OpenRasta) has been kind enough to organize a dinner so I can meet all my geek friends from the Isles. If are in London near Victoria on Thursday eve, 15-Jul-2010 then it would be great to meet! I am sure we’ll have some great conversation on a breadth of topics….and bitching IS allowed :-)

Time: 6:30 PM

Area: Somewhere in the Victoria vicinity (restaurant TBD)

Bringing MEF and REST love to the UK and at FEST 10

Glenn Block MSFT — Sun, 11 Jul 2010 02:18:56 GMT

Next week I’m coming to the UK where I’ll be spreading the MEF love at FEST 10 and in events in a few other cities. I’ll also be talking about REST and the new work we are doing in WCF to provide a better experience for building RESTful systems.

Below is the event schedule

Date/Time	Event	Location	Talk(s)
14 July 2010 10:00 AM to 2:00 PM	Microsoft UK	Microsoft Campus Reading	.NET Managed Extensibility Framework with Glenn Block [A half day of MEF] The Managed Extensibility Framework (MEF) is a new library which is part of the .Net 4.0 framework. MEF helps you build extensible and maintainable applications, which you can evolve over time, by providing a mechanism that promotes decoupling and separation of concerns, and supports plugins. Come join us on this quest for enlightenment in the way of MEF. We will start our journey light with the essentials of composition in MEF: Import, Export and Compose. We will then travel together on the path as we elevate toward master.
14 July 2010 7:00 PM to 9:00 PM	NxtGenUG	Microsoft Research Cambridge	Silverlight Application Partitioning and Extensibility with MEF Wouldn't it be nice if your team could add new features to your applications without all the headache they have to deal with today? With the Managed Extensiblity Framework (MEF) in 4.0 you can bolt your apps together dynamically on the fly. Adding new modules and features is as simple as deploying a new binary, you don't have to touch the existing code. You can even deploy those features as separate XAP files which can be loaded on-demand! Come to this talk for a quick tour of what MEF is, and learn how you can use it to beat out your competition.
15 July 2010 Evening	Geek Dinner	Somewhere in London near Victoria	Register here quick: http://is.gd/dolgi
16 July 2010	Fest 2010!	Bournemouth Pier Bournemouth	Building extensible frameworks with MEF Come to this talk where we will take a deep dive into building frameworks which can easily extended by third-parties. For the first part of the session we will learn about what MEF offers for framework authors as we build a small extensible library which leverages it. Then in the second part we’ll dive into several OSS frameworks that are utilizing MEF for extensibility. We’ll also leave plenty of time to answer any deep questions you have on MEF. REST, It’s more than Data Today it’s very common to simply throw some data over the wire and call it REST. But REST as Roy Fielding described it is much, much more. Come to this session and we’ll explore the tenants of a RESTful system. We’ll start with looking at traditional web services, then we’ll remove the SOAP shackles and explore what we can achieve as we get closer and closer to HTTP. We’ll also look at various frameworks both within and outside Microsoft for achieving REST Nirvana.

All of this is made possible by the fine folks at NxtGenUG who have been gracious to sponsor my trip.

I look forward to seeing all of you on the other side of the Atlantic!!!

Help my friend Scott Hanselman raise $50000 for Diabetes!

Glenn Block MSFT — Thu, 08 Jul 2010 09:30:56 GMT

I’ve got a good friend Scott. He works at Microsoft, he’s a technical leader, and an awesome individual. He also lives every day plagued with being a Type I diabetic. I have known Scott for years and never realized just what he and others like him go through each day as he struggles with this illness. As a matter of fact you can spend quite a bit of time with him without even having a clue of his condition as he is so good at hiding it. Scott never complains, instead he takes action whether it is promoting awareness of Diabetes or helping to raise money to find a cure.

Scott has now set out to raise $50000 dollars for the ADA Diabetes Walk 2010. $30000 has been raised so far, that leaves $20000 to go. He needs your help. Help him! (and all others that will beneift) I and many others did.

Watch the video, get educated, help find a cure!!!

Open sourced .NET libraries in Mono

Glenn Block MSFT — Thu, 08 Jul 2010 08:46:09 GMT

Recently Miguel did a post that made me smile. He talked about several libraries from Microsoft which were released under an OSS license and thus incorporated into the Mono tree and ship as part of Mono 2.8. I smiled for two reasons. One, I was happy to see that Microsoft is becoming more and more open with our development platform. Second, I was happy because MEF was on that list. :-)

The full list is below:

Managed Extensibility Framework, a framework to create extensible applications (blogged about their open sourcing).
The Dynamic Language Runtime is the engine that powers IronPython and IronRuby, but also third party efforts like IronJS and RemObject's Javascript compiler. This lives largely in the System.Core assembly in .NET 4. Some of the code is also used in Mono's version of System.Numerics.
OData's .NET client (System.Data.Services.Client), I blogged about this here.
ASP.NET MVC both MVC1 and MVC2.
Microsoft's AJAX library for use with ASP.NET WebForms.
Silverlight's Controls, these are used by Moonlight.

I hope this is just the beginning!

RESTing from MEF (or The MEF dealer is at REST)

Glenn Block MSFT — Wed, 30 Jun 2010 09:44:00 GMT

Side note: I am having serious writer’s block these days….or maybe it’s twitter’s block :-)

Continuing the tradition of overdue posts…….It’s been over a month since i left the MEF team. Before moving on let me say that working on MEF was a fantastic experience! The team is very excited to see all the community interest and adoption we’re seeing with MEF in commercial products, internal applications, as well as OSS projects. Thank you all for your support over these past two years.

Where am I?

I’ve moved over to the WCF team where i am now RESTing :-) My focus is on providing platform support for distributed applications that communicate over HTTP and which conform to a RESTful style. If you are using WCF, then you may be familiar with WCF WEB HTTP which shipped with the .NET Framework and the REST Starter kit which shipped out of band. That’s my team.

Why HTTP and REST.

HTTP is the application layer protocol that the web is built on. Browse to any web page and you immediately see HTTP in action in this case for delivering HTML web pages. HTTP is not limited as a transfer for HTML, it’s much richer. You can use HTTP for delivering data as well as core application functionality, and you don’t have to use SOAP to do it. Applying the constraints of REST lets you take direct advantage of the capabilities HTTP provides in order to achieve greater scalability, performance and evolveability.

For example if you are using a blog reader to read this post, then it is very likely that you have subscribed to an Atom feed. AtomPub is one popular incarnation of RESTful principles that is primarily used for data feeds such as a blog, a video queue, etc. If you’ve heard our recent announcements about OData, it builds on top of AtomPub to provide a protocol for querying and updating data. Another popular usage of REST services is for building AJAX style applications which communicate with the server using JSON. REST however is not at all limited to these scenarios, as a matter of fact you can apply REST to solve many of the problems that today you are doing through SOAP based services albeit in a different (and many argue simpler) fashion.

It’s not WS-* and that is a good thing

REST doesn’t bring all the bells and whistles of the WS-* protocols, however its power is in its simplicity. That means no SOAP client stack required. For many systems the “power” WS-* brings is unnecessary, and that power is not free, that means it can turn into a tax. That doesn’t mean WS-* in itself is bad…it definitely provides value.

There’s a growing momentum in the community and the enterprise for building RESTful systems and for frameworks which enable that. Take a look at programmableweb.com and you’ll see 1500 APIs listed under the REST category. These APIs run the gambit in terms of their application of RESTful principles, but regardless it is clear that companies are looking more and more to expose their systems over HTTP.

Why do we need something new?

One word, Freedom. Freedom to work directly with the protocol and freedom to harness all of it’s richness.

The work we did in WCF 3.5 and 4.0 was a great first step. It allows you to use the traditional WCF service model and tweak it to behave well over HTTP. However, it has it’s limits. WCF was designed to shield the service author from any of the underlying transport details. It was also designed around an RPC style of communication, i.e. a Service operation corresponds to a method. Folks that are exposing services (Resources) over HTTP don’t want those details hidden, in fact they embrace them. HTTP is also not based on classes, types or methods, its based on resources and verbs.

We want WCF to provide a natural experience which allows you to fully embrace HTTP within your development. We want to allow you to develop in a resource-oriented style. To that end we’re looking to extend WCF and introduce a set of client and server APIs completed based on HTTP. Those apis will enable building RESTful systems, or RESTful frameworks to build RESTful systems :-)

What about WCF Data Services?

WCF Data Services is designed to allows developers to expose entity data models using the OData protocol such that they can be queried and updated by OData clients. The work that we are doing with WCF WEB HTTP is to enable both clients to interact with arbitrary resources exposed over HTTP, as well as to enable exposing resources over HTTP in an arbitrary manner. It’s basically the “have it your own way” of HTTP.

We’re not the first to the party

Look across the .NET OSS community alone and you will see there’s a healthy ecosystem budding of frameworks like OpenRasta, RestSharp, Hammock. Glance into the Java, Ruby and Python worlds and you will see the same with frameworks like Restful Rails, Sinatra, RESTlet, RESTfulie (also in C#), and Jersey to name a few. Oh and don’t forget JQuery and ExtJS :-) All this existing innovation is a great thing! It means we have a lot of existing mindshare we can pull from to ensure that whatever we deliver plays by the rules.

Two key goals: Simplicity and Testability.

Less is more. We want to do less but make sure whatever we do is really easy to use (and really useful).

Simple to test. Not technically feasible to test after you do a lot of work :-)

We want your help

We’re not going about this alone:

We want you to help us get there.

We want you to validate that what we’re building meets the needs and that we’re playing by the industry rules.

We want you to tell us that what we’re building is right, rather than us telling you it will make your life better.

We’re still in the early phases of determining exactly what that means, but if you followed the way MEF was developed you can imagine ;-)

You don’t have to be using .NET or Microsoft technologies to help

If you are passionate in this space we’d welcome your involvement. I look forward to making this new journey with you.

Way of MEF slides and Code

Glenn Block MSFT — Sun, 13 Jun 2010 07:11:52 GMT

Thanks to everyone who came out to the “Way of MEF” education day in Cupertino. I had a great time and you were an awesome audience. I really appreciate all the great / in-depth questions. It showed that you really were keeping along. I also enjoyed all the different side conversations, and all the times you guys overwhelmed me at the breaks. I really do love this stuff!

Here is a link to get you access to the code and the slides: http://cid-f8b2fd72406fb218.office.live.com/browse.aspx/Public/Way%20of%20MEF

If you download the code it contains the following:

HelloMef_Simple - The simple widget example we built
HelloMef_Extended - Sample that downloads multiple XAPs and which demonstrates ExportFactory.
MefRules_Simple - The simple rules engine we built on the fly
MefRules_Extended - More complete rules engine sample which uses rule metadata and contains a runner for Silverlight and Desktop.
DynamicObjectContracts - Demonstrates a simple illustration of using dynamic exports and imports
PartUpdatesInPlace - Demonstrates uses shadow copying to allow hot swapping / removing parts on the fly. (the one that the audience asked me about)

Here are additional links:

Default exports: http://blogs.msdn.com/b/gblock/archive/2009/05/14/customizing-container-behavior-part-2-of-n-defaults.aspx
Filtered Catalogs: http://mef.codeplex.com/wikipage?title=Filtering%20Catalogs&referringTitle=Guide
Config export provider: http://codepaste.net/en44vo
Ruby and MEF: http://blogs.msdn.com/b/nblumhardt/archive/tags/ruby/
ASP.NET MVC and MEF: MEF and ASP.NET MVC sample updated
ASP.NET Web Forms and MEF (doesn’t use CompositionInitializer approach): WebForms and MEF Sample
Diagnosing MEF - http://blogs.msdn.com/b/nblumhardt/archive/2009/08/28/analyze-mef-assemblies-from-the-command-line.aspx

Finally as promised, if you have questions that were not answered in the talk, feel free to comment here or email me direct and I will answer them in a follow up post.

Thanks to Mathias Brandewinder, Kevin Rohling, his nutty girlfriend and recruiter extraordinaire Megan Hopkins and the Bay.NET UG for hosting me. I had an awesome time.

Yes, I know I need to post on what I am working on now……I hear you, pleae be patient :-)

MEF day in SF, “The Way of MEF, the Path to Enlightenment”

Glenn Block MSFT — Thu, 03 Jun 2010 08:08:12 GMT

On Saturday June 12th I am stoked to be coming to the SF bay area on behalf of the Bay.Net UG where I’ll be delivering a full day on MEF!

We’re going to cover a world of topics as you can see from the list below.

1. How to lazily instantiate parts to conserve processor cycles
2. Self-describing parts in order to allow more flexible discovery
3. Diagnosing common MEF failures
4. Adapting legacy components to work with MEF
5. Partitioning your Silverlight applications across multiple XAPs to reduce download cost and improve startup time
6. Providing default overridable parts
7. Using hierarchical containers for scoped composition
8. Creating custom catalogs to apply custom policy for filtering
9. Creating export providers to integrate with existing service providers
10. Composing UIs with MEF / MEF with Prism
11. Implementing MVVM with MEF

The cost is $39. Register here while there is still time!

MEF has shipped!!!

Glenn Block MSFT — Thu, 03 Jun 2010 01:26:00 GMT

You might have missed it, but a few weeks ago MEF V1 shipped in .NET 4.0 and Silverlight 4! As a team we’re really happy to have seen MEF hit the wild. We believe MEF helps you to build better applications that are easier to extend. To get started with MEF, go visit our wiki here

So far we’ve been hearing lots of goodness from customers that they feel the same. We’ve also been really happy seeing a healthy set of projects in the open source community pulling in MEF to address their extensibility challenges within their frameworks and applications. We’ve also had some interesting ports of MEF which is a great outcome of having an OSS license!

Below is a list of some of the folks internal and external to Microsoft that are using MEF along with the scenarios for which they use/support us (in a completely random order)

Visual Studio 2010	New extensible editor Project system uses MEF under the covers VS Ultimate uses MEF for it’s UML designers Several other teams like EF use MEF for their designers
MEF Contrib	Community driven extensions to MEF
Silverlight Analytics Framework	Allows plugging in different analytic engines through MEF
Silverlight Media Framework	Uses MEF for plugging in various extensions relating to the player
TypeMock Test Lint	Uses MEF for allowing you to plug in your own custom rules
RavenDB	Uses MEF to allow plugging in triggers
Caliburn	Supports plugging in MEF as a service provider
Common Service Locator	Provides an adapter for working with MEF
MefedMVVM	MEF handles discovery and wire up of View Models both at runtime and design time
PHPMEF	Yes, it’s possible, MEF for PHP :-)
PocketMEF	MEF for PocketPC
Mono	Yes you heard it right, MEF 3.5 joins MVC2, System.Dynamic and OData client as part of the mono.

MEF V1 has been an awesome ride. The best part has been the fantastic community that worked with us every step of the way giving us continual feedback and ensuring our success as well as our internal partners who pressed hard on us to keep us honest. Thank you for all your help and support!

I also want to thank my team for the fantastic work they did. It was an amazing experience building MEF together!

Sit tight, MEF v2 is on the way!

Caveats about DeploymentCatalog

Glenn Block MSFT — Tue, 13 Apr 2010 20:58:00 GMT

The information below was wrapped up in my previous post on DeploymentCatalog. As a bunch of folks have been asking questions on this, it seems worth to rip out on it's own.

A few caveats about DeploymentCatalog.

DeploymentCatalog is a very exciting addition to the MEF box. There are a few caveats to it’s usage.

Does not support Silverlight cached assemblies. (Otherwise known as TPEs). This means that DC will not download referenced assemblies that are packaged with the Silverlight caching infrastructure (.extmap).
- This includes cached assemblies in the main xap.
- If the cached assemblies are referenced by the main app, they will be available to the assemblies in a downloaded XAP.
- You can create shared xaps which contain assemblies to be used by other xaps and download those with the DeploymentCatalog. As long as the shared xaps are downloaded first they will be available to others.
- If you do decide to use either of the previous approaches, be sure to set your references to “Copy Local = False” in your XAPs otherwise you will be embedding the shared assemblies again.Does not support localization.
- We are looking into cached assembly support in the future.
Does not support non-embedded resources.
Local resource references in XAML also are not supported i.e. using pack URIs. You can programatically access embedded resources though.