You copy a new build of your ASP.NET Core app to IIS and the copy fails half-way: "The process cannot access the file 'MyApp.dll' because it is being used by another process." Someone on Stack Overflow says "use app_offline.htm". You drop the file in, and either nothing changes, or the site shows a blank page, or IIS's own 503 page, or it stays offline after you deleted the file.
app_offline.htm is a small feature with very little documentation. Microsoft's page on it is about 360 words and doesn't even say which status code it returns. Most of what you find on blogs and forums was written for classic ASP.NET on IIS 7, and some of it, like "the file must be at least 512 bytes", is wrong for ASP.NET Core.
So for this guide I read the source of the ASP.NET Core Module (ANCM), the IIS module that implements the feature, and checked each rule against it. Every fact below links to the line it comes from.…