HttpPlatformHandler has been replaced by ASP.NET Core Module

Background

In beta8 and rc1 ASP.NET Core Applications hosted in IIS employed a native IIS module, HttpPlatformHandler v1.2, to forward requests to the ASP.NET Core Kestrel Server.

What's Changing?

Going forward we're moving to the ASP.NET Core Module, a new native IIS module, to forward requests to Kestrel.

Why?

We have added Asp.Net specific features, where HttpPlatformHandler was a generic reverse forwarder.

What's new?

AspNetCoreModule v0.8 is based on a fork of HttpPlatformHandler 1.2. Most viable is the rename of the module and associated config entries to avoid conflicts with the existing module. We've also fixed several bugs and added the following features:

Support for app_offline.htm
Forward client certificates
Unlocked config section
Support for sub applications in IIS
Download the new ASP.NET Core Module v0.8
x86 Installer
x64 Installer
What won't work yet?

There is no tooling support in Visual Studio yet (as of 3/25). In the meantime you'll need to use dotnet publish from the command line and run the application with full IIS. dotnet-publish-iis is also in the process of being updated so some manual web.config manipulation may be necessary.

The module will be deployed to Azure Web Sites in the coming weeks.

Changes to your app

New package dependency

There is a new package Microsoft.AspNetCore.Server.IISIntegration that contains the extension methods to work with ASP.NET Core Module. This replaces Microsoft.AspNetCore.IISPlatformHandler. Note that as part of https://github.com/aspnet/IISIntegration/issues/122 we have removed the Microsoft.AspNetCore.IISPlatformHandler package from our repository and we will no longer be building new versions of it. However, we will retain the old package on our feed until the module is deployed to Azure Web Sites.

Changes to `Startup.cs`

public class Startup
{
    public void Configure(IApplicationBuilder app, ILoggerFactory loggerfactory)
    {
          ...
          // Remove call to app.UseIISPlatformHandler(); This is handled by UseIIS in Main.
          // Remove call to app.UseForwardedHeaders(); This is handled by UseIIS in Main.
          ...
    }

    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseDefaultConfiguration(args)
            .UseServer("Microsoft.AspNetCore.Server.Kestrel")
            // Replaces call to UseIISPlatformHandlerUrl()
            .UseIISIntegration()
            .UseStartup<Startup>()
            .Build();

        host.Run();
    }
}

Register the new `AspNetCoreModule` in your `web.config`

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="..\MySite.exe" arguments="" stdoutLogEnabled="false" stdoutLogFile="..\logs\stdout" />
  </system.webServer>
</configuration>

See https://github.com/aspnet/IISIntegration/issues/105 for discussion.

aspnet / Announcements