You may be wondering why ActiveFile even provides a download capability. All you need is the right URL and you can download a file, right? And your Active Server Pages application can use the redirect method of the Request object to control this, right? Well, we think there are some major advantages to using ActiveFile to download the file.

Without ActiveFile, your file must be associated with an URL and therefore must be in a Virtual Directory your web server has access to.  This can be a real problem if the file you are transferring contains sensitive data that is meant only for the client that requested it. With ActiveFile, your Active Server Pages application can send files from directories that are not mapped as a Virtual Directory giving you a better handle on security.

Last but not least, when you use ActiveFile to download the file to the client you still have control after the file is sent. This is extremely important if you want to remove the file after it is no longer needed.

Download Topics

Creating your download script
Formatting your download URL
Controlling 'Save As' prompting

Basic steps

The steps to perform a download are simple:

1. Create a File object:
   
   Set File = Server.CreateObject("ActiveFile.File")
    
2. Point at the file and download:
   
   File.Name = "C:\Download\Download.html"
   File.Download
    

Here is a complete example that puts all of these steps together:

<% ' Initialize a file object to reference the file to be downloaded Set File = Server.CreateObject("ActiveFile.File") File.Name = "C:\private\arch.zip" ' And send it down to the browser File.Download %>

In the above example, ActiveFile will download the file C:\private\arch.zip to the web browser. For a more complete example, take a look at the ActiveFile Explorer sample application that demonstrates both file upload and download.

Clearing the Response Buffer

If your download script contains any HTML tags or Response.Write statements, this data could be included in the response causing the file to appear corrupted when it reaches the browser. To prevent this, you must either remove these tags and statements, place them within conditional code that you are sure will not execute when a file is being downloaded, or manipulate the response buffer to make sure the response is clear of this data.

Manipulating the response buffer is the safest approach to solving this problem and can be accomplished by following these steps:

1. Turn on response buffering. The following must be included as the first line of your Active Server Page:
   
   Response.Buffer = True
    
2. Clear the response buffer just prior to calling File.Download
   
   Response.Clear
    
3. End the response as soon as possible after calling File.Download
   
   Response.End
   

Here is a complete example that puts all of these steps together:

<% ' Turn on buffering Response.Buffer = True ' Initialize a file object to reference the file to be downloaded Set File = Server.CreateObject("ActiveFile.File") File.Name = "C:\private\arch.zip" ' Clear buffer and send file down to the browser Response.Clear File.Download ' End the response Response.End %>

Once you have an Active Server Pages script that can download a file, you need to reference that script through a URL. Since your Active Server Pages script will be handling the request, the URL must contain a reference to this script along with any parameters that you might need. To further complicate matters, earlier versions of Microsoft Internet Explorer inspect the URL to locate the file extension to determine the file type. Without formatting your URL correctly, this can confuse the browser and result in the file not being displayed correctly. With this in mind, your application should use URLs for downloading similar to:

download.asp?NAME=sample.zip

While most web browsers rely on the MIME type information that is automatically sent by ActiveFile, earlier versions of Microsoft Internet Explorer look at the file extension instead. By including the file name, sample.zip in this case, as a query string parameter at the end of the URL, Microsoft Internet Explorer will correctly interpret the file as a ZIP archive.

Microsoft Internet Explorer will not interpret the URL correctly if the period (.) in the file extension of your file name parameter is encoded as %2E. This will happen if you pass the value to Server.URLEncode, which you may need to do if you file names contain spaces or other special characters. In this case, be sure to use the Replace function after you call Server.URLEncode to change the %2E encoding back to the period (.) character.

Controlling 'Save As' Prompting

Depending on your application you may want the end user to save the file being downloaded to their local file system. Differences in the way web browsers behave make this difficult to control from the server. The problems involve getting the browser to automatically prompt with the 'Save As' dialog and getting the correct default file name to show up.

Getting the Correct Default File Name

When web browsers prompt to save a file being downloaded, they will display a default file name to save the user from having to type in the name. Unfortunately, getting the correct default file name to show up is complicated by the fact that the URL is actually referencing your ASP application.

Netscape browsers and even Microsoft IE 4.0 and higher browsers recognize a "Content-Disposition" header for specifying a file name. By including the following line in your ASP script, just before calling File.Download, you can get the correct file name on some browsers.

Response.AddHeader "Content-Disposition", "inline; filename=" & File.FileName

A partial solution for Microsoft Internet Explorer versions prior to 4.0 is to make sure you are using a correct download URL that contains the file name as a query string parameter such as:

download.asp?NAME=sample.zip

In this case, Microsoft browsers that do not recognize the "Content-Disposition" header will interpret the file name to be download.zip. While the first part of the file name is incorrectly base on the name of the ASP script, the file extension is correct.

A complete solution for getting the exact file name to show up on all browsers including Internet Explorer 3.0 and other browsers that don't recognized the "Content-Disposition" header is to exploit the ActiveFile Download Filter. The ActiveFile Download Filter allows you to include extra path information in your download URL. By appending the correct file name after the name of your ASP script, you can control what file name the browser uses as the default in the 'Save As' dialog. For the above example your application should use the following download URL.

download.asp/sample.zip?NAME=sample.zip

Note that even when using the Download Filter, the file name must still be included as a query string parameter at the end of the URL.

For a complete working example, refer to the Download Filter version of ActiveFile Explorer.

Forcing 'Save As' Prompting

Depending on what web browser is being used and how it has been configured, downloading a given file may or may not result in the user being prompted with the 'Save As' dialog. The file may very well end up being displayed by the browser, a plug-in, or a helper application. Netscape browsers can always be tricked into prompting by using the MimeType parameter on the File.Download method to send an undefined MIME type value, such as 'application/unknown'. Because Netscape uses the MIME type value to look up the appropriate action for processing the file, using an undefined value avoids the use of any plug-ins or helper applications configured to display the file. Unfortunately, this does not work with Microsoft browsers.

Like Netscape browsers, Microsoft browsers also allow the action to take for a given type of file to be configured by the user. However, Microsoft does not rely solely on the MIME type value to look up the file type. First, Microsoft looks at the OLE document type. Next, if the file is not an OLE document, the file extension is used. Finally, if the file extension has not yet been associated with a file, the MIME type value will be used. This means that if you are downloading an OLE document, such as Microsoft Word files, you can not control the behavior. And even if you are downloading non-OLE files, you will not be able to control the behavior unless you are using a file extension that has not been mapped. Because of these limitations, it is recommended that you instruct your Microsoft browser users as follows:

If you select a file to be downloaded and it is viewed inside the browser instead you can either:

• Select 'Save As' from the File menu while viewing the file.
  
  or

• Back up to the page containing the download URL and select the 'Save Target As' option from the right mouse button pop-up menu.

or

• Change the default file action for the type of file being downloaded to prompt for saving.

If you still choose to send an undefined MIME type value using the File.Download method, be aware that Microsoft Internet Explorer 3.0 has a bug that causes text (.txt) files and HTML (.htm,.html) files to not download correctly if an undefined MIME type value is sent. The download request appears to complete successfully but the file will not be displayed or saved. To avoid this bug, your application should special case the browser type, the file type, or both and only send an undefined MIME type value if the browser is a Netscape browser or the file is not a text or HTML file.