Continuous Integration Tip #2 – Using App_offline.htm in Your Build

deploying in an automated fashion using continuous integration doesn’t happen instantly, and depending on the size of your application, your continuous integration deployment can get caught in a state of unknown/in-between if a user visits your application half way through deployment. this can be far from optimal, but asp.net has a trick up it’s sleave in the form of the app_offline.htm file.

this is the second post in a series on continuous integration tips & tricks in follow up to a post i made about setting up continuous integration automated deployment with web deployment projects & team city .

while there has been quite a bit of broadcast advertisement of the app_offline file over the years, whenever i bring it up with developers i usually get a blank stare in reply.

basically the gist of this is simple: if you place a file named app_offline.htm in the root of your application, all requests to asp.net pages or web services, is met by the contents of this file.

because of this really cool feature that asp.net has on offer, we can use it to our advantage in our automated build. what we need to do is copy a file into the root of our application before we copy the site.

the example build file

in all my examples, i've been using microsoft web deployment projects and teamcity . this solution uses msbuild for it’s automation, therefore i’m going to show you an example msbuild script that you can add to your web deployment project. you'll have to alter these for your build provider of choice if you use a different one (nant etc).

create an html file called deploymentinprogress.htm in the root of your application (it can be anywhere, as long as you update your build script to reflect the new path) and in it put some html that mentions that the app is being deployed. i suggest that if you use css include all the styles in the header instead of linking to it, and if you use any images in the page they are hosted on another domain/location (because you’ll be deploying your site and want to make sure the image file you calls exists and hasn’t been deleted by your deployment process).

add the following to bottom of your web deployment project file.

<target name="afterbuild">
    <propertygroup>
    <!-- this is where i want to copy my deployment to-->
        <deploymentdestination>c:\myiisroot\</deploymentdestination>
    </propertygroup>
    <itemgroup>
        <filestocopy include="$(outputpath)\**\*.*" />
    </itemgroup>

    <!-- copy the app offline file-->
    <copy sourcefiles="$(outputpath)deploymentinprogress.htm" 
                destinationfiles="$(deploymentdestination)app_offline.htm" />
    
    <!-- copy the deployment files-->
    <copy sourcefiles="@(filestocopy)" 
                destinationfiles="@(filestocopy->'$(deploymentdestination)%(recursivedir)%(filename)%(extension)')" />

    <!-- delete the app offline file-->
    <delete files="$(deploymentdestination)app_offline.htm" />
</target>

this will copy your file (in the process renaming it to app_offline.htm ), copy your project files, and then delete the app_offline.htm file so that your application can start.

this can  be further integrated with the ftp upload i mentioned in the previous post to give a remote deployment option.