Chapter 2: Simple Uploads

The following HTML form (located in the sample file Form1.asp) enables a user to select up to three files for uploading to the server:

If your browser supports HTML5, the three file items on the form above can be replaced by a single file item with the multiple attribute, as follows:

Notice the ENCTYPE="multipart/form-data" attribute in the <FORM> tag. It instructs the browser to send the entire file to the server and not just the file name entered in the input text box. It is absolutely mandatory that your upload forms contain this attribute, or no uploading can be performed.

This form contains three items <INPUT TYPE="FILE"> which appear on the page as text boxes with the Browse button next to them. Each box can be used to select one file only. While the SIZE attribute of an <INPUT TYPE="FILE"> item is optional, the NAME attribute is required.

This form invokes the upload script UploadScript1.asp shown below:

The first line of the ASP script simply creates an instance of the AspUpload object. The second line calls the Save method of the component which actually performs the upload: it parses the information POSTed by the browser, figures out how many files are being uploaded, and saves them in a specified local directory on the server under their original names.

The Save method returns the number of files successfully uploaded. In case of an error this method will throw an exception.

Click the links below to run this code sample:

http://localhost/aspupload/02_simple/Form1.asp http://localhost/aspupload/02_simple/Form1.aspx

Due to the "multipart/form-data" attribute of upload forms, your ASP script can no longer use the built-in Request.Form collection to access individual form items. AspUpload solves this problem by offering two collections of its own, Upload.Files and Upload.Form to provide access to uploaded files and text fields, respectively.

Upload.Files is a collection of UploadedFile objects which offer access to various properties and attributes of uploaded files, such as filename, path, size, hash value, etc. The UploadedFile object also offers many methods which enable you to manipulate uploaded files (copy, move, save to the database, delete, etc.) Individual items of the collection can be referenced via numeric or string indices, or iterated through via the For-Each statement.

Upload.Form is a collection of FormItem objects that represent text fields on an upload form. Upload.Form is similar to Request.Form and should be used instead of the latter in your upload script. The FormItem object provides two properties, Name and Value.

The use of the Files and Form collections is demonstrated by the sample files Form2.asp and UploadScript2.asp:

This form contains both <INPUT TYPE=FILE> and regular <INPUT TYPE=TEXT> items. It invokes the script UploadScript2.asp:

Click the link below to run this code sample:

http://localhost/aspupload/02_simple/Form2.asp

The output should look similar to this:

IMPORTANT: The Upload.Files and Upload.Form collections are populated by the Upload.Save method. Therefore, it is incorrect to reference either collection before the Save method is called:

1. Enable ASP Compatibility Mode

AspUpload 3.0 is not a native ASP.NET component. It was written specifically for classic ASP, and it uses many intrinsic ASP objects such as Request. Therefore, you must enable the classic ASP compatibility mode for all pages using AspUpload by setting the aspCompat attribute of the @Page directive to True:

<%@ Page aspCompat="True" other attributes%>

Failure to do so will result in the run-time error

2. Use Wrapper Assembly

Create a \bin subdirectory under your ASP.NET application and place the wrapper assembly ASPUPLOADLib.dll in it. Alternatively, you can place this file in the Global Assembly Cache. The file ASPUPLOADLib.dll is included in the setup AspUpload.exe. You may also re-create this file using the command-line utility TLBIMP.

For more information, see the knowledge base article PS020704100.

The following script written in C# demonstrates AspUpload's usage under .NET:

Click the link below to run this code sample:

http://localhost/aspupload/02_simple/Form2.aspx

The previous code sample uses the For-Each loop to iterate through the Files and Form collection. It is also possible to reference individual file and form items via integer or string indices, for example:

When referencing an individual item from the Files collection, it is a good idea to check whether a file was actually selected via the referenced input type=file box, as follows:

The Upload.Form collection is not entirely identical to Request.Form as it handles multi-select form items such as <SELECT MULTIPLE> differently.

The sample files Form3.asp and UploadScript3.asp (not shown here) demonstrate how to handle all basic input form items with the Upload.Form collection. Click the link below to run this code sample:

http://localhost/aspupload/02_simple/Form3.asp http://localhost/aspupload/02_simple/Form3.aspx

By default, AspUpload overwrites existing files in the upload directory. In a multi-user environment, this is undesirable, as multiple users may upload files with the same name.

AspUpload can be configured to generate unique names for the files being uploaded to prevent overwriting existing files in the upload directory. This is done by setting UploadManager's OverwriteFiles property to False before calling Upload.Save, as follows:

To prevent name collisions, AspUpload appends the original file name with an integer number in parentheses. For example, if the file MyFile.txt already exists in the upload directory, and another file with the same name is being uploaded, AspUpload will save the new file under the name MyFile(1).txt. If more copies of MyFile.txt are uploaded, they will be saved under the names MyFile(2).txt, MyFile(3).txt, etc.

AspUpload is capable of enforcing file size limits by rejecting or truncating uploaded files as specified by the SetMaxSize method. By default, any size files are accepted (as long as the total upload does not exceed 2 GB).

The SetMaxSize method expects two arguments: the maximum file size (in bytes) and a flag indicating whether a file exceeding the limit should be rejected with an error exception thrown (if set to True) or truncated (if set to False).

A value set by SetMaxSize is applied to each uploaded file individually rather than an entire upload. Since AspUpload has no way of knowing in advance how many files there are in a POST and how large they are, it will always allow the upload process to go through, even if the very first file exceeds the specified limit.

The sample files Form4.asp and UploadScript4.asp demonstrate a file upload system with file size limit enforced. Here is what the upload script looks like:

Click the link below to run this code sample:

http://localhost/aspupload/02_simple/Form4.asp

If the Upload.Save method is called in a script invoked directly rather than via a multipart/form-data form, the following error will occur:

This creates a problem if you want to place both your form and the corresponding upload script in the same file. To avoid this error, set the property Upload.IgnoreNoPost to True.

The code sample BothFormAndScript.asp demonstrates the usage of this property.

Click the link below to run this code sample:

http://localhost/aspupload/02_simple/BothFormAndScript.asp