Click here to download the source code for this lesson.

In this lesson I am going to show you how to use the ASP.NET FileUpload and CustomValidator controls.  We will walk through an example together.  I setup a web form named FileUploadPage.aspx that allows a user to upload a .jpg picture file to the server.  The example code that I have performs some basic validation on the uploaded file such as ensuring that the size of the file falls within a certain range.  If the validation succeeds, the code saves the file to a folder called “uploads”.  Let me first describe the two server controls a little bit.

The ASP.NET FileUpload control can be used when you want the user to upload a file and then save the file on the server or in a database.  You have be careful when you use this server control because you are giving the user the ability to temporarily perform operations on the web server which could be hazardous to your server’s health.  An example of this is if a malicious user repeatedly submits large files to clog your server’s resources (hard drive space, etc.).  *A couple of tips to keep your applications more secure are to restrict the size of the files that you allow the user to upload and do NOT allow the user to name the target file that is saved on your web server (i.e. your application should create the filename).  I will show you how to implement these two tips in this lesson.  When you use the FileUpload control you have the option to either save the uploaded file to the server’s hard disk, or you can access the file in memory and put it somewhere else (e.g. in a database table).  *Putting large files in a database table is something that I would avoid because it can turn your database into a huge and difficult to manage entity.

The ASP.NET CustomValidator control allows you to create server side validation methods and associate them with particular controls that are in your web form.  This is contrast to the RequiredFieldValidator, RangeValidator and RegularExpressionValidator controls that I covered in previous blog entries.  With those other validation controls, you don’t really have to write any code, but with the CustomValidator you can create your own validation rules in C# code.  In this lesson I am going to use the CustomValidator to make sure that an uploaded file size doesn’t exceed a predefined maximum size.  The CustomValidator control does have a couple of Properties that are similar to the other validation controls.  Those are the ControlToValidate and the ErrorMessage properties.  Click here to learn more about the other validation controls and properties mentioned here.  Look for the articles with the title of ASP.NET validation controls.

Alright, now let me take you step by step through the lesson.  First I dragged a FileUpload control onto my web form FileUploadPage.aspx.  The FileUpload control is in the Standard group of Toolbox controls.  After you drag it onto a web form the FileUpload looks like a TextBox with a Browse button right next to it.  The FileUpload server control is actually rendered as an HTML input type=”file” tag in the browser.  The ID of my control is “FileUpload1″.

<asp:FileUpload ID="FileUpload1" runat="server" /> 

Next I added an Upload button that is responsible for posting the web form back to the web server.  Then I dragged a couple of CustomValidator controls underneath the button.  The CustomValidator controls are in the Validation group in the Toolbox.  The first CustomValidator control that I put in my form is responsible for making sure that the uploaded file is at least 1K in size.  I set its ErrorMessage property to “File must be at least 1K”.  If the validation fails for this control, that message will be displayed to the user on the web page.  Next I set the CustomValidator OnServerValidate property to “validateMinimumFileSize”.  The OnServerValidate specifies the name of a server side method that will execute the code for the CustomValidator control.  In my example, I have a method in my code behind class file named validateMinimumFileSize.  When my web form executes and a post back occurs, ASP.NET will automatically call my validateMinimumFileSize method.  This only happens during post backs (e.g. when a button is pressed).

<asp:CustomValidator ID="CustomValidator1" runat="server"
 ControlToValidate="FileUpload1"

ErrorMessage="File must be at least 1K"
 OnServerValidate="validateMinimumFileSize"></asp:CustomValidator>

I then created the validateMinimumFileSize method in my FileUploadPage code behind class file.  Since the method is going to be called automatically by the control and ASP.NET, the method has to follow a specific signature (i.e. you have to put a couple of standard method input arguments).  I will tell you a little bit more about the arguments later.  Let’s take a look at what my example method looks like.

protected void validateMinimumFileSize(object source, ServerValidateEventArgs args)
{
 //Get the information about the file that was uploaded.
 HttpPostedFile postedfile = FileUpload1.PostedFile;
 
 //If the file was less than the minimum size
 //of 1K, reject it.
 if (postedfile.ContentLength < 1024)
 {
      args.IsValid = false;
      mPassedValidation = false;
 }
 else
      args.IsValid = true;
}

On the first line of my method, I am getting an HttpPostedFile object from the FileUpload control.  That object contains the file that was uploaded to the server and has a ContentLength property that I can access to determine the size of the file.  I check that value and if it is less than 1K, I set the IsValid property to false.  The args input argument contains the IsValid property so that your method can communicate with ASP.NET to let it know whether or not the validation failed.  If you set it equal to false, ASP.NET will assume that the validation failed and display the ErrorMessage on the web page.  Setting it to true, passes the validation.

I repeated pretty much the same steps for the second CustomValidator control that checks to make sure that the file size doesn’t exceed a certain limit.  In that case I am calling a method named validateMaximumFileSize.  That method looks very similar to the other validation method above.  If I wanted to perform additional validation logic in this web page, I could drag additional CustomValidator controls and create more server side methods to perform validation business logic.

The advantage of using CustomValidator in this fashion is that it separates the validation logic from your other processing.  Also, it comes in handy because you can create as many server side rules as you want and ASP.NET will automatically call all of them for you.  This is a big benefit of event driven programming in C# with ASP.NET.  Now let’s look at the actual processing of the file during the upload.

I created a button click event handler method for the Upload button named btnUpload_Click.  Here it is.

protected void btnUpload_Click(object sender, EventArgs e)
{
//If the file passed all the validation rules, only
//then do we save it to the hard drive.
if (mPassedValidation)
{
string serverfilename = System.Guid.NewGuid().ToString()
+ ".jpg";
FileUpload1.SaveAs(Server.MapPath("") +
"\\Uploads\\" + serverfilename);
txtResults.Text = "File successfully uploaded at "
+ DateTime.Now.ToString() + "\r\n";
}
else
txtResults.Text = "";
}

In this method I am creating a unique file name for the uploaded file by using a .NET Guid object.  This will create a file name that will look something like “020261de-0627-43a2-b4f4-a0911488e7f5.jpg”.  This is to ensure that no two users can have the same file name and it also eliminates the security risk of allowing the user to name their file on the server.  To save the file to the hard disk on the web server I am calling the SaveAs method of the FileUpload object.  That method expects the full path file name of where you want to save on the hard drive.  I save the uploaded images into an Uploads folder.

One thing you will notice is that I use a shared class instance variable named mPassedValidation in order for all of the methods to be able to communicate with each other.  If any of the validation methods fail, they set that boolean variable to false, which prevents the saving of the uploaded file onto disk.  To read more about class instance variables click here.

To summarize, there is a couple of things going on inside this web page.  I have a control that is responsible for uploading a file to the web server.  That control checks to ensure that all validation passed before it saves the file.  Finally there are a couple of separate validation controls that actually perform the logic of ensuring that the file size is within a given desired range.

To watch a video of this example project actually running click here.  See how I choose different files with different sizes and see how the program behaves.

So how do you intend to use the FileUpload or CustomValidator controls?