What are suggested alternatives to the often broken app_offline.htm hack?

Question

In quite some scenario's, placing app_offline.htm in the root is just right: you do some updates, the message appears while updating, and that's that. The idea is, as Microsoft puts it, that before anything is called, IIS first checks if app_offline.htm is there and if so, it cancels everything and displays it.

So for so good, but in many situations it doesn't work:

• When you have a compile error in an ASPX page and a user links directly to it
• When you have conflicting assemblies
• When you have a parsing error in your web.config
• In the midst of removing / uploading the entire site.
• A direct link to a static HTML page is still displayed as such
• File-not-founds, access-denieds are thrown before the message is shown

Possibly more scenario's exist that fail. My point is: for any serious updating work, app_offline.htm is not suitable. I sometimes create a redirect in IIS, to another site, but another site may not always be available and it can confuse users.

Ideally, I'd want to keep the current location in the url location bar of the end-user, show the message, and have the page auto-refresh each minute to see whether the site is back, so that the user continues where he left of when the site comes back. While technically easy enough with a static page, it will fail for the above mentioned reasons the minute an error is thrown.

Answer 1

No one else mentioned web.config and recompilation, so here it is. I've encountered this issue. I disagree with the person who said it's "not intended for prod use": VS 2010 uses app_offline when deploying so it's baked into the code.

The workaround (credit goes to Kurt Schindler, blog post here).

1. copy up app_offline.htm to your site
2. make a web.config that looks like this (see below numbered block)
3. copy that web.config up to your remote directory
4. copy all of the site files except your true web.config up to the remote dir
5. copy the real web.config up to the remote dir (which should kick off a recompile)

web.config:

<?xml version="1.0" encoding="utf-8" ?> 
<configuration>
  <system.web>
    <httpRuntime waitChangeNotification="300"
       maxWaitChangeNotification="300"/>
  </system.web>
  <system.webServer>
     <modules runAllManagedModulesForAllRequests="true"  />
  </system.webServer> 
</configuration>

The consequence of this is that you can't use the VS 2010 app deployment directly if you care about end users not seeing YSOD during a deploy. So you'll need to use Nant or some other deploy tool to do this.

Answer 2

One way I've seen this handled on a number of very highly traffic'ed sites is to have multiple folders in the inetpub directory. Something like:

inetpub
     \ site2011-02-03 
     \ site2011-03-14

Where the "site2011-02-03" is the existing site and "site2011-03-14" is the one pushed today. Once the push to the new folder is complete you change the IIS site to point to the new directory. In case of failure, you change IIS to the older version.

Quite frankly, I've never encountered the errors you speak of when using app_offline.htm. It has always properly functioned to take the site down; even for direct links to pages. I'd guess that you might have something else going on here. and I've used IIS 7 and 7.5 (2008 R2) with it.

update
Just looked in our config. We have app_offline.htm mapped as the top default document on our servers. That might be a mitigating factor.

Answer 3

I like the idea of using an "offline" web app while your actual web app is offline. You would set up a symlink on your web directory to point to the appropriate application.

Your setup might look like the following:

Web_Dir (this is the directory that IIS serves www.yourdomain.com from)
WebApps

• ActualWebApp
• OfflineWebApp

Scenario: Your app is online
Web_Dir -> ActualWebApp (Web_Dir is linked to ActualWebApp)

Scenario: Your app is offline
Web_Dir -> OfflineWebApp (Web_Dir is linked to OfflineWebApp)

---

Essentially, you end up with two different web applications: an actual web app and an "offline" web app. This gives you the flexibility of redirecting users to another site but maintains the appearance of being your domain--because it is!

The actual web app is the real web application. This is the one you're making changes to and the one that has your actual content.

The "offline" web app has very little content. Maybe it only contains the static page you mentioned in your question. Maybe it has some routing to handle any page request, display an offline message, and reload every minute.

Your IIS web directory is actually a link to one of these two web apps. Normally, it will be linked to your actual web app. When you are ready to begin (re)deploying your web app, you change your web directory to point instead to the "offline" app. After the deploy is complete, you change the link back so that it points to the real web app once again.