DEV Community

Cover image for Modernizing Classic ASP: A Practical Guide to Hosting AxonASP Behind IIS
Lucas Guimarães
Lucas Guimarães

Posted on

Modernizing Classic ASP: A Practical Guide to Hosting AxonASP Behind IIS

#iis #asp #microsoft #webdev

Let’s be honest: when most developers hear "Classic ASP," they picture legacy Windows Servers, clunky COM object registrations, and an architecture deeply entangled with asp.dll and the IIS worker process (w3wp.exe).

But the code itself—often thousands of lines of critical business logic written in VBScript or server-side JavaScript—still does exactly what it needs to do. The problem isn't necessarily the language; it’s the aging, monolithic hosting architecture.

This is where AxonASP changes the game. Built in Go, it completely untangles ASP from the Windows OS, executing code natively and dropping idle memory usage down to around 18MB.

However, moving to this engine requires a fundamental shift in how you think about hosting your applications.

The Paradigm Shift: Application-Centric Architecture

Now, regarding your biggest concern about hosting architecture: AxonASP is not a direct replacement for IIS; it is a Classic ASP runtime. It operates on a modern, application-centric architecture—structurally identical to how modern .NET Core or Docker applications are deployed.

This means all your existing IIS configurations remain entirely valid. To properly orchestrate AxonASP within IIS, you must use the HttpPlatformHandler v1.2+ module. You can read more about the setup in the official manual here:

For example, in the axonasp.toml file, you can set the root directory to match your default IIS site directory. This allows you to serve your static files (CSS, JS, images) through IIS natively while AxonASP handles the application logic and dynamic .asp requests.

The whole idea is to universalize and implement modern administration practices for ASP so it can run on any platform or server. This way, if one website runs out of control or exhausts its memory, it won't crash the other applications or the main server, because every application runs its own distinct, isolated instance of axonasp-http.exe.

This setup also allows you to run ASP inside Docker containers, significantly reducing the costs associated with Windows servers. It might seem a bit complicated at first, but it is definitely worth migrating to this approach—it is more secure, highly distributable, cheaper, and ultimately easier to manage.

Step-by-Step: Implementing AxonASP on IIS

Because IIS handles FastCGI via Windows named pipes (which is incompatible with standard TCP FastCGI protocols), we can't just plug AxonASP in as a legacy module. Instead, IIS will act as a reverse proxy, standing at the edge of your network (Ports 80/443) and forwarding dynamic requests to isolated AxonASP instances running on internal loopback ports (e.g., 8801, 8802).

Here is how to set it up.

1. Prerequisites

You need the IIS HttpPlatformHandler v1.2+. This is the exact same module Microsoft recommends for managing Python or Java applications behind IIS. It handles process management, dynamically assigns ports, and ensures your AxonASP executable stays alive.

2. Directory and Permissions

Let's say your site is located at C:\Sites\App1\.
Inside this folder, you should have:

  • The axonasp-http.exe binary.
  • The axonasp.toml config file.
  • The iis-http.cmd wrapper script (provided with AxonASP).
  • Your www folder containing your .asp files.

Crucial Step: The IIS user identity (usually IIS_IUSRS or the specific ApplicationPoolIdentity) must have read/write permissions to this folder. AxonASP needs to write to its temp directory and execute the binaries. If permissions are missing, IIS will silently fail and throw a 500 Internal Server Error.

3. The web.config Configuration

Drop a web.config file into the root of your IIS site. This tells IIS to stop trying to process the code natively and instead hand it off to the AxonASP process.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
        </handlers>

        <httpPlatform processPath="C:\Sites\App1\iis-http.cmd"
                      arguments="--server.server_port %HTTP_PLATFORM_PORT%"
                      stdoutLogEnabled="true"
                      stdoutLogFile="C:\Sites\App1\temp\axonasp.log"
                      startupTimeLimit="5"
                      processesPerApplication="1">
            <environmentVariables>
                <environmentVariable name="SERVER_PORT" value="%HTTP_PLATFORM_PORT%" />
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>
Enter fullscreen mode Exit fullscreen mode

Understanding the Configuration Mechanics

There are two critical details in the XML above that dictate how your application behaves:

  • %HTTP_PLATFORM_PORT%: You don't need to manually assign port 8801 to Site A and 8802 to Site B. IIS generates an available port dynamically, injects it into the environment variable, boots the AxonASP process, and routes traffic to it automatically.
  • processesPerApplication="1": Do not change this to a higher number. Classic ASP relies heavily on in-memory state (Session variables and the global.asa lifecycle). If IIS spawns multiple worker processes for a single site, your user sessions will fracture across them. AxonASP handles concurrency internally via Go routines; it only needs one OS process per site.

Why This Architecture is the Future of ASP

By decoupling the execution engine from the OS, you are no longer tied to legacy Windows infrastructure.

  1. The Post-COM Era: AxonASP intercepts Server.CreateObject("ProgID") natively. Instead of relying on the fragile Windows Registry to load an outdated DLL, AxonASP maps that call to a pre-compiled, high-speed GoLang code living inside the VM that executes Go modern code.
  2. Infrastructure as Code: Your routing rules, configurations, and environment variables are now text files (.toml and .config) that travel with your application repository.
  3. The Docker Horizon: Once you successfully migrate a site to this proxy pattern on IIS, migrating that same site to a Linux Docker container behind Nginx or Caddy requires almost zero changes to your application logic.

Classic ASP might be decades old, but with an engine built in Go and an architecture mimicking modern microservices, there's no reason it can't run on the edge of today's web infrastructure.

Top comments (0)