June 27, 2014

Taking Your ASP.NET Site Offline with App_Offline.htm

Have you ever wanted to display a friendly maintenance page to users while updating or performing some sort of work on your website? It could be that you are rolling out an upgrade to your site or maybe you are tweaking some IIS settings or making some major changes to your database or infrastructure.

ASP.NET 2.0 introduced a simple yet powerful feature that is still available today. It is as simple as adding a single file to your website.

Basically, if you place a file with the name 'app_offline.htm' in the root of your web application directory, ASP.NET will shut-down the application, and stop processing any new incoming requests for that application.

ASP.NET will also then respond to all requests for dynamic pages in the application by sending back the content of the app_offline.htm file (for example: you might want to have a “site under construction” or “down for maintenance” message).

After the maintenance is complete just delete the App_Offline.htm file and the site will return back to normal.
A few points to consider:        
  • Prevent Friendly Http Errors - Some browsers like to be helpful 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.  To prevent this make sure the size of the app_offline.htm file is greater than 512 bytes. Add some comments to the file to make sure the byte size is greater than 512 and it will work fine.          
  • CSS, Images & JavaScript - If you want your offline page to look nice, any CSS and JavaScript will have to be embedded in the page.  In addition if you want images, you will have to use the Base-64 encode trick and include it using a data URI. 

Sample Project - I created a sample MVC 4 project on GitHub called AppOfflineify to demonstrate this feature.
To test it out copy the file App_Offline.htm in the Tools folder to the root and run the project.

Generating Maintenance Pages - If you would like to generate maintenance pages automatically there is a cool site which will help you do this.