Quickstart: Download from the filesystem

This quickstart will walk you through building a handler to support downloads from the server filesystem.

Download Source Code

» Prerequisites

An ASP.NET site with a page you want to use to handle downloads. This example is downloadable as an ASP.NET 2.0 web site solution, but the code and settings described below will work exactly the same in any version of ASP.NET (v1.0-v3.5). For ASP.NET 1.0, see the workaround in the Stream file download how to entry.

» Creating a download handler

First, you need to create a handler resource that will perform the actual download to the client. You could use an aspx, but since its just a file download the whole page lifecycle isn't needed. In this case, it's better to use an ashx, which is basicaly a barebones endpoint. This avoids the unneccessary overhead of the aspx.

To create the download handler

1. Select Project->Add New Item
2. Pick "Generic Handler" from the list of items
3. Name your handler "Download.ashx"
4. Remove all code inside the ProcessRequest method.
5. Modify the IsReusable property of the handler to return true

After adding the handler, the handler source code should look like this:

using System;
using System.Web;

public class Download : IHttpHandler
{  
    public void ProcessRequest(HttpContext context)
    {
    }

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

» Adding download code

Now that the handler shell exists, we need to add code to actually perform the download. Information about the important sections can be found in the how to:

» Set the Content-Type for a download

» Set a file name for a download and show download dialog

» Stream file download

To add code to the download handler

1. Copy the following code and paste it inside the ProcessRequest method

// Get the file name from the query string
string queryFile = context.Request.QueryString["file"];

// Ensure that we were passed a file name
if (string.IsNullOrEmpty(queryFile))
    throw new FileNotFoundException();

// Generate the server file name        
string file = Path.Combine(context.Server.MapPath("~/Files"), queryFile);

// Ensure that the file exists
if (!File.Exists(file))
    throw new FileNotFoundException();

// Set the content type
// TODO: set based on extension
context.Response.ContentType = "image/jpeg";

// Set the filename
context.Response.AddHeader("content-disposition", "attachment;filename=" + queryFile);

// Stream the file to the client
context.Response.WriteFile(file);

Now when this handler gets hit for a valid file the user gets a download box – with file name:

Download Source Code