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,
- 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.
- You need complex reverse proxy rules to be defined on IIS side, so that traffic can be properly forwarded to the application server.
- 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),
- 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.
- 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. - 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.
- 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 likeUseIISIntegration
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.
References
- PHP on IIS announcement
- wfastCGI initial commit
- iisnode initial commit
- HttpPlatformHandler initial announcement
- HttpPlaformHandler v2 by LeXtudio
- Configuration Reference by Microsoft
- Java Example by Microsoft
- Python Example by Microsoft
- Python/Flask Example by me
- Python/Django Example by me
- Python/FastAPI Example by me
- Node.js Example by me
- Next.js Example by me
- Nuxt 3 Example by me
- Nest Example by me
- Ruby Example by Scott Hanselman
- Go Example by me