Infovark Underground

In our previous programming jobs, neither Gordon nor I had to do much testing. We tended to focus on architecture and development issues. Just prior to forming Infovark, we were acting as consultants for an ECM vendor that has since been snapped up by HP. So while we were aware of things like unit testing and test-driven development, we’d never had to do much of it ourselves.

We knew it was important, though. We’d seen too many things go wrong in software projects that didn’t make testing a core part of their standard operating procedures. So we incorporated testing into our product development and we’ve been learning about this testing stuff as we go. (It always happens that way, doesn’t it?)

We began with NUnit, the gold standard for unit testing on the .NET Platform, and quickly discovered some things that everyone else already knew:

1. Good unit tests are essential for refactoring. It’s the only way you can make big OO changes with confidence that you haven’t broken anything that used to work.
2. Good unit tests are are essential for troubleshooting. It makes it much easier to pinpoint the source of the errors when things go wrong.
3. Good unit tests are essential for making your product fail gracefully. Every program will fail at some point. It’s how a program reacts to a failure condition that counts.
4. You can’t write good test suites without good specifications. You’ll forget to test key assumptions and dependencies. You won’t confirm error conditions. You’ll couple your tests to your current object model, rather than to program requirements.
5. If you’re doing it right, you’ll write far more code for testing than for the product itself. It’s much harder to verify correctness than it is to write correct code.
6. Unit testing is different from integration testing. Integration testing is different from system testing. All three are important.

In addition to these common nuggets of TDD wisdom, we also discovered something else: It’s dreadfully easy to shoot yourself in the foot with NUnit tests. It’s easy to write tests that aren’t atomic, for example, or tests that expect errors to occur in one line of code that pass because another line of code throws a similar error.

To address some of these quibbles, a splinter group has launched xUnit on CodePlex. It aims to simplify testing syntax, incorporate more .NET 3.5 constructs, and prevent some of the more common NUnit anti-patterns that testing neophytes (like us) regularly develop.

We’ve messed around with XUnit a bit, and so far we like what we see. It’s not enough yet to make us abandon NUnit though, especially with NUnit 2.5 on the horizon. Besides, the NUnit framework is integrated with a variety of other development tools we’ve found indispensable. (I.e., everything made by JetBrains.)

But that’s just our opinion. What do you think? How do these things stack up? And what about the testing framework built in to Visual Studio Team System? We’d love to hear your experiences with these tools.

The BCLTeam just released a really neat looking tool that makes it much easier for us Managed Code types to interoperate with the dirty bowels of windows (also known as the Win32 API : )

Called the P/Invoke Generator, it inspects any Win32 API call, and then generates the interop code that you need to be able to call it in either C# or VB.Net. It also lets you generate P/Invoke calls from any other native library.

Nice one! You can download the tool for zero dollars over on CodePlex

The easiest way to explain the issues we encountered when implementing REST is to work through the design principles we followed. I think much of our trouble came from the fact that we come from a web applications background, not a SOAP services background. I’m hoping that by laying out our REST design, some of the Microsoft gurus can help us do things “the WCF way.” And perhaps we can help the WCF team out by highlighting a handful of places where we found WCF unintuitive.

The Importance of Being Addressable

Fundamentally, the REST pattern is about making resources available. This means that each item stored within your system can be accessed by someone with the correct permissions. Every one of these items has its own unique address, and its address should not change. This consistency is important, because it allows both people and computer programs to remember and reference items in your system.

Note that we’re talking about resources or items. In contrast with the SOAP model of web services, which allows programmers to invoke procedures on remote computers, REST is about providing data. SOAP is about verbs, while REST is about nouns. A SOAP service might CalculateTotalSale(); a REST service provides CustomerRecieptNo_12345. The kind of web services architecture you use will depend on the kind of application you’re building. The choice has major implications for the other components of your system.

REST imposes restrictions on what sort of things you can do, because it supports only a handful of actions: GET, POST, PUT, and DELETE. (There are a few other HTTP methods, but these four are the most important.) Fortunately, with these four actions, you can accomplish most basic programming tasks. There’s a close parallel to these actions and create/read/update/delete, or CRUD, the building blocks of data storage systems.

UriTemplate

Since the address, or URI, is the primary way to access information in your system, it’s effectively part of your user interface. All the principles of good user interface design apply. So when designing a REST service, you need fine control over the structure of these identifiers.

SOAP, by contrast, typically has just one endpoint. The address itself conveys no information about what services are provided — that’s why SOAP services require a separate WSDL file to tell folks what’s possible. With REST, it should be easy to discover the extent of the system by looking at the URIs alone.

Coming up with good REST URI patterns can be tricky. Using short, descriptive naming conventions for your resources makes them easier to type. But URI patterns must also be distinct and unambiguous.

In the .NET framework, you use the UriTemplate class to define patterns. The UriTemplate implementation that shipped with .NET 3.5 allowed you to define variables that fit into slots in your URI. A typical UriTemplate might look like this: http://restserver/{object}/{id}?view={viewname}.

WCF looks for incoming URIs that match the patterns you define. The pattern defined above would match the following URIs:

• http://restserver/customer/5?view=profile
• http://restserver/article/how_to_do_stuff?view=print
• http://restserver/author/John-Smith?view=1

Once you’ve defined a UriTemplate, you bind it to a method that has the same number of parameters. (I won’t go into the ABCs of WCF here, but you can check out this MSDN Introduction to WCF if you need a refresher.)

In WCF 3.5, you could only define a variable for a whole segment. A segment is basically the bit between the one forward slash and another, or one querystring parameter. A few bloggers requested more flexibility in UriTemplates, and the WCF team answered with the soon-to-be-released 3.5 SP1. The ability to define variables for partial segments was crucial for our URI design.

Representation Matters

Most books about web services, including RESTful Web Services, advocate leaving off file extensions from your URIs. This makes sense for SOAP, where you’re accessing methods and all responses are transmitted in XML. But in REST, you’re serving up items.

In our case, some of these items being served were files and some were records from a database. It seemed inconsistent to have some endpoints that had file extensions and others that didn’t. And we also wanted to be able to serve up different representations for our database records. Our REST service supports both JSON, XML, and HTML. It made sense to use a file extension to distinguish between the different representations.

One workaround would have been to create endpoints like http://restserver/form/1040/xml but that looked funny next to URIs like http://resterver/file/documentation.pdf. True RESTafarians would point out that neither the “/xml” or the “.pdf” are needed, since you can request an appropriate representation using the HTTP ACCEPT header. We decided against the header approach because not all browsers use the ACCEPT HTTP header. Besides, it might be useful for us humans to be able to reach alternate formats by simply changing the URL in the browser address bar.

In WCF 3.5, this required us to create three times the number of endpoints, with a separate method to handle each. We can’t wait for the official release of 3.5 SP1 to make UriTemplates like http://restserver/user/{id}.{ext} possible.

The Final Slash

Another source of endpoint duplication was the need to have two different endpoints for http://restserver/folder and http://restserver/folder/. Because the slash is used as a segment delimiter, the dispatcher in WCF 3.5 saw these two URLs as fundamentally different.

So handling what we thought were fairly trivial cases in URI patterns led us to create FIVE TIMES the number of endpoints we wanted. It’s a maintenance nightmare. SP1 can’t get here soon enough.

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.

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.

As I’ve mentioned previously, I’m someone who likes his code logical and tidy. While I’m just as guilty of playing the F5 game (a.k.a. “try it and see”) as any other developer, it really bothers me when I write code I don’t understand. I’ll spend hours researching a handful of lines of code in a sample posted on someone’s blog. I like to think that it makes me a better programmer. After all, I’ll be in a much better position if I have to write something similar in the future, or to troubleshoot any bugs that appear. And those pesky bugs love hiding in the dark corners of your code.

But that habit of mine can also lead me down some rabbit holes. I’ve given a name to one hole I tumble into on a regular basis. I call it “Fighting the Framework.”

First, a definition. Fighting the Framework occurs whenever you, the programmer, begin second-guessing the code library, development environment, or other tool designed to make your life easier. This second-guessing might happen because you’re convinced that the framework is too heavy, carrying unnecessary baggage when you only need a few lines to handle a particular case. It could happen because the style or idiom of the language is unfamiliar to you. It might be because the framework gets between you and the metal, forcing you to deal with high-level abstractions when you already understand the fundamentals. Whatever the reason, when you’re Fighting the Framework, you’re doing the programming equivalent of swimming upstream. The flow is against you. Everything seems harder than it should.

It’s at this point that I’ll waste hours of time researching alternate frameworks, refactoring already working code, staring off into space, or reading Slashdot. When you see a programmer doing things like this, it’s the equivalent of a child pushing peas around on the dinner plate, trying to find a configuration that tastes better.

Eventually, you just have to accept the fact that every possible configuration of peas on the plate will taste exactly the same — ick — and eat them. Don’t fight the framework. You picked it for a reason. It’s good for you. Perhaps even character building.

Pros and Cons

I’m in exactly this position with Microsoft .NET right now. Gordon and I picked the Microsoft platform for two solid business reasons:

1. Our application targets knowledge workers, and most businesses run Microsoft Office.
2. Both Gordon and I have prior experience working with C#.

At the same time, our choice of platform comes with some hefty drawbacks.

1. All the cool kids are using Ruby or Python or PHP. How can we call ourselves a “2.0″ company if we’re using the platform that all but defines the 1.0 approach?
2. Much of the innovation that’s happening in the software space is not happening on the .NET framework — something that Microsoft has belatedly realized. That means we often have to choose between using ports of software written for another technology stack or rolling our own libraries.
3. We have to deal with certain Microsoft biases when it comes to application setup and deployment. (This wouldn’t be a major issue if our product weren’t so idiosyncratic. But hey, if we weren’t doing something dramatically different, we wouldn’t have set out to do it as a small ISV.)

Deciding what technologies to use in your product is hard. ReadWriteWeb lists five things to consider when picking a platform. Eric Sink provides guidance about building on solid foundations. Yet despite all the great advice, it isn’t easy to settle on one or two core providers. Especially when you feel you have to accept their entire programming paradigm, warts and all.

Spinning My Wheels

In the last two weeks, I’ve dealt with no fewer than three different .NET namespaces that have come up short. I could write several blog articles about what was missing — and probably will at some point — but right now I’ve got to stop dreaming of Rails, Adobe Air, or Google Gears. It’s time to take my own advice: Dean, the grass may be greener on the other side, but for now you’ve still got to mow your patch.

Don’t fight the framework.

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!

Firebird News just announced the release of Firebird 2.1.

We’ve been using Firebird as infovark’s SQL database for several months now. It’s an open source fork of Borland’s InterBase SQL server. So far, we’ve been extremely impressed by the database itself. Its companion database administration tool, FlameRobin, is shaping up nicely too. It’s currently in version 0.86, but it handles most of what we need.

Why did we choose Firebird? I’ve worked with a variety of databases during my career, including Microsoft’s SQL Server, Oracle, and MySQL. While we were strongly tempted use one of those, none of them met our criteria. We needed an embeddable, scalable, ANSI-compliant database that we could deploy easily. It also had to have liberal licensing arrangements and low (or no) royalties. That limited our available choices.

Two features persuaded us to give Firebird a try: It was free to use and the entire database is contained within a single file. I’m glad we did; it’s absolutely the right choice for us.

I wouldn’t recommend it for everyone, however. If you haven’t done much work with relational databases, Firebird is not the place to start. While the Firebird community is working on documentation and tools, they’re far behind what you’ll find at a commercial vendor or some other open source products. The Firebird website is tricky to navigate and lacks a search feature. Trying to get pointers from Google is tough, too, due to a certain American muscle car with the same name. (Tip: Search for Firebird SQL to get the database.) You’ll most likely need to rely on a combination of the Firebird website, InterBase documentation, and developer blogs to get specific information.

If you can look past those issues — and they’re common ones in the open source space — you’ll find FIrebird to be a solid database for development across a variety of platforms.

But keep Lorenzo Alberton’s cheat sheet handy, and bookmark Stefan Heymann’s reference site.

As we mentioned recently, we’re building the infovark server using the REST pattern. Since REST is more a loose set of guidelines than a strict series of rules, it’s hard for implementers to know where to begin.

OK, you could go to the source, chapter 5 of Roy Fielding’s dissertation. Or you could check out the somewhat academic discussions on the REST wiki, though there hasn’t been much activity lately. You can occasionally find good advice from the odd blog post, like the REST for the Rest of Us article at Open Garden. But ironically, there’s not a whole lot of material about implementing REST web services available on the web yet. (If you know of good links, leave a comment.)

For the practical, gritty details of how it’s actually done, you’ll need the RESTful web services book by Sam Ruby and Leonard Richardson. They describe the principles that inform REST-ian (RESTafarian?) design in detail, taking you step-by-step through two different sample applications. If you’re a Ruby programmer using Rails, you’ll find the book especially valuable, since that’s the language and framework in which most of the examples are done. For those of us using different technology, it’s the thought process behind the examples that is most illuminating.

This is because the key challenge of the REST paradigm is the fact that it can’t really be implemented on today’s web without some workarounds. REST will come into its own with HTML 5. The book steers an interesting course between how REST web services might be done in HTML 5 with how they must be done today. I think the authors get the balance right, but at times it can make for a frustrating read for someone wanting practical advice about building a REST service right now.

But that’s less a criticism of the book than of the openness of the REST concept itself. The occasional what-if digression the authors make is a small price to pay for the amount of sound guidance you get. The appendixes alone, which discuss things like which HTTP status codes and headers are worth implementing and which are worth forgetting, will save you far more time than you’ll lose in reading how great things will be when HTML forms finally support the PUT method.

Until that day comes, keep this book handy.

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:

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?