Taking an ASP.NET 2.0 Application Offline

CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

By John Peterson

Normally the last thing you want is for your web application to be offline.
In the 24/7/365 world of the Internet, users expect your site to be available
whenever they want to use it. Many of the improvements in the latest versions of
ASP.NET and IIS have helped make this goal a reality, and these days it’s not
uncommon for sites to achieve upwards of 99.9% uptime. That being said, there are
times when it’s either desirable or necessary to take an ASP.NET application offline.

Just because you take an application offline doesn’t necessarily mean your site is down.
You might be dealing with an application that represents one small part of your site
or maybe you’ve implemented a web farm and requests can be handled by other servers.
This article discusses a technique to simplify taking a single application offline. How taking
that application down affects your site depends on the site’s specific architecture and configuration.

Why Take an Application Offline?

There are two main reasons that you would normally want to take your application offline.

  • To make major changes to the application.
  • To gain access to resources that cannot be accessed while in use.

If you’re going to make major changes to your application then it’s likely that you don’t want users
using it in the process. For example, if you’re changing the structure of one of your database tables
and the associated code, having users access it while those changes are taking place will most likely
result in problems.

Speaking of the database, that brings up the second reason you might want to take your application offline.
When an application is actively accessing an Access or SQL Server Express database it locks the files so that they
aren’t modified by other processes. The problem is that if you need to make changes to those files or replace them,
you’re not able to until the application releases the lock, and it won’t release the lock as long as users are accessing
the database.

In both of these scenarios it’s probably better to take the application offline for a few minutes
then to try and make the changes with the application online and then be stuck trying to clean up any
problems you run into.

The app_offline.htm File

So now that we’ve decided we want to take an application offline, how do we do it?
If we’ve got access to the server we could stop the web site via the IIS management console, but
in most shared hosting scenarios you don’t have that kind of access to the server. The other shortcoming
of that approach is that many developers publish via FrontPage Server Extensions or WebDAV, both of which need
the web site to be running in order to make changes.

Enter the app_offline.htm file. The app_offline.htm file is a special file that ASP.NET 2.0 watches for in the root
of an application. If the file exists, then ASP.NET shuts down the application and sends the contents of the file back
to the user’s browser for any new requests to dynamic pages in the application. This means that users are basically
locked out of the application and you’re free to make any changes that need to be made before removing
the file and letting them back in.

A Sample app_offline.htm File

For an example of an app_offline.htm file you don’t have to look any further then the files that
Microsoft ships with Visual Web Developer Express.


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >

    <title>Application Offline</title>

div {



    This application is currently offline. To enable the application, remove the
    app_offline.htm file from the application root directory.

When viewed from a browser it looks something like this:

If you look at the address bar in the screen shot above, you’ll notice that I didn’t actually
request app_offline.htm. I requested the application’s default.aspx page
but was sent the contents of the app_offline.htm file instead.

You’re free to have the file say whatever you want, but you do want to make sure that it’s not too short.
Many people have run across an error where IE will display one of its "friendly HTTP error messages"

if the file is smaller then 512 bytes.

For more information on this issue see Scott Guthrie’s blog entry:
app_offline.htm and working around the "IE Friendly Errors" feature.

One last thing to note is that, while all requests to .NET files will be redirected to app_offline.htm,
static content and classic ASP scripts will continue to be served and run as usual. Just a heads up for those
of you running applications that contains a mix of classic ASP and ASP.NET.


While the goal for most sites is to stay up as much as possible, there are times when you need to
take an application offline. The new ASP.NET app_offline.htm file provides an extremely
convenient way to take an application down when you need to without shutting down the web server.
Not only is it simple for a developer to use, it also provides an easy way to let site visitors know what’s
going on and helps prevent them from getting errors when the application restarts.

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read