Locked Assemblies and App_Offline Files
When a Razor Pages site is running on the web server, the application's .dll file is loaded by the IIS process along with the .dll file that holds the precompiled page content and are locked. If you use FTP to upload the published content, you will need to stop the process in order release the .dll files so that they can be overwritten. This is handled automatically by the traditional ASP.NET framework but needs to be done manually with ASP.NET Core applications.
There are a number of ways to accomplish this. If you have access to the web server, you can stop the site's application pool and then restart it once the new files have been uploaded. However, this won't provide the visitor with a particularly good experience. A cleaner alternative is to use an App_Offline.htm file. When placed in the root folder of the site (i.e. the location returned by the IHostingEnvironment.ContentRootPath property), the presence of a file name App_Offline.htm results in any further request to the application being served with the content of the file. This file is most commonly used to display a message explaining the the site is currently undergoing maintenance.
The name of the file is important, although case-insensitive. The easiest way to switch this feature on and off is to use an FTP client to rename the file to something else when the site should be live, and then alter it back when the site should be offline.
imagePath full path to image file
bytes File imagePath
base64Image Convert bytes bytes Length
Including Static Content in the Root Folder
Non-supported framework versions
One of the USPs offered by .NET Core is the fact that you do not have to rely on your hosting company installing the latest version of the framework on the hosting server in order to take advantage of it. This means that you can target any version of the framework you like. So when a newer version is released that contains features or bug fixes that you need, you can simply target it. However, if you deploy an application that targets a version that isn't supported by the hosting server, you will get errors along the lines of:
Error: An assembly specified in the application dependencies manifest (xxx.deps.json) was not found: package: 'Microsoft.ApplicationInsights.AspNetCore', version: 'xxx' ... This assembly was expected to be in the local runtime store as the application was published using the following target manifest files: ...
By default, the publish operation employs a process known as Runtime Store Trimming, whereby dependencies that form part of the .NET Core runtime are not included in the published output. The error therefore arises because items specified in the MyApp.deps.json file are not present on the hosting server.
There are four possible solutions to this problem:
- Install the relevant version of the SDK on the server (which also installs the runtime store package)
- Install just the Runtime Store Package on the target server (you can get that by locating the correct version of .NET Core here)
- Amend the .csproj file to include the following entry which disables runtime store trimming:
<PropertyGroup> <PublishWithAspNetCoreTargetManifest>false</PublishWithAspNetCoreTargetManifest> </PropertyGroup>
- Use the following (undocumented) property option when publishing via the CLI:
dotnet publish -o c:\publish\myApp -c release /property:PublishWithAspNetCoreTargetManifest=false
The third and fourth options will result in the entire contents of the runtime store being included with the published output - about 200 files and folders at around 40MB. All of this will need to be included in the files uploaded to the hosting server.
The items covered here are just some of the things that can catch the unwary out when publishing a Razor Pages application to IIS using the Folder publishing option. The article on www.learnrazorpages.com goes into more detail about the actual process, and will be updated as more commonly encountered Gotchas come to light.