App_Offline.htm

Update: A newer post about this can be found here.

 

I was planning to break the news about the little-heard-of app_offline.htm feature in ASP.NET 2.0, but Erik beat me to it. J

 

Basically, if you place a file with this name in the root of a web application directory, ASP.NET 2.0 will shut-down the application, unload the application domain from the server, 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).

 

This provides a convenient way to take down your application while you are making big changes or copying in lots of new page functionality (and you want to avoid the annoying problem of people hitting and activating your site in the middle of a content update).  It can also be a useful way to immediately unlock and unload a SQL Express or Access database whose .mdf or .mdb data files are residing in the /app_data directory.

 

Once you remove the app_offline.htm file, the next request into the application will cause ASP.NET to load the application and app-domain again, and life will continue along as normal.

 

Hope this helps,

 

Scott

38 Comments

  • Can we override the file name via web or machine .config ? Just curious.

  • Scott,



    Sounds quite useful, but is this for all incoming requests, or does it only cover requests from new users (those that would result in a new "session")?



    For example, I visit the site and start reading some content, or filling in a form, etc. While I'm doing that, you copy the file up to the server. I then click on a link to go to another page, or submit a form ... what would happen?



    Actually, maybe you could answer a question from a colleague of mine about if you can stop accepting sessions in ASP.Net and monitor when all existing activity has terminated.



    thanks

    Simon

  • Can you achieve the same results by renaming a file to App_Offline.htm (e.g. toggling between App_Offline.htm and App_Offline.xxx), or is the trigger when the file is created in the directory?

  • Hi Todd,



    Yep -- any file-change to app_offline.htm will trigger it. So renames will cause it as well if you want to use a toggle file.



    Thanks,



    Scott

  • Excellent. That's exactly the kind of useful, practical feature that we need. Cheers! :)

  • This is cool news. Thanks Scott

  • Sounds very cool - seems a little easy to bring down a website though - need to make sure its an admin function perhaps otherwise someone can bring your site down rather easily.

  • Oops, sorry, Scott. Didn't mean to steal your thunder. Your explanation is better than mine anyway. ;)

  • this only works with IIS or does cassini support that as well?

  • This is pretty cool...



    I like it...specially this will take care of search engines trying to sniff through your server.

  • Really nice feature.



    Does it allow any IP range filter eg: do not display "Under Construction" webpage for internal developers? Generally, developers need to verify major upgrade, before it goes to live world.



  • another great feature for 2.0. cant wait, scott you and your team are doing a fantastic job. roll on the release day.

  • This is a good feature to have. However, it seems static. Why not have an object or something registered to IIS that will return true or false.

    For example, application might be ready to become offline after serving existing sessions. And would not be willing to take new sessions. I do not see why an e-commerce application in the middle of its operation would want to go offline, affecting their business. Approach would have to be so that new sessions are not created.



    But it is a first step. And seeing that web server is taking take care of it, is relieving. One less programming headache.



    -Prakash

  • What if (I think) visual studio is creating the by it self. I have done some testing with the preview release of july and wefly247, and everytime I started the studio, the App_Offline.htm was created. Haven't seen it in the RC so maybe it was a bug in de preview release.

  • This is one of those really cool simple things that are extremly useful. But they often fall in the shadow of all the new major features that steal the spotlight, and therefore don't get as much documentation. So you just fell happy when you by accident stumble onto one.

    But your team have probably implemented plenty more like this one, so will there be a white-paper of all the other ones? I want to know about every little change and new feature. :)

  • Hey Scott - Welcome back from you holiday. I truly hope you could forget about ASP.NET and IIS for at least a few days while away ;-)

  • Thats a really nifty and useful feature..

    cheers

  • Hi Ruud,



    Yep -- in the Betas there was a bug that caused the file to occasionally get generated and not cleaned up when new databases are provisioned. Hopefully it no longer exists (I haven't run into it for a few months)!



    Thanks,



    Scott

  • Hi Mital,



    It doesn't allow IP range filtering. One challange with IP range filtering is that it is easy to defeat and bypass. Anyone can send a packet saying it is from another IP address -- the response from the web-server wouldn't reach them (if the IP address wasn't real), but it would still activate the app and cause things to run.



    Hope this helps,



    Scott

  • Hi Simon,



    We actually have perf counters that track session creation and the number of active sessions. So if you wanted to count these you can using this infrastructure. The app_offline.htm trick is designed to provide a pretty easy and bare-bones way to take down your site and app-domain for upgrading bits. If you wanted to provide a more graceful approach, you could ceretainly implement one by rejecting sessions and slowly weaning people off the server before you then dropped a app_offline.htm file to finally shut it down.



    Hope this helps,



    Scott

  • Hi Tim,



    App_Offline.htm will also take down apps with Cassini, although honestly it probably doesn't make sense using it there. It is easier to just right click and stop Cassini vs. adding the file.



    Hope this helps,



    Scott

  • Great - one of the problems I have with classic ASP is that I would actually have to toggle the IIS service to unlock files before I could do a site upgrade.



    Mike.

  • As a prank for your fellow developers, create the file but don't put any text in it. This causes a 'resource not found' error! - but doesn't mention anything about the app_offline.htm file! You can sit back and laugh while your peers struggle for hours trying to figure out why the site doesn't work anymore!

  • Scott,

    How come every time I install any security updates and reboot the server the App_Offline.htm appears so my site never comes back online automatically. If it is a feature that is built in can i disable the option for it to automatically be created after every security update and reboot

  • Hi Scanner,

    The app_offline.htm file is only ever generated by VS (ASP.NET and Windows never generate it). It shouldn't be happening when installing security updates. Can you provide more details on when/how this is occuring?

    thanks,

    Scott

  • Is there a way to get around this file permanantly? I'm testing an app that is using MS Access 2003 as a back-end and this app_offline.htm file suddenly shows up because the .ldb file on the Access database didn't close because I made an error in my code while saving data and the connection stayed open. I had never seen this file before and when I looked for it, it was not in the root directory as Firefox and IE said it was. Any idea as to how I can get around this file so I can test. I'm using VS 2005, ASP.Net 2.0 on a W2003 Enterprise server coding in VB.Net. I'm also connecting to PayPal since this is a fund raising site.

    Many thanks,

    Rich

  • Hi Rich,

    From your message above, it doesn't sound like you are seeing the app_offline.htm file. Rather, it sounds like you are having runtime errors within your application - which is triggering the default ASP.NET error message to display.

    These pages provide more details on how to handle custom errors within ASP.NET:

    http://www.aspnetresources.com/articles/CustomErrorPages.aspx

    http://www.c-sharpcorner.com/vbnet/vbarticles/VBASPExHSSK.asp

    http://www.aspnetpro.com/NewsletterArticle/2003/07/asp200307mb_l/asp200307mb_l.asp

    Hope this helps,

    Scott

  • Hi Haakon,

    That is pretty odd. The only reason I could think that there would be this problem is if the database keeps getting re-generated on each attempt.

    Thanks,

    Scott

  • Hi,

    I need some help. I uploaded App_Offline.htm and the site looks stop working. But my CbfCASPNETDB_log.LDF file is locked. I am not able to delete or rename it. Deletion is necessary because CbfCASPNETDB.MDF file was modified and uploaded.
    Did someone have same experience?

    Peter

  • Hi Peter,

    I think the problem you are running into is that your SQL Express database is holding the file open. Unfortunately you'll need to stop/restart the SQL Express process in order to update this file.

    Hope this helps,

    Scott

  • TIP: The app_offline.htm file must be greater than 512 bytes if you want to MS Ineternet Explorer show this "friendly" error message and not and a 404 Error Message default page.

  • If a hacker gets to place the file on your web root somehow you'll be wondering what happened for quite a while.

  • Is there a way of getting VS to use a custom made App_Offline.htm file instead of the default one? It would be nice if we could still let VS take care of placing and deleting the file during deploy/publish and still let use choose the message/design displayed to users.

    Cheers

  • Hi Rich,

    Unfortunately the app_offline.htm file that VS creates doesn't support customization I'm afraid.

    Sorry about that. :-(

    Scott

  • Hi Paper,

    If a hacker is allowed to download files onto the root of your web you have pretty serious security problems (since they can modify all of your configuration files and deploy code). So app_offline.htm would be the least of your worries!

    Hope this helps,

    Scott

  • Hi, I have tried this feature. But find it a little awkward. If the user is currently navigating inside my site, app_offline.htm will be shown. But if the new user just visit the page (afeter app_offline.htm) has been copied, the user received 404 error page, bot the content of app_offline.htm. How to make it always display the app_offline.htm conent?

  • Is there plans in the future to make the auto-created app_offline.htm content custimized?
    As it stands now, publishing my webapps doesn't take very long, but I would still prefer users to not see the current message inside app_offline.htm.
    I see it as allowing a stacktrace to be visible to the end user the way the message is currently setup.

  • Thanks Plater, I was searching my machine in hopes of finding the file *somewhere*. This is about the only place I didn't look.

Comments have been disabled for this content.