Archive for Web Services

WCF Instance Context

I finally figured out the source of my HTTP 400 problem. Apparently the Windows Communication Foundation deals with exceptions differently depending on your InstanceContextMode settings. I had been using the Single setting but I should have used the PerCall setting. In PerCall mode, the try/catch block works as expected.

I think it has something to do with the way that WCF distinguishes between channel exceptions and message faults.

Anyway, if you’re building a REST web service, you’ll want to make sure your class is decorated with the following ServiceBehavior attribute.

  1. [ServiceBehavior(InstanceContextMode = InstanceContextMode.PerCall)]

Using WCF for REST, Part 2

In part one of this series, I listed several websites and blogs that had useful information on the Windows Communication Foundation (WCF) and REST. I also mentioned that if I was stating again, I’d probably use something other than WCF. Perhaps deriving my own REST server from System.Net.HTTPListener, for example.

Vish asked for some additional details in his comment to that post. He works on the Microsoft WCF development team and was curious about our experience.

I had just begun putting together my response when I noticed Scott Guthrie’s post about Service Pack 1 for the .NET Framework 3.5 beta release. Steve Maine also posted specifics about the ADO.Net Data Services and WCF changes.

So, Vish, it seems your team’s beaten me to the punch on some of these issues! Many of the difficulties I was having with WCF and REST were addressed by the service pack. Here’s an overview of our key stumbling blocks:

  1. REST requires much greater control over the URI than SOAP does, and the URITemplate class just wasn’t up to the task. We had to hardcode most of our endpoints to compensate. (Fixed in SP1. Hooray!)
  2. Supporting multiple formats, such as serving both XML and JSON, either require you to program against Stream or require twice the number of endpoints.
  3. Existing serializers had trouble with complicated object graphs, forcing us to perform serialization/deserialization ourselves. (This seems greatly improved in SP1.)
  4. WCF allows only one contract/interface per endpoint. This makes it tricky to factor out common contract patterns.
  5. Good REST practice would have you return many kinds of errors as HTTP status messages. SOAP embeds all error information in the returned XML. WCF is closely aligned with the SOAP approach, which means that you’ve got to be very careful distinguishing exceptions from faults when implementing REST in WCF. It was an unpleasant surprise, and we had to do quite a bit of work to deal with that.

I’ll talk about all five of these areas in more detail in upcoming posts in this series. And I’ll be sure check out the SP1 beta once we get our Infovark Alpha release out the door.

Using WCF for REST, Part 1

Just because you can do something doesn’t mean it’s a good idea.

We decided to use the Windows Communication Foundation to drive our REST-based web service. In hindsight, it was a poor choice. REST support in WCF seems like it was a last-minute addition to .NET 3.5. You can certainly hack something together, but I’ve found few real-world examples on the Internet, and most of those sidestep the tricky issues.

Here’s the short of it: WCF was designed for RPC-SOAP. More importantly, it was designed to SOA-enable legacy services that used older communications channels like DCOM. If you’re starting from scratch, and have full control over the output of your web service and the design of your object model, I’d recommend using a different (and simpler) framework.

We’ve gotten a good bit of blog traffic from people looking for help with Windows Communication Foundation and the REST architectural pattern. (It’s good to know that we’re not the only ones needing advice.) Here are the better sources we’ve found so far.

Windows Communication Foundation documentation on MSDN

Good overview presentation on REST and Syndication using WCF

Microsoft’s Picture Services Sample

Justin Smith’s WCF articles on Cybertopian Chronicles

Nicholas Allen’s Indigo blog

Steve Maine’s blog

Assorted posts on Rick Strahl’s blog

That Indigo Girl

If you find other useful places to look, let us know!

WCF Bad Request

I’ve just identified a horrible bug in WCF for the .NET Framework 3.5.

A caught exception in a WebInvoke operation will cause WCF to return an HTTP 400 Bad Request status code to the client. Any caught exception. Every time. Regardless of whatever error code you might want to send back.

I found the error by mistake. I’d used “BadGateway” instead of “BadRequest” in my code. If it weren’t for other odd WCF behavior, I wouldn’t have noticed that my status code was being ignored.

Consider the following example:

  1.  // Read the Xml into our object and save.
  2.  try
  3.  {
  4.   // The following line triggered the error.
  5.   obj.ReadXml(reader);
  6.   obj.Save();
  7.   // Set HTTP Cache Options and MIME Type.
  8.   Utilities.SetCaching(WebOperationContext.Current, obj.DateModified, 60);
  9.   Utilities.SetMimeType(Format.Xml);
  10.   return Utilities.GetXmlStream(obj);
  11.  }
  12.  catch (Exception e)
  13.  {
  14.   // Was it a schema validation error? If so, provide detail.
  15.   if (!string.IsNullOrEmpty(_XmlValidationErrors))
  16.   {
  17.    // I slipped here, using BadGateway 502 instead of Bad Request 400.
  18.    // But WCF doesn't care. If you enter the catch block it's _always_ 400.
  19.    WebOperationContext.Current.OutgoingResponse.StatusCode = HttpStatusCode.BadGateway;
  20.    WebOperationContext.Current.OutgoingResponse.StatusDescription = _XmlValidationErrors;
  21.    WebOperationContext.Current.OutgoingResponse.SuppressEntityBody = false;
  22.    return null;
  23.   }
  24.  }

If no error occurs, WCF will return the status code you specify. A try/finally block will work just fine; WCF returns whatever status code you specify. Enter a catch block, though, and it’s nothing but 400 Bad Request.

Hey, if there’s an error, it must be the client’s fault, right?

The Address Bar as the New Command Line

It’s been a common meme over the past few years that command-line interfaces (CLIs) are making a resurgence. Jeff Atwood noted in 2005 that the Google search box is a command line of sorts. In early 2007, Lifehacker’s Gina Trapani listed several examples of CLIs showing up in a variety of applications.

The return of the command-line interface is striking. It was pronounced dead, replaced by the graphical user interface (GUI) more than two decades ago, after usability research discovered that novice users were much more comfortable with GUIs. But a CLI has three big advantages over a GUI.

The first advantage is speed. Expert users find that command-line interfaces are significantly faster than GUIs. People can type much faster than they can identify a link or button, move the mouse to it, and click. This is especially true if the user’s hands are already positioned above the keyboard. People that do a significant amount of word processing (or writing code) often memorize keyboard shortcuts to avoid having to grab the mouse. It might save only a fraction of second, but if you do it many, many times over the course of the day, those split-second differences add up.

The second advantage is that a command line interface is a linear interface. Neither the user nor the application have to worry about the exact position of the pointing device over a two-dimensional surface. This makes command-line interfaces ideal for devices that have tiny screens, or whose pointing devices aren’t very accurate. It’s much easier to text a few commands on a cell phone or PDA than it is to use a stylus or manipulate a touch screen.

These first two advantages of CLIs are are well-known. The third advantage is less obvious: It turns out that CLIs are also much easier for computers to use.

Why do we care about making things easier on our silicon-based friends? Well, one reason is that it indirectly makes things easier on those of us humans that give instructions to computers. (As a programmer myself, that’s a big selling point.) Another reason is that if it’s easy enough for a computer to figure out, then it ought to be brain-dead simple for a human to understand. As I’ve pointed out before, computers just aren’t very bright.

So the advantage of having a command-line interface is that if you, a human, get bored of typing the same silly commands over and over, you can easily write a small program that instructs a computer to do it for you. This is the reason why every office suite has some kind of macro language. It allows humans to hand off repetitive tasks to a machine so that people can get on with the important creative stuff.

So what’s this about using a browser’s address bar as a command line? With AJAX technologies, the URI is no longer merely something that a human types into the address bar to get a web page. It’s also an interface that computers use to interact with data. This means the humble web URL shares most of the key characteristics and advantages of a command line interface.

It’s this insight that’s led to increased interest in the REST architectural style. REST has begun moving into the mainstream because the patterns it promotes allow the URI to serve an audience of computers as well as an audience of humans.