图片上传和显示控件

 

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 0, 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