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 application running Kestrel. Since 2.0 we have been hard at work to bring to two major improvements to ANCM: version agility and performance. In the 2.1.0-preview1 release, we have chosen not to update the global module to avoid impacting any existing 1.x/2.0 applications. This blog post details the changes in ANCM and how you can try 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 Server Hosting Bundle. 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 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. Instead of serving as a reverse-proxy, ANCM can now boot the CoreCLR and host your application inside the IIS worker process. Our preliminary performance tests have shown that this model delivers 4.4x the request throughput compared to hosting your dotnet application out-of-process and proxying over the requests.
How do I try it?
If you have already installed the 2.1.0-preview1 ServerHosting 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.
Modify your project
Let’s go ahead and modify our project by setting a project property to indicate that we want to 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 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 WebSDK 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
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 a be 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 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 observed in this simple app where you’ll observe either Hello World from dotnet or Hello World from w3wp based on your hosting model.