圖檔上傳和顯示控件

Introduction

I am obsessed with writing reusable software components. I have done several web projects where users need to upload files to the server. I think it is time for me to write a reusable component to simplify possible future work. Nowadays it is hard to write anything that has not been done multiple times on CodeProject already. However, I believe what I am about to present is different from what has been done by others and at least some audience will benefit from it.

User Controls for File Uploading and Viewing

First, let me show you a screen shot. It is a web application with which users can upload and view files. It is done using three ASP.NET user controls,

FileUploadControl

,

FileListControl

, and

PictureBrowseControl

.

My reusable component consists of three ASCX files, one for each control, and a DLL. In the above application, the user can select a file from the local computer, click "submit" button to upload the file to server. The file will be shown as a thumbnail image on the same page immediately. Clicking the thumbnail will open the file in a separate window. If the files uploaded are pictures, clicking the "browse pictures" link will allow the user to browse through pictures one by one. The "view slide show" button will start a slide show of the uploaded files.

What's so special about that? Well, the first special thing is, you almost don't need to write any code to get the above features. To use this component, all you need is add the DLL and the three ASCX files to your ASP.NET web project. Then, drag and drop the ASCX file(s) to your web page. Here is the web form content of the demo page above. As you can see,

FileUploadControl

and

FileListControl

are present on the web form, and there are also two links to other pages that have the

PictureBrowseControl

(for browsing and slide show).

Collapse

Copy Code

<div align="center" >
    <h2>File Upload Demo Page</h2>
    <uc1:FileUploadControl ID="FileUploadControl1" runat="server" /><br />
    <uc2:FileListControl ID="FileListControl1" runat="server" /><br />
    <a href="PictureBrowseDemo.aspx" target="_blank">Browse Pictures</a><br />
    <a href="SlideShowDemo.aspx" target="_blank">View Slide Show</a><br />
</div>       

Besides the user controls, what code do I have to write for this demo page? Two lines. Actually, even if you comment out the two lines of code below, the application still "works". The only anomaly is, the user won't be able to see the file he/she uploaded immediately, it will show up when the page refreshes.

Collapse

Copy Code

protected void Page_Load(object sender, EventArgs e)
{
    if   (IsPostBack)
    {
         // the magic two lines of code
        FileUploadControl1.ProcessUpload();
        FileListControl1.DisplayFileList(false );
    }
}       

That means, in any of your ASP.NET applications, you can provide file uploading and viewing features by simply dragging and dropping my user controls to your web page (and perhaps adding a few lines of codes). If I add two more lines of code to the

Page_Load

function above, you will get the capability of deleting uploaded files.

Collapse

Copy Code

protected void Page_Load(object sender, EventArgs e)
{
    if   (IsPostBack)
    {
         // the magic two lines of code
        FileUploadControl1.ProcessUpload();
        FileListControl1.DisplayFileList(false );
    }
    else
    {
         // two more lines to make delete possible
        FileListControl1.SetFolderPath(null);
        FileListControl1.SetDelete(true );
    }
}       

See screen shot below:

If you click the "delete" link below a thumbnail, the corresponding file will be deleted.

What if you want users to be able to upload more than one file at a time? The answer is, no problem. You can customize

FileUploadControl

to accomplish that. The other two controls,

FileListControl

and

PictureBrowseControl

are also easily customizable. In general, you can modify the ASCX files to change the appearances of the user controls. However, when you do that, the changes will be made to all instances of the controls in your web project. Also, you need to be careful not to change too much to break the code in the DLL, especially the

runat="server"

elements of the control.

The three user controls provide some

public

methods for you to modify appearance and behavior for a single instance at run time. I will be getting into more details on this in the following sections.

FileUploadControl

This control uses an HTML table to group and separate various UI elements. It has the following

public

methods:

Collapse

Copy Code

public void SetFolderPath(string sFolderPath)       

Where did the uploaded file go? The

SetFolderPath

method sets the path of the folder that will be used to store user uploaded files, if the folder does not exist yet, calling this method will also create the folder. If the argument string does not begin with drive letters (c:, d:, etc.), it will be treated as a path relative to the web application root. Note that the folder path is a property of the current instance of the control, each user can use a different folder to store uploaded files.

When

FileUploadControl

saves a file into the folder, it will use a new GUID as file name so that users won't override each other's files in case they are uploading to the same physical folder. It will also create/update a special file FileInfo.data located in the same folder. This special file contains information of all uploaded files within this folder, such as file name, file description (provided by user who does the uploading), original file path on user's computer, and date/time the file was uploaded. FileInfo.data will be used by the other two controls,

FileListControl

and

PictureBrowseControl

. If input parameter

sFolderPath

is

null

, then folder uploadedfiles under the web application root will be created/used to store files.

Once you uploaded files into a folder using

FileUploadControl

, you can copy the whole folder to a different place (or a different server), the files will still be usable by

FileListControl

and

PictureBrowseControl

. This is because FileInfo.data contains everything that is needed to use these files.

Collapse

Copy Code

public void ShowControlItem(int nItemIndex, bool bShowFile, bool bShowDescriptiion)
public void ShowControl(bool[] pShowFile, bool[] pShowDescription)       

FileUploadControl

allows you to upload up to 5 files at a time. In design mode, the control looks like the following. By default, only the first item (the file browse row and the associated description row) is shown. The other 4 items are hidden.

If you want to show or hide items in the control for the whole web project, you can modify file fileuploadcontrol.ascx directly, changing the visible attributes of various rows. Alternatively, you can call these two methods to modify appearance of a single instance of

FileUploadControl

.

The

nItemIndex

parameter can be

,

1

,

2

,

3

, or

4

. If

bShowFile

is

true

, then the corresponding row with browse button will be shown, otherwise it will be hidden. The

bShowDescription

parameter determines whether the corresponding description text box will be shown or hidden. The method

ShowControl

shows / hides all 5 items at once. The input parameters

pShowFile

and

pShowDescription

should be boolean arrays of length

5

.

Collapse

Copy Code

public void SetControlItemLabel
	(int nItemIndex, string sFileLabel, string sDescriptionLabel, bool bHTML)
public void SetControlLabel(string[] pFileLabel, string[] pDescriptionLabel, bool bHTML)       

The label texts can be changed as well. Again, changing file fileuploadcontrol.ascx will make the change global to the whole web project, calling these two methods will make the change for a single instance of the control. For example, the following line of code...

Collapse

Copy Code

SetControlItemLabel(0, "Picture File:", "Picture Title:", false);       

... will replace the default labels on the control, see picture below (note the different text in the circle).

The last parameter

bHTML

indicates whether the label texts you passed to this method are in HTML format. If

bHTML

is

true

, you can use HTML to manipulate the appearance of the label, such as changing font type, size, color, etc.

Collapse

Copy Code

public void SetClass(string sLabelClass, string sTextClass, string sTableClass)       

You can use cascading style sheet to change the appearances of various elements on the control. In this method,

sLabelClass

is the CSS class for labels,

sTextClass

is the CSS class for text box, and

sTableClass

is the CSS class for the table that contains all visual elements of the control.

Collapse

Copy Code

public void SetSize(string sUploadControlWidth, 
	int nDescriptionBoxSize, string sTableWidth)       

The size of the elements in the control is changeable, too. Here,

sUploadControlWidth

is the width of the file browse box,

nDescriptionBoxSize

is the number of visible characters in the description text box, and

sTableWidth

is the width for the parent table.

Collapse

Copy Code

public void ProcessUpload(string sFolderPath)
public void ProcessUpload( )       

ProcessUpload

is the method that does all the processing for

FileUploadControl

. This method is invoked when user clicks the "submit" button on the control, it can also be invoked by the parent ASPX page as shown in the demo code.

FileListControl, PictureBrowseControl

FileListControl

displays uploaded files as thumbnail images on the parent ASPX page. Thumbnail image files are generated automatically by

FileUploadControl

when users uploaded the files. If a file uploaded is not a picture, then a generic thumbnail image will be used instead.

FileListControl

has the following

public

methods:

Collapse

Copy Code

public void SetFolderPath(string sFolderPath)
public void SetClass(string sFileDescriptionClass, string sTableClass)
public void SetSize(string sDescriptionFontSize, string sTableWidth)
public void ShowHideDescription(bool bShowDescription, bool bShowDescriptionAsLink)
public void SetDelete(bool bEnable)
public void DisplayFileList(string sFolderPath, bool bMostRecentFirst)
public void DisplayFileList(bool bMostRecentFirst)       

I will not bore you with details on each of the methods listed above. What I want to point out is,

SetFolderPath

determines which folder to retrieve the files and thumbnail images. It must be a folder under the web application root for

FileListControl

to work properly. This is different from

FileUploadControl

. If input parameter

sFolderPath

is

null

, then uploadedfiles under the web application root is assumed (and created if it does not exist).

PictureBrowseControl

let you browse through picture files in a folder one by one or start a slide show. Like

FileListControl

, the folder must be under the web application root. Here are the

public

methods of

PictureBrowseControl

.

Collapse

Copy Code

public void SetFolderPath(string sFolderPath)
public void SetClass(string sLinkClass, string sFileDescriptionClass, string sTableClass)
public void SetSize(int nPictureWidth)
public void DisplayPicture( )
public void OpenSlideShow( )       

As you can see, the picture browse demo page has no code at all, everything is taken care of by the instance of

PictureBrowseControl

on the page.

To make a slide show, you need to do the following:

1. Create an ASP.NET page
2. Add tag

   <meta http-equiv="refresh" content="6" />

   to the page header
3. Drag file picturebrowsecontrol.ascx to the page
4. Call

   SetFolderPath

   and then call

   OpenSlideShow

   on

   Page_Load

   function

The meta tag determines how fast the slide show will go, it is 6 seconds delay for each picture in the above example.

Finally,

PictureBrowseControl

will close the parent page if it finds no file in the target folder.

Some Important Application Settings

It would be foolish to allow users to upload any type of file to your server. Allowed file types are controlled by

AppSettings

key "

UploadUtilAllowedUploadTypes

" in your application's web.config file. By default, the following types are allowed:

• Image files (.jpg, .gif, .bmp, .png)
• Text files (.txt)
• Zip files (.zip, .rar)
• HTML and XML files (.htm, .html, .xml)
• Word files (.doc, .docx, .rtf)
• Excel files (.xls, .xlsx, .csv)
• PowerPoint files (.ppt, .pptx)
• PDF files (.pdf)
• Media files (.avi, .flv, .swf, .mpg, .wma, .wmv, .mpeg, .mp3, .mp4)

This setting is a string of semi-colon delimited file extensions. For example, if you want to allow only JPG and GIF images, then you need to set value of this setting as string "

.jpg;.gif

".

Thumbnail image size can be defined in

AppSettings

key "

UploadUtilImageThumbSize

", the default is

100x100

(pixels).

Virus Scan: If you set the value of

AppSettings

key "

FileUploadControlScanVirus

" to

true

, then

FileUploadControl

will do virus scan for the files you uploaded, any suspicious file will be deleted automatically. However, virus scan is the most un-reusable part of this tool because it assumes that anti-virus software Trend Micro is installed on the server. To make Trend Micro scan virus for you, you also need to put the full path of the program vscanwin32.com (which comes with Trend Micro) in the value of

AppSettings

key "

UploadUtilAVLocation

". To use a different anti-virus software, you need to rewrite this part.

Finally, the number of thumbnail images per row in

FileListControl

is defined in

AppSettings

key "

FileListControlTableColumns

", the default is

6

.

Using This Component in Your Own Project

The included zip file has two folders. UploaderSource contains all source code files, UploaderWeb contains the compiled reusable parts (three ASCX files and one DLL) as well as the demo application. Note that I used ILMerge to produce the single DLL. It is not necessary to include the demo ASPX files into your own project. What you need to do is:

1. Include the three ASCX files and the DLL in your ASP.NET web project
2. Drag and drop ASCX file(s) onto your web page
3. Call methods in the user control(s) from your code

The DLL also contains a utility class called FileUploadUtility.Tools, which has the following

public static

methods. This utility class is used in all three of the user controls and it can be used from your own code.

Collapse

Copy Code

public static void CreateThumbForFile
	(string sFileName, string sFolderPath, string sDefaultThumbImagePath)
public static bool CheckFileType(string sFilePath)
public static bool IsFilePicture(string sFileName)
public static bool CheckVirus(string sFilePath)
public static Hashtable LoadFileInfo(string sFolderPath)
public static void StoreFileInfo(string sFolderPath, Hashtable oFileInfo)
public static void RemoveFile(string sFolderPath, string sFileName)
public static UploadFileInfo GetUploadFileInfo(string sFolderPath, string sFileName)
public static UploadFileInfo GetUploadFileInfo(Hashtable oFileInfo, string sFileName)
public static UploadFileInfo[] GetUploadFileInfo(string sFolderPath) 
public static void ProcessFolder(string sFolderPath, string sDefaultThumbImagePath)      

What if user wants to view or browse an existing folder, say a folder with picture files, and these files are not uploaded using

FileUploadControl

? Can I still use

FileListControl

and

PictureBrowseControl

? The answer is, yes. What needs to be done is call the last method above,

ProcessFolder

, then you will be able to use these two controls on this folder with no problem. Otherwise user will not see any file in the folder.  The method

ProcessFolder

creates the file

FileInfo.data

for this folder and also creates thumbnail images for files in the folder.

http://www.codeproject.com/KB/aspnet/FileUploadUtility.aspx