The Rough History of IIS HttpPlatformHandler

Due to various misinformation around this IIS out-of-band component, I think it’s worth the while to write about its history so you know what others are talking about and how some of them made mistakes.

The Start of Windows Azure

When Microsoft entered the cloud computing market, it was a big challenge to support non-Microsoft technologies on Windows Server so that this platform can expand its reach to a broader audience.

That effort happened to align with a few important changes on IIS itself, where FastCGI support was added so that PHP applications can be hosted on IIS via that interface in 2006. Zend Technologies Inc. and PHP community were willing to help on PHP for Windows while Microsoft provided support.

While this was a big step forward, soon people discovered the difficulty to extend the excitement to other programming languages. For example, wfastcgi was developed by Microsoft Python team in 2012 to enable FastCGI support for Python. iisnode was developed by Tomasz Janczuk initially in 2012 to enable FastCGI support for Node.js, and later handed over to Microsoft Azure team.

But the FastCGI approach isn’t sustainable, and the story for Ruby, Go, Java, and many more was undone.

The Reverse Proxy Disadvantages

Clearly an alternative is to run those non Microsoft technologies on their own application servers, and then IIS/ARR can sit in front as reverse proxy. The popularity of nginx proved that approach for long, but it comes with its own disadvantages,

  1. The application server is usually running on its own, so you should not expect it to work in your familiar application pool pattern that from time to time the processes are recycled.
  2. You need complex reverse proxy rules to be defined on IIS side, so that traffic can be properly forwarded to the application server.
  3. You need to predetermine the port for your application server. It’s not a big deal for your own server which just hosts one or two web apps this way, but what about an enterprise server with hundreds of web apps? It’s not easy to manage the port numbers.

The Magical HttpPlatformHandler

The experience of building FastCGI and ARR gave Microsoft developers enough experience on both sides of the coin, so they came back with a very smart idea and implemented a new component called HttpPlatformHandler.

In general it works as a reverse proxy between IIS and your application server, but it hooks up the reverse proxy rules itself and also determines which port to use. Then all you need is to specify which process should be called with what arguments to launch the application server process. After such simple configuration, this module spins out the application server on demand and recycle it whenever needed. The port number to use is either passed as one of the arguments or via an environment variable.

The simplicity of this design makes the module a great success, as you no longer need any specific FastCGI bits or ISAPI modules. All you need is just the very simple HttpPlatformHandler configuration snippet and it works for almost all modern web stacks.

Initially this was used by Microsoft Azure Websites to host Java web apps, and later released as a separate download for IIS in 2015.

The Mist of ASP.NET Core Module

Naturally when Microsoft designed ASP.NET Core, HttpPlatformHandler was chosen to be the integration point. However, the more features ported from ASP.NET 4.x, the more gaps identified that HttpPlatformHandler cannot fulfill all the needs.

ASP.NET 4.x has so tight an integration mode with IIS (if you read about the integrated pipeline), that a dedicated IIS module must be developed upon HttpPlatformHandler to support most of the features and enable a smooth migration path. Of course, this new module is now known as ASP.NET Core module for IIS.

Almost all misinformation today can be traced back to this announcement made by the ASP.NET Core team on GitHub. Readers without knowing the entire background or reading the announcement carefully can easily assume that they shouldn’t use HttpPlatformHandler, but switch to ASP.NET Core module. But you can see how wrong that assumption is. Author of the original announcement later clarified that the announcement was not meant to discourage HttpPlatformHandler usage, but to inform the community about the new module in this comment,

“HttpPlatformHandler was only replaced by ANCM for ASP.NET Core apps, it is still maintained for other uses. You’re welcome to use ANCM for other applications but we don’t document or support that scenario, you would need to reverse engineer it from here.”

There are a few noticeable things we can observe from ASP.NET Core module source code though (to help you better understand its sibling HttpPlatformHandler),

  1. The module keeps the functionality of HttpPlatformHandler, so that it can host Kestrel processes in out-of-process mode. But you won’t find the documentation from Microsoft on the port number environment variable, as ASP.NET Core/Kestrel has that knowledge built in.
  2. Except the way to shut down the application server process via Control+C, it also adds a new way to shut down the process via a special URL (/iisintegration). This is a feature that HttpPlatformHandler does not have.
  3. The module adds a lot of features to support ASP.NET Core in-process mode, which is not available in HttpPlatformHandler. This is why the module is not a replacement for HttpPlatformHandler, and it has a larger memory footprint.
  4. It changed some internals such as the 8kb internal buffer. Those changes were not backported to HttpPlatformHandler.

If you are interested in learning more about ASP.NET Core module, you might review its code base on GitHub under dotnet/aspnetcore repository. Methods like UseIISIntegration orUseIIS are also important.

So, HttpPlatformHandler is still fully supported by Microsoft, and its latest release v1.2 from 2015 supports all latest Windows releases. If you are hosting Python/Ruby/Go/Java/Node.js applications on IIS, give it a try and feel how simple it is to set up everything around it.

HttpPlatformHandler v2.0 by LeXtudio Inc.

LeXtudio Inc. just released a new product, HttpPlatformHandler v2, which is a a drop-in replacement for Microsoft HttpPlatformHandler v1.2 but offer more features and bugfixes. You are welcome to give it a try.

This post talks about why we build it and how we build it. You can find more details in this post.

Side Notes

HttpPlatformHandler on Azure App Service

HttpPlatformHandler is also enabled on Azure App Service (Windows) by default, so if you have tested your web apps on your own IIS server, you can confidently host them on Azure App Service without many changes on configuration.

HttpPlatformHandler on IIS Express

This is for the first time covered by the new open source HttpPlatformHandler v2.0 from LeXtudio.

I also created the necessary PowerShell scripts to help enable Microsoft HttpPlatformHandler v1.2 on IIS Express if you want to give it a try. You can find them on my GitHub repository.


© Lex Li. All rights reserved. The code included is licensed under CC BY 4.0 unless otherwise noted.

© - Lex Li. All rights reserved.

Using the Chirpy theme for Jekyll.

Last updated on April 13, 2024