ASP.NET Core 2.1.0-preview1: Improvements to IIS hosting

The ASP.NET Core Module (ANCM) is a global IIS module that has been responsible for proxying requests over from IIS to your backend ASP.NET Core application running Kestrel. Since 2.0 we have been hard at work to bring to two major improvements to ANCM: version agility and performance.

Note, that in the 2.1.0-preview1 release, we have chosen not to update the global module by default, to avoid impacting any existing 1.x/2.0 applications at this early stage. This post details the changes in ANCM and how you can opt-in to trying out these changes today.

Version agility

It has been hard to iterate on ANCM since we’ve had to ensure forward and backward compatibility between every version of ASP.NET Core and ANCM that has shipped thus far. To mitigate this problem going forward, we’ve refactored our code into two separate components: the ASP.NET Core Shim (shim), and the ASP.NET Core Request Handler (request handler). The shim (aspnetcore.dll), as the name suggests, is a lightweight shim, where as the request handler (aspnetcorerh.dll) does all the request processing.Going forward, the shim will ship globally and will continue to be installed via the Windows Server Hosting installer. The request handler will now ship via a NuGet package- Microsoft.AspNetCore.Server.IIS, which you can directly reference in your application or consume via the ASP.NET Core metapackage or shared runtime. As a consequence, two different ASP.NET Core applications running on the same server can use a different version of the request handler.

Performance

In addition to the packaging changes, ANCM also adds supports for an in-process hosting model for ASP.NET Core applications running on .NET Core. Instead of serving as a reverse-proxy, ANCM can now boot the CoreCLR and host your application inside the IIS worker process (w3wp.exe). Our preliminary performance tests have shown that this model delivers 4.4x the request throughput compared to hosting your .NET Core application out-of-process and proxying over the requests.

How do I try it?

If you have already installed the 2.1.0-preview1 Windows Server Hosting bundle, you can install the latest ANCM by running this script.

Alternatively, you can deploy an Azure VM which is already setup with the latest ANCM by clicking the Deploy to Azure button below.

Create a new project or update your existing project

Now that we have an environment to publish to, let’s create a new application that targets 2.1.0-preview1 of ASP.NET Core.

Alternatively, you can upgrade an existing project by following the instructions on this post.

Modify your project

Let’s go ahead and modify our project by setting a project property to indicate that we want our published application to be run inprocess.

Add this to your csproj file.

Publish your project

Create a new publish profile and select the Azure VM that you just created. If you’re using Visual Studio, you can easily publish to the Azure VM you just created. In the Solution Explorer, right-click the project and select Publish to open the Publish wizard where you can choose to publish to an Azure VM that you just created.

You may need to allow WebDeploy to publish to a server using an untrusted certificate. This can be accomplished by adding the following attribute to your publish profile (.pubxml file)

If you’re running elsewhere, go ahead and publish your app to a Folder and copy over your artifacts, or publish directly via WebDeploy.

web.config

As part of the publish process, the Web SDK will read the AspNetCoreModuleHostingModel property and transform your web.config to look something like this (observe the new hostingModel attribute):

Debugging

To view the Cloud Explorer, select View > Cloud Explorer on the menu bar

If you’ve been following along using an Azure VM, you can enable remote debugging on your Azure VM via the cloud explorer. In the Actions tab associated with your VM, you should be able to Enable Debugging.

Once you’ve enabled remote debugging, you should be able to attach directly to the w3wp.exe process. If you don’t see the process listed, you may need to send a request to your server to force IIS to start the worker process.

If you’ve been following along locally, you can use Visual Studio to attach directly to your IIS worker process and debug your application code running in the IIS worker process as shown below. (You may be prompted to restart Visual Studio as an Administrator for this).

We don’t yet have an experience for debugging with IIS Express. At the moment, you will have to publish to IIS and then attach a debugger.

Switching between in-process and out-of-process

Switching hosting models can be a deployment-time decision. To change between hosting models, all you have to do is change the hostingModel attribute in your web.config from inprocess to outofprocess.

It can be easily seen in this simple app where you’ll observe either Hello World from dotnet or Hello World from w3wp based on your hosting model.