Taking a .NET Core Web App Offline ... Gracefully

Have you ever had to take a Web App offline for maintenance or a software update? How did you do it ? Many of you will time it for out of business hours so users wont be impacted. But what if there happens to still be someone using it when you take it offline ?

You could end up cutting a process off halfway, and depending on your database setup there could be a series of queries partially executed !

This could be a disaster 💀

Our Savior ... Sort Of

Microsoft has given us the ability to shut down a web app gracefully by halting new requests and issuing a custom maintenance page while giving existing processes time to finish executing - we can even customize the the length of time given for the existing requests to finish before killing them.

The caveat here is that this will only work on a Windows Server where the web app is hosted using IIS - sorry Linux guys 🤷

How To Do It ?

Its actually pretty simple . Create a file called 'app_offline.htm' , and add the desired html to it. Note the file type .htm - this is not a typo, if you name it .html it will not work !! ASP.Net is quite particular about this detail !

Make sure the file is also no larger than 4 GB - for those of you crazy enough to try creating an maintenance page that size it wont work !

Fun fact

The .htm ending is a throwback to the DOS days where file types were limited to 3 characters ! They function entirely the same way as .html files but modern conventions would have you use .html because it is more semantically clear that it is a Hyper Text Markup Language file .

✨ The More You Know✨

Now you are ready to take the app offline. All we need to do it navigate to the root directory of the Web App and copy the file into it. This will take immediate effect and any new requests will get our app offline maintenance page served to them, while existing requests will now have 10 seconds ( the ASP NET default value ) before being killed. If you want to change this default then you need to change the value for shutdownTimeLimit in aspNetCore element of the web.config file. It has a minimum value of 0 and a maximum possible value of 600 seconds.

Example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess"
                  shutdownTimeLimit="60"   />
    </system.webServer>
  </location>
</configuration>

You can find my app offline file here :

Automated Deployment

For those of you who automate their deployment , you can also deploy the app_offline.htm file at the same time, the key is to add it first , deploy changes , then remove. If you leave the file there your app will never go back online!

OR

You can include the file in your project but rename it - eg x_app_offline . Then in your deployment script rename this file so that it can trigger the IIS app_offline function, then rename it after completion.

Parting Words

As you can see that was pretty easy !

Got any improvements ? Then feel free to comment below !

And if you're feeling generous you can buy me a coffee with the link below ( and yes its all for coffee, I drink a copious amount of it while writing ☕ )

Cover Image: No wifi vector created by storyset - www.freepik.com