What is an ASHX file?

An ASHX file is a webpage that is used by the ASP.NET HTTP Handler to serve user with the pages that are referenced inside this file. The ASP.NET HTTP Handler processes the incoming request, references the pages from the .ashx file, and sends back the compiled page back to the user’s browser. The method of processing is mostly similar to that of ASPX files with the differecne that in this case, the referenced pages/documents are processed and sent back.

ASHX File Format

The .ashx files are saved in plain text file format and contains references to other pages or documents that are sent back to user’s browser upon request. These can be opened in any text editor and developer IDEs such as Xamarin Studio, Microsoft Notepad, Notepad++, and many more. The ASHX files are useful in case when you have:

  • Binary files
  • Dynamic image views
  • Performance-critical web pages
  • XML files
  • Minimal web pages

How to dynamically compile an ASHX file?

The following steps can be used to add and compile an ASHX file using Microsoft Visual Studio.

  • add a Generic handler - Handler1.ashx in visual studio
  • delete the cs file which auto-created.
  • open ashx again, ** remove CodeBehind=“Handler1.ashx.cs” ** add c# code below
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;

public class Handler1 : IHttpHandler
{
    public void ProcessRequest(HttpContext context)
    {
        context.Response.ContentType = "text/plain";
        context.Response.Write("Hello World2");
    }

    public bool IsReusable
    {
        get
        {
            return false;
        }
    }
}

ASHX Example

The following ASHX code returns the image file to user’s request when the ASHX file is called in internet browser.

<%@ WebHandler Language="C#" Class="QueryStringHandler" %>  

using System;  
using System.Web;  

public class QueryStringHandler : IHttpHandler   
{  
    public void ProcessRequest (HttpContext context)   
    {  
        HttpResponse r = context.Response;  
        r.ContentType = "image/png";  
        string file = context.Request.QueryString["file"];  
        if (file == "Arrow")  
        {  
            r.WriteFile("Arrow.gif");  
        }  
        else  
        {  
            r.WriteFile("Image.gif");  
        }  
    }  

    public bool IsReusable   
    {  
        get  
        {  
            return false;  
        }  
    }  
}

Key Characteristics of the ASHX File Format

CharacteristicDescription
No Page Lifecycle OverheadASHX handlers bypass the Init, Load, Render, and Unload events of traditional pages, focusing solely on request processing.
Direct Response ControlDevelopers have precise control over every aspect of the HTTP response, including headers, status codes, and output streams.
Stateless by DefaultWhile session state can be enabled, ASHX handlers are naturally stateless, aligning with RESTful principles and scalable architectures.
No UI MarkupUnlike ASPX or ASCX files, ASHX handlers contain no HTML, CSS, or client-side scripting—they’re purely server-side processors.
Extension-Based RoutingThe .ashx extension is mapped to the System.Web.UI.SimpleHandlerFactory in IIS, routing requests directly to handler logic.
Web.config IntegrationCan be configured or registered in web.config for centralized management and virtual path routing.
IIS IndependenceWhile optimized for IIS, the handler model is compatible with other ASP.NET hosts with proper configuration.

FAQ

Q1: What is the primary purpose of an ASHX file?

A: ASHX files serve as lightweight HTTP handlers for processing specific web requests without the overhead of full ASP.NET pages.

Q2: Can ASHX files display HTML user interfaces?

A: While they can output HTML, they’re designed for data processing rather than UI rendering—use ASPX pages for complex interfaces.

Q3: How do ASHX handlers differ from ASPX pages?

A: ASHX handlers skip the page lifecycle and focus solely on the ProcessRequest method, offering better performance for specific tasks.

Q4: Are ASHX files compatible with ASP.NET Core?

A: No, ASP.NET Core replaces the handler model with middleware—migrate to controllers or middleware components instead.

Q5: Can ASHX handlers maintain session state?

A: Yes, but you must implement the IRequiresSessionState marker interface and enable session state in the handler.

References

See Also