Why does HttpPlatformHandler/ANCMv2 for IIS only assign a port dynamically and how to use ARR/URL Rewrite given this

Question

Why does HttpPlatformHandler/ANCMv2 for IIS only assign a port dynamically and how to use ARR/URL Rewrite given this

Mark Zhukovsky 46

This question is 2 parts - would really appreciate any insight.

What are the architectural reasons behind the port assignment via HttpPlatformHandler to another process, let's say a Python web app, only being dynamic? i.e. it is not possible to specify, explicitly, a port that should be used to run the process, and instead it is only determined once a request comes through and the module finds an open port dynamically to pass the socket connection onto - https://learn.microsoft.com/en-us/iis/extensions/httpplatformhandler/httpplatformhandler-configuration-reference - so only the env variable HTTP_PLATFORM_PORT (or ASPNETCORE_PORT if using ANCMv2) will indicate this once the process is started.
Given this fact, please confirm then that it is not possible to define appropriate rules using ARR/URL Rewrite modules to proxy some requests directly to the web server being run by the owned process, since those variables are not accessible - it may seem strange to even ask this but due to some limitations of a 3rd party web app framework I am looking for a workaround of sorts.

TengFeiXie-MSFT 346 Reputation points

2023-08-15T09:05:57.5+00:00

The port assignment is dynamic is to avoid port conflicts and ensure that the application process can always listen on an available port. If the port was fixed or specified by the user, there might be a situation where another process is already using that port. This would prevent the application process from starting or receiving requests. By using a dynamic port assignment, the HttpPlatformHandler/ANCMv2 can find an open port at runtime and pass it to the application process. This can adapt to different environments and scenarios.
tadpole 20 Reputation points

2025-03-14T17:43:46.8133333+00:00
Using [HttpPlatformHandler] and [ARR Proxy + Rewrite rules] on the same (single) client request (eg mysite.com/abc) is not possible.

You can use both modules/solutions within a single site instance, but a clear understanding of the objectives & usage of these modules is beneficial.

example: within <handlers><add path="api/" verb="" ...> , all files(verb ) matching path mysite.com/api/" are handled by [HttpPlatformHandler] process. Path here is a literal string not a Regex pattern but with support of a wildcard asterisk*.

Then using a rewrite rule all requests matching url="^api2/?$" routing though [ARR Proxy + Rewrite Rules] to another server/process.

Might be useful to review the core purpose of [HttpPlatfromHandler] module vs [ARR Proxy], and some of their limitations.

Using [ARR Proxy + Rewrite], you will need to manage the start-up of the backend system yourself (via a service, or script) and some type of health keepalive script to ensure your back-end process is running or to restart it.

This is one of the advantage of using HttpPlatformHandler solution, it handles the starting of the target process, restarting it, assigning a [process] "listener port" and handling the reverse proxy route of responses back to the client from the backend system. Note each TCP socket connection has 2 ports [sender - listener]

ARR Proxy vs HttpPlatformHandler, are designed for different purposes as far as i can tell. ARR Proxy is more aligned to managing routing to processes running on different server(s). HttpPlatfromHandler for managing (reverse proxy) routing comms to processes on the same server via directory paths and dynamic ports.

Why? HttpPlatfromHandler dynamic assignment of a listener port, allows it to startup the target backend system, and create a new instance if the backend system is unresponsive. When using a static port with HttpPlatformHandler, the backend process is started on the specified static port, but reverse proxy management doesnt work (within V1.2)

Config a HttpPlatfromHandler with static port - its possible.

HttpPlatformHandler(V1.2) will start up the backend process with that defined port

but it wont route the responses back from the backend target system to IIS and back to the client[user request] (via reverse proxy rules).

You would need a 2nd/separate request to the the backend process ( mysite.com/backendCall) and use of [ARR Proxy + Rewrite rules]

The route would need to match a specific %backendCall% URL request pattern different to the one used that triggered HttpPlatformHandler.

There may be some limited use cases for this setup, potentially the backend system doesn’t support dynamic port assignment.

Example of Node.exe running Angular V19.x SSR server side mjs - with httpPlatformHandler V1.2 dynamic listener port active - ALL incoming requests using handler reverse proxy:

<handlers accessPolicy="Read, Execute, Script"> <add name="SSR" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" /> </handlers> <httpPlatform stdoutLogEnabled="true" stdoutLogFile=".\node.log" startupTimeLimit="20" processPath="C:\Program Files\nodejs\node.exe" arguments=".\test-app\server\server.mjs"> <environmentVariables> <environmentVariable name="PORT" value="%HTTP_PLATFORM_PORT%" /> <environmentVariable name="NODE_ENV" value="Production" /> </environmentVariables> </httpPlatform>
Lex Li (Microsoft) 6,032 Reputation points Microsoft Employee

2025-03-14T23:03:59.5866667+00:00

When I initially answered this question in 2023, HttpPlatformHandler v1.2 was the only context my answer relied on. In 2024 I started to ship an open source version of HttpPlatformHandler and called it as v2, so I believe a workaround is possible with that version if you dislike the dynamic port choice. Please read my updated answer below and see if that's what you wanted. Besides, you never disclose what were the actual limitations in "due to some limitations of a 3rd party web app framework I am looking for a workaround of sorts" but that's very important for others to understand the situation better and provide help.

2 answers

Your answer

TengFeiXie-MSFT 346 Reputation points

2023-08-15T09:05:57.5+00:00

The port assignment is dynamic is to avoid port conflicts and ensure that the application process can always listen on an available port. If the port was fixed or specified by the user, there might be a situation where another process is already using that port. This would prevent the application process from starting or receiving requests. By using a dynamic port assignment, the HttpPlatformHandler/ANCMv2 can find an open port at runtime and pass it to the application process. This can adapt to different environments and scenarios.
Lex Li (Microsoft) 6,032 Reputation points Microsoft Employee

2025-03-14T23:03:59.5866667+00:00

When I initially answered this question in 2023, HttpPlatformHandler v1.2 was the only context my answer relied on. In 2024 I started to ship an open source version of HttpPlatformHandler and called it as v2, so I believe a workaround is possible with that version if you dislike the dynamic port choice. Please read my updated answer below and see if that's what you wanted. Besides, you never disclose what were the actual limitations in "due to some limitations of a 3rd party web app framework I am looking for a workaround of sorts" but that's very important for others to understand the situation better and provide help.

Answer 1

Dynamic port selection makes perfect sense, as HttpPlatformHandler has a feature to restart your web app and there isn't a guarantee that the same port is always available.

You don't need extra ARR/URL rewrite rules with HttpPlatformHandler (unless you try to perform generic rewriting like HTTP to HTTPS), and you don't need to access HTTP_PLATFORM_PORT yourself.

Update: Mar 2025

In case you want to fully take control of the port number between IIS and your application server, instead of depending on HttpPlatformHandler's random choice, HttpPlatformHandler v2 (https://github.com/lextudio/httpplatformhandlerv2) allows you to make your own decision, with sample settings as below,

        <httpPlatform stdoutLogEnabled="true" stdoutLogFile=".\node.log" startupTimeLimit="20" processPath="C:\Program Files\nodejs\node.exe" arguments=".\node_modules\next\dist\bin\next start">
            <environmentVariables>
                <environmentVariable name="PORT" value="4000" />
                <environmentVariable name="NODE_ENV" value="production" />
                <environmentVariable name="DEBUG" value="socket*" />
                <environmentVariable name="HTTP_PLATFORM_PORT" value="4000" />
            </environmentVariables>
        </httpPlatform>

You can see that by setting an explicit port of 4000, the backend Node.js server will monitor port 4000 instead of a random port and you can access the same default page using http://localhost:4000. IIS/HttpPlatformHandler v2 in this case will forward the incoming traffic to port 4000 and enable reverse proxy rules.

This is still different from runnning your Node.js server on port 4000 and use IIS/ARR as reverse proxy, because HttpPlatformHandler still manages the Node.js process for you so things like implicit reverse proxy rules, application pool recycle support, app_offline.htm support, etc. continue to work as you might expected. With ARR you lose all of them and have to manage Node.js processes fully on your own.

Note that this behavior is only possible with HttpPlatformHandler v2 (as it inherites this feature from ASP.NET Core module). The original v1.2 from Microsoft doesn't support it.

tadpole 20 Reputation points

2025-03-15T13:36:22.6866667+00:00

Thanks again for V2 project, i'll need to eval it over the next week, nice upgrade combined with x64 support.

how does V2 handle unresponsive process when using an explicit listening port number (fixed port)?

V1.2, attempts to kill process and starts another process on a different port. managed by HttpPlatformHandler optional config properties :

startupTimeLimit - kill process and restart if unresponsive in x seconds.

startupRetryCount - default 10, number or retries to start process.

rapidFailsPerMinute - default 10, max fail per minute, delay handler startup for remainder of minute period.

Answer 2

Bruce (SqlWork.com) 74,936

the ports are assigned dynamically because every hosted app needs a unique port. if multiple processes are configured, than each needs its own port.

your goal is not clear. The HttpPlatformHandler is acting as a reverse proxy to the hosted application site. ARR/Url only work on requests handled by IIS. you can use url rewrite to map IIS requests to the handler. as IIS will not see actual requests to hosted app's port, not sure what you are trying to do.

Share via

Why does HttpPlatformHandler/ANCMv2 for IIS only assign a port dynamically and how to use ARR/URL Rewrite given this

2 answers

Update: Mar 2025

Your answer