IIS Support

Overview

Due to how IIS handles FastCGI (named pipes) on Windows, which is incompatible with the GoLang implementation, it is not possible to directly integrate the axonasp-fastcgi.exe binary into IIS.

Therefore, as recommended by Microsoft for running other engines like Python, AxonASP must be integrated via httpPlatformHandler. Another option is using the IIS reverse proxy. In this case, you must start AxonASP separately and ensure continuous execution (you can use a service implementation). The target address must be set to http://localhost:8801 (modify the port if necessary). The httpPlatformHandler implementation is recommended, as it automatically manages the server lifecycle. For further instructions on configuring a reverse proxy, check the documentation for reverse proxy setup or visit https://learn.microsoft.com/en-us/iis/extensions/url-rewrite-module/reverse-proxy-with-url-rewrite-v2-and-application-request-routing.

We provide the iis-http.cmd file in both the Windows installation and the project root directory. You must define it in the processPath="C:\axonasp\iis-http.cmd" attribute. Warning: If AxonASP is not installed in the default directory (C:\axonasp\), you must modify the file to point to the correct directory. Otherwise, the system will fail to locate the configuration file, and script execution will fail silently.

Because IIS does not allocate a real console during server execution, console messages via stdoutLogEnabled="true" will always yield a blank stdoutLogFile. This is a strict limitation caused by the integrated C-supported SQLite library, which crashes the server if started without an attached console. AxonASP error and console messages will continue to be written to the location defined in the axonasp.toml configuration file.

Installation

Before running AxonASP on IIS, you must install the IIS HttpPlatformHandler v1.2 module or higher, available at: https://www.iis.net/downloads/microsoft/httpplatformhandler

Configuration

Following the installation of the HttpPlatformHandler module, you must configure your IIS web.config as follows:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
        </handlers>
        <httpPlatform processPath="C:\axonasp\iis-http.cmd"
                      arguments="--server.server_port %HTTP_PLATFORM_PORT%"
                      stdoutLogEnabled="true"
                      stdoutLogFile="C:\axonasp\temp\axonasp.log"
                      startupTimeLimit="5"
                      processesPerApplication="1">
            <environmentVariables>
                <environmentVariable name="SERVER_PORT" value="%HTTP_PLATFORM_PORT%" />
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>

Warning: Ensure the IIS user, typically defined as IIS_IUSRS, has read/write permissions to the AxonASP folders and files. This is required for writing to the temp directory and for executing both iis-http.cmd and axonasp-http.exe. Without proper permissions, the process will fail silently and return a 500 Internal Server Error.

The executable that IIS will proxy traffic to is axonasp-http.exe. Consequently, your ASP files, global.asa, AxonASP web.config, and overall infrastructure must reside within the default directory defined in axonasp.toml (default C:\axonasp\www\). IIS acts solely as a reverse proxy starting the executable. For proper isolation, we recommend that each AxonASP Application/Site is placed in a dedicated folder containing its own executable and .toml configuration file. Also, set the clean_sessions_on_startup in the configuration file to prevent session being lost if IIS finish the application process, or users may experience unexpected behavior when using features that require persistent sessions. For better performance, you can also set clean_cache_on_startup to false.

Limitations

While IIS natively supports Classic ASP, it is highly resource-intensive. If possible, consider migrating to a lighter reverse proxy setup (e.g., Nginx, Caddy).

The Microsoft IIS implementation spawns a FastCGI process with named pipes for each individual request. This contrasts with Nginx/Apache/Caddy architectures, which start a single persistent process and route requests via TCP. This IIS behavior can cause anomalous execution state, particularly regarding session persistence and Application-level memory data.

Because we recommend isolating each application in its own server process due to global.asa scoping rules, and because supporting IIS FastCGI directly would require a complex architectural rewrite, native IIS FastCGI support will not be implemented at this time. For this same reason, you must not set processesPerApplication to a value greater than 1, as it will cause state fragmentation and anomalous behavior.