ASP.NET ASHX Handler TutorialUse the ASHX file format in the ASP.NET framework. Create a Handler.ashx file.
ASHX Handler. Some ASP.NET files are dynamic. They are generated with C# code or disk resources. These files do not require web forms. Instead, an ASHX generic handler is ideal. It can return an image from a query string, write XML, or any other data.
First in this tutorial, we review the goal of using ASHX files in ASP.NET framework. We use the ASHX file in a URL, and have it dynamically return content. We will use the query string. The final URLs will look like this.
Getting started. We list the steps to add a new ASHX file. To do this, open your ASP.NET web site. Go to the Website menu and click on the first menu item there, "Add New Item". This will present the Add New Item dialog box.
Then Select the "Generic Handler" item, and you will get a new file with some code in it called Handler.ashx.
Url example:
Autogenerated code. What purpose does the autogenerated code in the ASHX file have? It defines two parts of the IHttpHandler interface. The important part is ProcessRequest(), which will be invoked whenever the Handler.ashx file is requested.
Tip You should not change the interface inheritance or remove either of the members.
Part of Web.config file, XML:
<system.web> <urlMappings enabled="true"> <add url="~/Default.aspx" mappedUrl="~/Handler.ashx"/> </urlMappings> ...
Mappings. It is often desirable to map an older URL or path to your new ASHX file. For backwards compatibility and for search engine optimization, you will probably want the new handler to take over an old URL in your site.
Tip To do this, use urlMappings. Alternatively you can use more complex RewritePath methods.
ASHX code-behind file, C#:
<%@ WebHandler Language="C#" Class="Handler" %> using System; using System.Web; public class Handler : IHttpHandler { public void ProcessRequest (HttpContext context) { // Comment out these lines first: // context.Response.ContentType = "text/plain"; // context.Response.Write("Hello World"); context.Response.ContentType = "image/png"; context.Response.WriteFile("~/Flower1.png"); } public bool IsReusable { get { return false; } } }
URL mappings. The above Web.config markup will automatically link one URL to another. When the Default.aspx page is requested, your Handler.ashx file will take over. This means you can map the default page in a directory to your handler.
ASHX modified code-behind, C#:
<%@ WebHandler Language="C#" Class="Handler" %> using System; using System.Web; public class Handler : IHttpHandler { public void ProcessRequest (HttpContext context) { HttpResponse r = context.Response; r.ContentType = "image/png"; // // Write the requested image // string file = context.Request.QueryString["file"]; if (file == "logo") { r.WriteFile("Logo1.png"); } else { r.WriteFile("Flower1.png"); } } public bool IsReusable { get { return false; } } }
Add example image. We mention what you can do with the ASHX file involving images. Find your favorite image on your disk or on the Internet and add it to your website project. For my example, the image I chose was "Flower1.png".
Next We will use this image in the Handler.ashx file. We implement an image-based handler.
URL 1:
URL: http://www.dotnetperls.com/?file=logo File query string: logo File written: Logo1.png
URL: http://www.dotnetperls.com/?file=flower File query string: flower File written: Flower1.png
Modify Handler.ashx. Your handler has two parts. Here we modify the ProcessRequest method. We can change the ContentType of the file and the Response content. Modify your Handler.ashx to be similar to the following, with your image ContentType and file name.
Use Web Forms...:
If you have simple HTML pages ASP.NET custom controls Simple dynamic pages
If you have binary files Dynamic image views Performance-critical web pages XML files Minimal web pages
Test handler. Here we test the new configuration and ASHX file on the local machine. Now click the green arrow to run your website on the development server. You should see the image in your browser. This is the result of the handler.
Add functionality. The example here so far is relatively useless. All it does is allow us to pipe an image through an ASHX handler. You can add any functionality (logging code or referrer logic) to the handler in the C# language.
Also, developers commonly need to use the QueryString collection on the Request. You can use the Request.QueryString in the Handler just like you would on any ASPX web form page. The code is the same.
What this does. The above code receives requests and then returns a different file based on the QueryString collection value. It will return one of two images from the two query strings. The strings it returns are shown.
Test query string. Does all this work? Yes, but it is always important to test. Open your browser. And on the path, add query strings like those shown above. What happens is that ASP.NET internally maps the Default.aspx page to your Handler.ashx.
Then The Handler.ashx file receives the query string and writes the appropriate file.
Uses. The code here could be used as a hit tracker that counts visitors and logs referrers. This could provide a more accurate visit count than server logs, because of browser and bot differences.
Handlers versus web pages. ASP.NET web forms inherit from the Page class. This provides them with many events and a detailed initialization and event model. You don't need that for dynamic images, XML, or binary files.
Image Output
Performance. Is there any performance advantage or change to using ASHX files? These files are less complex and they do not involve as many events. They are more streamlined and involve less code, and this is an advantage.
As you can imagine, firing more than ten events each time a request is handled is a fair amount more expensive than only firing one event. Therefore, there will be some performance advantage to using ASHX files where possible.
IsReusable I do not know precisely what the IsReusable property does. Much of the supporting code is not in the ASHX file itself.
But My reading indicates it can improve performance and decrease memory pressure by not repeatedly destroying the handler.
Choose handlers. Here I want to propose some guidelines about when to choose custom handlers and when to prefer ASPX web form pages. Handlers are better for binary data, and web forms are best for rapid development.
Control trees. In the ASP.NET Framework, web forms use a concept called control trees where the parts of web pages are stored in an object model. Use custom handlers when you do not require the custom control tree or the whole HTML web form framework.
Note This will result in greater performance. And the code will be much simpler code to debug.
Summary. We used ASHX custom handlers in an ASP.NET website. This could fill many different important web site functions. We combine urlMappings with query strings on custom handlers to greatly simplify and streamline back-end web site code.
© 2007-2022 sam allen.
see site info on the changelog.