Using App_Offline.htm to take you ASP.NET Web Application Offline

Ever wanted to stop visitors from seeing your site whilst you performed maintenance to it? Maybe you’re having some database or hardware issues and you want to stop any new requests from hammering your server. Well, with ASP.NET 2.0 and later it’s as easy as adding a single file to your website.

All you have to do is create a file called app_offline.htm in the root of the website. Bam! Your site is down for maintenance. This provides a super convenient way to take your website offline while you make changes to it. You can put arbitrary HTML in the file, so your offline page can be as pretty (or otherwise) as you like – with a caveat discussed later.

When ASP.NET sees the app_offline.htm, it will shut down the AppDomain for the application and instead return the app_offline.htm file in response to all new HTTP requests. When you’ve finished deploying your new version, fixing the problem or replacing the hardware, just delete the file and the site will come back online.

Images, CSS and JavaScript

When you have an app_offline.htm file it will be returned for EVERY request. That includes static assets like images, CSS files and JavaScript files. So, if you want you offline page to be pretty, CSS and JavaScript will have to be inlined. Images are a bit more tricky but are possible. You’ll have to Base-64 encode the image and include it using a data URI.

Avoiding friendly HTTP errors

Some browsers like to be helpful to their users and display their own custom error pages for HTTP errors like 404 and 500. These errors are triggered when the page returned by the server is very short, typically less than 512 bytes. If you just put the words ‘Application Offline’ in your app_offline.htm file then the browser will override it and the user will just think your site is broken. So, always make sure you page is at least 512 bytes by adding filler tags or hidden text.

And finally…

You could automate the addition and removal of the file as part of your automated deployment script. You do have an automated deployment script, right? No? Remember: automate all of the things!