Don’t Fear The Web.config

There’s someone at our organization — I’m not going to name names — who handles Web.config files as if they’re unexploded pieces of ordnance.  Now, to be fair, he’s probably seen a lot more borked websites than I have and, often, the problem is a Web.config change.

For those of you that aren’t ASP.NET developers, the Web.config file (located in your site root) is the primary configuration file for IIS (Internet Information Services).  Unfortunately, it’s one of the more obtusely-documented aspects of IIS web development.  The wheat/chaff ratio in the MSDN documentation is pretty low, though they do provide a fairly comprehensive reference (all of these links are for .NET 4.0, but you can access previous versions by clicking on “Other Versions” at the top of the page).

There’s no doubt that the Web.config file is a critical part of your site’s configuration, and even a small mistake can bring your site to its knees, serving up a yellow screen of death to your visitors.  Because it’s such a critical resource, we have a…”protocol” for handling production deployments.  The protocol goes something like this:

1. Download the existing Web.config from deployment as a backup
2. Make sure you don’t upload a new Web.config file
3. Double-check that you’re not uploading the new Web.config file
4. Upload anything you want AS LONG AS IT’S NOT THE Web.config FILE

On those instances where actual changes need to be made in the Web.config file, we have a slightly different protocol:

1. Download the existing Web.config from deployment as a backup
2. Backup the backup
3. Take half a dozen Maalox
4. Examine (by hand, mind you) the differences between your development Web.config file and the backup backup
5. Cherry-pick the changes you think are needed and (by hand) apply them to the backup
6. Take three more Maalox
7. Upload the Web.config file
8. Enjoy your Yellow Screen of Death
9. Frantically restore the backup backup before your client’s CEO calls your CEO and your CEO comes to yell at you
10. Repeat steps 3-7 until step 8 no longer applies

One thing you’ll notice is missing from this protocol is “update the development Web.config” or “add updated Web.config file to source control.”  The astute reader will immediately see the problem: as the production and development Web.config files diverge, this protocol gets more and more difficult every time.

As much as I enjoy this fear/panic cycle, there have been changes and improvements to ASP.NET, IIS, and Visual Studio that suggest a much different protocol is available:

1. From Visual Studio, click on “Publish”
2. Enjoy the sound of your CEO not yelling at you

Alright, maybe I’m employing the slightest bit of hyperbole to underscore my point, but the upshot is all true.  So let’s look at the two things that have made this possible.

The first is Clean Web.config Files.  If you’re using straight-up ASP.NET (no MVC), you can get your Web.config file down to 12 lines.  Awesome!  The gain isn’t so great if you’re using MVC, but you’re still looking at Web.config files that are 25%-75% smaller than they were.  I’ve got a couple of MVC projects going, and the Web.config files are hovering around 90 lines, and that includes whitespace and comments.  I hope Microsoft eventually can make a MVC Web.config file that’s as compact as an plain ASP.NET one.  That would be a big improvement.

The second — and more important — improvement is Web.config Transformations.  This is what really makes it possible to fearlessly deploy Web.config files to production, but it does require a little discipline and forethought.

My purpose here isn’t a tutorial on using Web.config transformations.  Other people have covered that material very deftly here, here, and here.

The general upshot of Web.config transformations is this: you often use different settings for development/debugging, staging, and production, and Web.config transformations gives you a mechanism for doing this in a sane, formal way.  The two most common differences are database connection strings, and debugging support.  They’re so common, in fact, that your default transform files contain (initially commented-out) examples of doing this.

There are a couple of consequences and considerations to taking this approach.  First of all, it requires you to think about what, exactly, is different between your development environment and your production environment.  But that’s a good thing, right?  Once those differences are clear in your mind, you can add the appropriate transforms, test them, and call it a day.  The second consequence is that you have to use Visual Studio’s Web Deployment mechanism.

I’ve got a lot to say about the latter — so much, in fact, that you’re going to have to wait for a future blog post.  For now, the upshot is that if you aren’t using it, you should be.

As for the first consideration, I’d like to point out that you have to do this either way.  No matter how you choose to handle your Web.config files, at some point, you have to think about what the changes between your development environment and the production environment are so that you can safely update production.  Wouldn’t you rather do it once, correctly, and not have to worry about it anymore?  That’s what transformations bring to the table.

One last thing.  I know there’s someone out there in the back of the crowd with their hand up.  I know what you’re going to ask: “hasn’t Microsoft just re-invented XSLT?”  This thought occurred to me as well, and if you want to accomplish this with XSLT, you absolutely can, and bless you for doing so (I love XSLT!)  However, I reached the same conclusion that Scott Hanselman did: Microsoft’s solution is much cleaner, easier, and problem-specific.

So stop fearing the Web.config already.