
During deployment and publishing, the App_Offline.html file plays a crucial role in providing a smooth user experience. It allows users to continue accessing the application while the deployment or publishing process is underway.
The App_Offline.html file is typically placed in the root directory of the application. This is where the web server can find it and serve it to users when needed.
The file can be customized to display a custom message or design, giving you flexibility in how you present the offline experience to users.
A unique perspective: Html Application
Locked Deployment Files
Locked deployment files can't be overwritten during deployment because they're locked when the app is running. This is a common issue developers face.
Files in the deployment folder are locked, and the primary mechanism to release locked files is app_offline.htm. This file is used by Web Deploy to properly stop and start the app.
To manually use app_offline.htm, you'll need PowerShell 5 or later. The placeholder {PATH TO APP} is the path to the app.
Broaden your view: Relative File Path Html
Here's a breakdown of the PowerShell script:
- The New-Item command stops the app pool.
- The Remove-Item command starts the app pool.
- Commands between the New-Item command and the Remove-Item command are provided by the developer to deploy the app.
Files can also be unlocked by manually stopping the app pool in the IIS Manager on the server. However, don't use the app_offline.htm file when using the IIS Manager to stop and restart the app pool.
Intriguing read: Localhost 8080 Manager Html
Deploying IIS Hosted ASP.NET Core Apps
Deploying ASP.NET Core sites with IIS requires attention to detail, especially when it comes to minimizing downtime.
The traditional method of using app_offline.htm has been available since ASP.NET 2.0 / 3.5.
I recently set up deployment pipelines for some ASP.NET Core sites and initially used a no-downtime approach with rolling and blue/green deployments.
However, for internal apps that are rarely updated, a maintenance page wasn't necessary.
To deploy sites with no downtime, I initially used the following steps: iisreset /stop, copy files using Robocopy, and iisreset /start.
The first deployment worked fine, but subsequent file copies would error with "The process cannot access the file because it is being used by another process.".
Additional reading: Is Html Still Used
A hack was to add PowerShell to kill the dotnet.exe processes, but this isn't the most elegant solution.
The ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests if a file with the name app_offline.htm is detected in the root directory.
The ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file while it's present.
To deploy IIS Hosted ASP.NET Core Apps, consider the following steps:
- Remove the steps to stop/start IIS.
- Add a PowerShell step to add the app_offline.htm file.
- When the app_offline.htm file is removed, the next request starts the app.
Getting Started
You can redeploy an ASP.NET Core app multiple times, but it's frustrating for users to see an ugly error page.
To avoid this, you can create an app_offline.html file to display a nicer page while the website is under maintenance.
This file is usually placed in the root of your website, and its purpose is to serve a custom HTML page when the website is unavailable.
You can customize the app_offline.html file to display a message saying the website is under maintenance, and even include a progress bar to show the operation status.
The goal is to provide a better user experience, making the downtime more acceptable.
Publishing and Deployment
Publishing and deployment can be a challenge, especially when it comes to minimizing downtime. Files in the deployment folder are locked when the app is running, making it difficult to overwrite them during deployment.
To release locked files, you can use the app_offline.htm file, which is the primary mechanism to stop and start the app. This file can be manually used to stop and start the app, requiring PowerShell 5 or later.
You can also unlock files by manually stopping the app pool in the IIS Manager on the server. However, don't use the app_offline.htm file when using the IIS Manager to stop and restart the app pool.
Here's a step-by-step guide to using app_offline.htm for deployment:
- Publish app_offline.htm to the root directory of your app.
- The ASP.NET Core Module will attempt to gracefully shutdown the app and stop processing incoming requests.
- When the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file.
- When the app_offline.htm file is removed, the next request starts the app.
Using the app_offline.htm file can help you deploy your app with minimal downtime, making it a useful tool for any web developer.
#1 Publish
To publish an app_offline.htm file, you can use the MSDeploy task. This task allows you to execute the msdeploy.exe command, which is necessary to deploy the app_offline.htm file to the destination.
Worth a look: Difference between Htm and Html
The msdeploy.exe command that you need to execute is: msdeploy.exe -source:contentPath='C:\Data\Personal\My Repo\sayed-samples\AppOfflineDemo01\AppOfflineDemo01\app_offline-template.htm' -dest:contentPath='"Default Web Site/AppOfflineDemo/app_offline.htm"',UserName='sayedha',Password='password-here',ComputerName='computername-here',IncludeAcls='False',AuthType='NTLM' -verb:sync -enableRule:DoNotDeleteRule
You can see how this is accomplished by creating an item for both the source and destination in the PublishAppOfflineToDest target. This ensures that the app_offline-template.htm file is converted to app_offline.htm in the folder from where the publish will be processed.
The item value for FilesForPackagingFromProject will only happen during publish and not packaging, so you don't want app_offline-template.htm to be in the package. The element for MsDeploySkiprules will make sure that app_offline-template.htm itself doesn’t get published.
Here are the key parameters you need to include in the msdeploy.exe command:
Web Assets
Static assets like images, CSS files, and JavaScript files will be returned with your offline page if you have an app_offline.htm file.
This includes images, which can be tricky to handle, but are possible to include in your offline page.
You'll have to Base-64 encode the image and include it using a data URI to make it work.
CSS and JavaScript files will have to be inlined if you want your offline page to be pretty.
Consider reading: Include Jquery to Html
Updating the App
Updating the app with app_offline.htm is a clever trick. It allows you to update the progress of the deployment by updating the template of the app_offline.htm file.
You can use a PowerShell script to update the progress bar, such as the one mentioned in the article. This script uses the #progress# placeholder in the app_offline.htm template and updates it with the percentage of files copied.
The script copies files one by one, and after each file is copied, it updates the template with the new percentage. The script also includes a refresh meta tag to refresh the page once the app_offline.htm file is removed.
Here's a step-by-step guide to using the PowerShell script:
* Run the script with the following command: `Deploy-WithProgress.ps1 -Source 'C:\SomeApp\bin\Release
etcoreapp3.0\publish' -Destination '\\192.168.1.2\someApp'`
- The script will copy files one by one and update the template with the percentage of files copied
- Once all files are copied, the script will remove the app_offline.htm file and refresh the page
3. Delete
Deleting the app_offline.htm file is a crucial step after publishing your app. The msdeploy.exe command is used for this purpose, specifically the -verb:delete flag.

You can delete the app_offline.htm file from the destination web app using the following command: %msdeploy% -verb:delete -dest:contentPath="{IIS-Path}/app_offline.htm",computerName="...",username="...",password="...".
The DeleteAppOffline target is used to implement this deletion, and it's triggered automatically after the publish process because of the AfterTargets="MSDeployPublish" attribute. This target builds up the msdeploy.exe command directly, as the MSDeploy task doesn't support the delete verb.
Curious to learn more? Check out: Jmeter Non Gui Mode Command with Html Report
Updating ProgressBar
Updating the progress bar is a crucial part of the deployment process. It's quite simple, actually - we need to use our App_offline.htm as a template, which has a #progress# placeholder.
Every time we make progress in deployment, we update the template with a percentage and move it into the IIS website folder. This is where the magic happens.
You can use a simple PowerShell script to achieve this. The script gets all files from your source directory with Get-ChildItem and then moves them to the server one by one with Copy-Item, updating the App_offline.htm each time.
Expand your knowledge: Progress Bar Html
The usage is pretty straightforward: just run the Deploy-WithProgress.ps1 script with the source and destination paths as arguments. For example: Deploy-WithProgress.ps1 -Source 'C:\SomeApp\bin\Release
etcoreapp3.0\publish' -Destination '\\192.168.1.2\someApp'.
Here's a breakdown of the script's parameters:
The script uses a function called Copy-WithProgress to copy the files and update the progress bar. It gets the template URL from a global variable, and then uses Invoke-RestMethod to get the template HTML.
Featured Images: pexels.com


