App_Offline.htm and working around the "IE Friendly Errors" feature

I posted the slides+demos from my ASP.NET 2.0 Tips and Tricks talk online last week from the ASP.NET Connections Conference in Orlando.  One of the new features I talked about was the "App_Offline.htm" feature in ASP.NET 2.0, which provides a super convenient way to bring down an ASP.NET application while you make changes to it (for example: updating a lot of content or making big changes to the site where you want to ensure that no users are accessing the application until all changes are done).

The way app_offline.htm works is that you place this file in the root of the application.  When ASP.NET sees it, it will shut-down the app-domain for the application (and not restart it for requests) and instead send back the contents of the app_offline.htm file in response to all new dynamic requests for the application.  When you are done updating the site, just delete the file and it will come back online.

One thing I pointed out in the talk that you want to keep an eye on is a feature of IE6 called "Show Friendly Http Errors".  This can be configured in the Tools->Internet Options->Advanced tab within IE, and is on by default with IE6.  When this is on, and a server returns a non HTTP-200 status code with less than 512 bytes of content, IE will not show the returned HTML and instead substitutes its own generic status code message (which personally I don't think is super friendly <g>).

So if you use the app_offline.htm feature, you should make sure you have at least 512 bytes of content within it to make sure that your HTML (instead of IE's friendly status message) shows up to your users.  If you don't want to have a lot of text show-up on the page, one trick you can use is to just add an html client-side comment with some bogus content to push it over 512 bytes.  For example:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

    <title>Site Under Construction</title>

</head>

<body>

    <h1>Under Construction</h1>

 

    <h2>Gone to Florida for the sun...</h2>

   

<!--       

    Adding additional hidden content so that IE Friendly Errors don't prevent

    this message from displaying (note: it will show a "friendly" 404

    error if the content isn't of a certain size).

   

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2> 

    <h2>Gone to Florida for the sun...</h2>     

-->

</body>

</html>

Yes -- it looks a little weird, but works. :-)

Hope this helps,

Scott

Published Sunday, April 9, 2006 9:41 AM by ScottGu
Filed under: , ,

Comments

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, April 9, 2006 1:47 PM by Dave Reed
Very useful. Perhaps IE7 can add support for the client to disable the friendly error, say via a http header? :)

Also, it would be interesting if the offline page could actually be a dynamic page itself. It could be considered a seperate application by the runtime from the rest of the site, thus still maintaining the 'shutdown' aspect, but still giving you considerable power over how it works. Static is better than nothing though, so its still very cool :)

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, April 9, 2006 1:50 PM by Dave Reed
I guess you could accomplish that by having the static page redirect to another application, so mission accomplished!

Also, I recommend coming to Southern California for the sun. Florida is much too humid :)

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, April 9, 2006 3:53 PM by jayson knight
Can this be generated on the fly, or does the physical file have to exist for the runtime to pick it up?

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, April 9, 2006 4:23 PM by scottgu
Hi Jayson,

You could save out a file if that is what you mean. The physical file does need to be on disk, since the part of ASP.NET that looks for it happens before the application is activated (so you can't just check it within your application -- since if you did it would defeat the purpose of having the feature in the first place).

Hope this helps,

Scott

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, April 9, 2006 4:28 PM by scottgu
Hi Dave,

What I'd usually recommend for migrating application updates is to either have two machines in a web-farm, and then update first one and then the other (swapping them out as you go). Or if you have a single machine, create a new directory for the application and copy all the bits there, and then switch the application path root in IIS (that way it happens quickly and you can always roll back if something goes wrong).

For simple updates, or cases where you don't mind the app being down for a few minutes, the app_offline.htm trick works well though. It also works with $5 shared hosting accounts. :-)

Hope this helps,

Scott

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, April 9, 2006 5:02 PM by Zeeshan Hirani
that's nice info. another way to bring asp.net 2.0 application offline but not too friendly is adding a httpruntime attribute in your web.config file like.
<httpRuntime enable="false" />
doing that will cause asp.net to reject all request returning 404 error and you can specify your own for 404 error page saying the app is currently offline like

<customErrors mode="On" defaultRedirect="~/errors/GeneralError.aspx">
<error statusCode="404" redirect="~/errors/PageNotFound.aspx" />
</customErrors>

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Monday, April 10, 2006 11:27 AM by Jon Galloway
Any hints or tricks with the processModel/serverErrorMessageFile setting?

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Monday, April 10, 2006 2:37 PM by Ward Bekker
They'll fix that bug in IE7, right? ;-)

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Thursday, April 13, 2006 11:27 AM by Rob Frisch
We implemented a similar feature in our application under ASP.Net 1.1. The Web.config file contains a flag that, when set, redirects the users to a static html page (informing them the site is down for maintenance, etc.).

But we also created a little back-door so we could test the site as an end-user before letting the world back in. The back door is triggered by appending the logon URL with a particular string (...Logon.aspx?force=y).

Such a feature would be helpful in App_Offline for those of us who would like to verify an upgrade before everyone else jumps online.

# re: working around the "IE Friendly Errors" feature, how big is my file anyway?

Friday, April 14, 2006 6:14 AM by Michiel
Something I just realised: VS is my home for almost the entire day, I don't look at my application files in Explorer. Wouldn't it be nice to add to the properties view the filesize in bytes?

And another thing, it only works with htm extension, not html

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Wednesday, May 3, 2006 3:54 AM by Johan
Useful feature I must say, thanks for the tips. I have a question though -

When I did a publish from within VS.NET to an FTP site, VS.NET added the app_offline.htm file, but never removed it once it was done publishing. Is that how it's supposed to be working?

Thanks,
Johan

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Wednesday, May 3, 2006 5:56 AM by scottgu
Hi Johan,

It shouldn't add the add_offline.htm and not remove it. I think there was a bug in Beta2 of VS that did this. Are you using that version or a more recent version?

Thanks,

Scott

# re: App_Offline.htm and working around the &quot;IE Friendly Errors&quot; feature

Friday, June 2, 2006 9:22 AM by Ogre
FTP can be unreliable. I've seen the app_offline.htm file not get deleted after copying the website due to a less than pristine connection.

Is there a place in a web project where you can put a customized app_offline.htm file and have VS copy that file instead of the one it auto-generates?

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Sunday, June 4, 2006 4:03 PM by ScottGu
Hi Ogre,

Unfortunately I don't think there is a way to override the default app_offline.htm file that VS uses.  Sorry!

Scott

# re: App_Offline.htm and working around the &quot;IE Friendly Errors&quot; feature

Tuesday, June 20, 2006 11:01 PM by Rick Strahl
I think this is a lame feature. Well, no the idea is right but the execution is lame <g>. Seriously - copying a file to take an application offline?

This should be a built in function that toggles the site between online and offline mode. An AXD page that requires a login of some sort. Better yet there should be some eventing available for this so that you could check who's coming into the site and potentially allow authenticated (or whatever user you use to filter) access.

I tend to build this sort of thing into my framework where there's a check for a static flag that gets toggled. In addition there's a static message that can be customized in the Web UI that lets you vary the message. That makes a heck of a lot more sense than having to transfer a file to a live a Web Site and then remove it again.

My mechanism does mean that some code still needs to run which can be a problem in some update scenarios but if this were internally supported in ASP.NET that could probably be avoided altogether.






# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Thursday, June 22, 2006 1:13 AM by ScottGu
Thanks Rick! ;-)

The reason you can't actually use a .axd approach is that this would require code to run *in* the application in order to enable it.  This works for some scenarios -- but in cases where you want to be able to update the application's configuration and \bin assemblies you might have cases where the app won't boot/run -- in which case you the .axd approach doesn't work.  That is why we support the .htm file option - since you can use it to shut-down the app without requiring any managed code to run.

ASP.NET does provide the hooks so that you can disable applications from running - so if you wanted to implement a control panel that runs *outside* of the application and supports toggling apps you can.  

But we wanted to have a nice, built-in option that people could use without requiring their hosters to-do work to wire this up.  That is why we added the app_offline.htm option as well.

Hope this helps,

Scott

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Friday, July 28, 2006 9:40 PM by ScottGu

Hi Adam,

The behavior you are seeing it because IIS is handling the request instead of ASP.NET (since it couldn't find any default document to execute).

One way to have it map to the app_offline.htm file in these cases would be to setup an IIS custom error handler to go to this file (instead of showing the default error).

Hope this helps,

Scott

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Thursday, December 7, 2006 11:09 AM by Ram

I have a query similar to this scenario. Is there anyway that we can go for offline mode in Web Application? So the users will not be connected to the network all the time, when they get the connection they shud be able to upload the data.

# re: App_Offline.htm and working around the "IE Friendly Errors" feature

Thursday, December 21, 2006 12:24 PM by Samiq

Ping back from samiqbits.blogspot.com

Found this morning in my daily RSS reading a post in the ASP.NET Daily Articles that shows how to bring an application down for maintenance or upgrade without even getting to open IIS and stop the service.