NETCustomUpload - Online Manual

Introduction

These instructions are also available in pdf format. We recommend using the PDF version if a printable manual is required.

This is a .NET class that is used to save files that have been uploaded to an ASP.NET application using the csXThumbUpload ActiveX control.

NetCustomUpload can save the uploaded file to disk, or export them as an array of bytes or as a MemoryStream object. The array of bytes can be used to save the file into a binary database field. The stream can be used with image files to pass the file into a Bitmap object or the Chestysoft csImageFile COM object.

This cannot be used to save general file uploads but when used with csXThumbUpload it is fully functional. For a general ASP.NET upload class use our csNetUpload component.

Using these Instructions

These instructions are divided into a number of sections with quick links to each section. A full Table of Contents is available on the next page and an index listing all commands in alphabetical order is included at the back for easy reference.

Click on one of the links below to go directly to the section of interest:

Table of Contents

1. Getting Started

1.1. Using NetCustomUpload in ASP.NET

The DLL file Chestysoft.NetCustomUpload.dll must be placed in the \bin folder for the web application. The ASP.NET machine account must be have Read and Execute permission on the DLL file.

The permissions on the \bin folder should not allow access for the anonymous internet user, IUSR_machine_name. This is to prevent users from downloading DLLs or components.

The ASP.NET script must import the namespace NetCustomUpload. The class name is UploadClass and the ReadUpload method must be called to extract the files from the upload.

Creating the component instance in VB.NET:

<%@ Page language="vb" debug="true" %>
<%@ Import NameSpace = "NetCustomUpload" %>
<%
.
Dim Upload As New UploadClass
Upload.ReadUpload
.
%>

Creating the component instance in C#:

<%@ Page language="c#" debug="true" %>
<%@ import Namespace = "NetCustomUpload" %>
<%
.
UploadClass Upload = new UploadClass();
Upload.ReadUpload();
.
%>

Both these examples show use with the full version of the class.

All the remaining examples are shown using VB.NET.

1.2. The Version Property

The NetCustomUpload component can only be used to upload files uploaded with csXThumbUpload but a quick test can be made to check that the component is running by calling the Version property.

Version - String, read only. This returns the version information and can be used to confirm that the component is running.

Example in ASP.NET (VB):

Dim Upload As New UploadClass
Response.Write(Upload.Version)

2. Saving or Exporting the Uploaded File

Before files can be saved or exported, the ReadUpload method must be called.

ReadUpload ( ) - This method extracts the file data from the HTTP post.

2.1. Methods for Saving or Exporting Files

SaveFile (Path As String) - This saves the file to the location specified by Path. Path is the physical path on the server, complete with file name and extension.

FileToArray - This returns an array of bytes containing the file.

FileToStream - This returns a MemoryStream containing the file.

3. Methods for Reading File Properties

The following methods return information about uploaded files, such as the name, extension or file size.

FileName - String. This returns the original file name of the uploaded. This includes the extension, but not the path.

Extension - String. This returns the extension of the uploaded file. It includes the period character.

LocalName - String. This returns the full path of the file, as used on the client computer before uploading. It is the value in the file field and can also be read using Request.Form.

ContentType - String. This returns the content type that the sender indicated for the file.

FileSize - Integer. This returns the file size in bytes for the file.

4. Examples

4.1. Saving a File

<%@ Page language="vb" debug="true" %>
<%@ Import NameSpace = "NetCustomUpload" %>
<%
Dim Upload As New UploadClass
Upload.ReadUpload
Upload.SaveFile(Server.MapPath("./files/") & Upload.Filename)
Response.Write("File saved: " & Upload.FileName)
%>

The VB.NET code shown above will save an uploaded file into a sub directory called "files", using the original file name.

4.2. Saving the File to a Database Field

In most cases, when a file is uploaded to the server it is saved on disk, as described above. Sometimes there is a requirement to write the file into a binary database field. The following example shows how a file can be written to a Microsoft Access database using a field type of OLE Object.

<%@ Page language="vb" debug="true" %>
<%@ Import NameSpace = "System.Data.OleDB" %>
<%@ Import NameSpace = "System.Data" %>
<%@ Import NameSpace = "System.DateTime" %>
<%@ Import NameSpace = "NetCustomUpload" %>
<%
Dim Upload As New UploadClass
Upload.ReadUpload
Dim ConnectionString As String = "PROVIDER=MICROSOFT.JET.OLEDB.4.0;DATA SOURCE=" & Server.Mappath("sample.mdb")
Dim AConnection As OleDbConnection = New OleDbConnection(ConnectionString)
Dim SQLString As String = "SELECT * FROM Table1 WHERE 1=2"
Dim DA As OLEDBDataAdapter = New OLEDBDataAdapter(SQLString, ConnectionString)
Dim CommandBuilder As OleDbCommandBuilder = New OleDbCommandBuilder(DA)
Dim DS As DataSet = New DataSet("Table1")
DA.MissingSchemaAction = MissingSchemaAction.AddWithKey
DA.Fill(DS, "Table1")
Dim Row As DataRow = DS.Tables("Table1").NewRow
Row("FileName") = Upload.FileName
Row("FileData") = Upload.FileToArray
Row("ContentType") = Upload.ContentType
Row("Extension") = Upload.Extension
Row("UploadDate") = DateTime.Now
DS.Tables("Table1").Rows.Add(Row)
DA.Update(DS, "Table1")
AConnection.Close
%>

At lot of the code is creating the various classes that are used to open and write to the database. It must use a data adapter in order to handle complex data types, such as the OLE Object. The database fields "FileName", "ContentType" and "Extension" contain information about the file and "UploadDate" contains the current date. "FileData" is the binary data and this can be written directly using the FileToArray method from NetCustomUpload.

4.3. Copying the File to a Bitmap Object

The FileToStream method can be used to copy uploaded images into a System.Drawing.Bitmap class. The following code checks the extension of the uploaded image and if it is .bmp or .jpg it loads the image and writes out the width and height.

<%@ Page language="vb" debug="true" %>
<%@ Import NameSpace = "NetCustomUpload" %>
<%@ Import NameSpace = "System.Drawing" %>
<%
Dim Upload As New UploadClass
Upload.ReadUpload
If (Upload.Extension = ".bmp") or _
  Upload.Extension = ".jpg") Then
  Dim BMP As New Bitmap(Upload.FileToStream)
  Response.Write("Width: " & BMP.Width & "<br>")
  Response.Write("Height: " & BMP.Height & "<br>")
End If
%>

Once the image has been loaded into a Bitmap object, further image processing can be done before saving the image. Other file types are supported by the Bitmap object but only jpeg and bmp have been used here for simplicity.

4.4. Copying the File into the csImageFile COM Object

Image files can be copied directly into the Chestysoft csImageFile COM object, using similar code to that shown in Section 4.3. The FileToArray method is used.

<%@ Page language="vb" debug="true" %>
<%@ Import NameSpace = "NetCustomUpload" %>
<%@ Import NameSpace = "System.Drawing" %>
<%
Dim Image = Server.CreateObject("csImageFile.Manage")
Dim Upload As New UploadClass
Upload.ReadUpload
If (Upload.Extension = ".bmp") or _
  (Upload.Extension = ".jpg") Then
  Image.ReadVariant(Upload.FileToArray)
  Response.Write("Width: " & Image.Width & "<br>")
  Response.Write("Height: " & Image.Height & "<br>")
End If
%>

The Extension method can be used to check if the file is in a valid format, and if so, it can be loaded using the csImageFile ReadVariant method. As with the Bitmap example in the previous section, the width and height are displayed, but further image processing can be carried out before saving the image. Other file types are supported by csImageFile but only jpeg and bmp have been used here for simplicity.

5. Server Settings and Configuration

This section summarises the configuration settings that must be made on the server to run NETCustomUpload.

5.1. Location and Permissions for the DLL

The DLL file, Chestysoft.NetCustomUpload.dll must be located in the binary folder for the web application. By default, this folder is called "\bin". The permission settings on the DLL must allow the ASP.NET machine account Read and Execute permission. The Internet Guest User account (IUSR_machine_name) should not be allowed to read the DLL, to protect it from unauthorised downloads.

5.2. Permissions for Saving Files

The ASP.NET machine account must have Write permission in the folder where the uploaded files are to be saved. In addition, some consideration should be made to security. If the uploaded files are saved in a location that can be viewed by web users, it may be advisable to disable the use of scripts and executables in this folder. Otherwise a user would be able to upload a script or other executable file and then run it.

5.3. Limiting the Size of File Uploads

There is a size limit on file uploads, which is determined by the web application configuration. The size limit is defined by the maxRequestLength attribute of the httpRuntime element in either the Machine.config or Web.config files. The default value is 4 MB and usually this value is left in the Machine.config file and a Web.config file is placed in the application root folder, or the script folder, with a new value to override the default.

Here is an example of the code to be placed inside a Web.config file to set the upload size limit to 10 MB.

<configuration>
  <system.web>
  <httpRuntime maxRequestLength="10240" />
  </system.web>
</configuration>

The value is measured in kilobytes.

When a file is uploaded which is over the size limit, it produces a "Cannot find server or DNS error" message. This is not user friendly and it might be preferable to set the maxRequestLength to a value that is larger than any expected file size and if the file size needs to be limited to a smaller value, read the Request.TotalBytes property to find the uploaded size before calling NetCustomUpload.

6. Alphabetical List of Commands

Click on one of the links below to go directly to information about that command:

© Chestysoft, 2012.