Ajax Control Toolkit
AjaxFileUpload Demonstration
Click Select File to select an image file to upload. You can upload a maximum of 10 jpeg files (files with the .jpg or .jpeg extension)

AjaxFileUpload Description

AjaxFileUpload is an ASP.NET Ajax control which supports:


  • Displaying File Upload Progress

  • Uploading Very Large Files (greater than 1 Gigabyte)

  • Client-Side File Chunking
  • Uploading Multiple Files at a Time

  • Drag-and-Drop File Upload


The AjaxFileUpload control uses one of two methods of showing file upload progress. If you are using a browser which fully supports the HTML5 File API (such as Google Chrome or Mozilla Firefox) then upload progress is displayed using client-side events. If, on the other hand, you are using a browser which does not fully support the HTML5 standard (such as Microsoft Internet Explorer or Apple Safari) then file upload progress is displayed by polling the server.


The AjaxFileUpload control also supports a drag-and-drop interface. You can add multiple files to the AjaxFileUpload upload queue by dragging the files onto the AjaxFileUpload control on a page. Alternatively, you can select multiple files to upload by using the SHIFT key or CTRL key when selecting files with the file upload dialog. These features are not supported by older browsers.


By taking advantage of the AllowedFileTypes property, you can restrict the types of files which can be uploaded with the AjaxFileUpload control. For example, you can prevent any file except image files (files with the extensions jpeg, png, or gif) from being uploaded. By taking advantage of the MaximumNumberOfFiles property, you can limit the number of files which can be uploaded with the control. For example, you can prevent a user from uploading more than 5 files.


When a file is uploaded, the control's UploadComplete event is raised. By creating an UploadComplete event handler, you can store the uploaded file anywhere that you please including the file system, a database, or session state. Before you can save the file to the file system, your ASP.NET application must have the necessary Write permissions.


AjaxFileUpload Temporary Data

The AjaxFileUpload control buffers the file being uploaded onto your web server's hard drive. This temporary folder is located at Path.GetTempPath().


When you call the SaveAs() method to save the uploaded file to a new location, the AjaxFileUpload control deletes the temporary file automatically. If you don't call the SaveAs() method (for example, you are saving the uploaded file to a database) then you need to call the AjaxFileUploadEventArgs.DeleteTemporaryData() method to delete the temporary file.


AjaxFileUpload Handler

The AjaxFileUpload control uses an HTTP Handler named AjaxFileUploadHandler.axd This handler has the type AjaxControlToolkit.AjaxFileUploadHandler. You must add this handler to your Web.Config file in order for the AjaxFileUpload control to work.


Here's the Web.Config configuration that you must add:
<system.web>
    ....
    <httpHandlers>
        <add verb="*" path="AjaxFileUploadHandler.axd"
          type="AjaxControlToolkit.AjaxFileUploadHandler, 
          AjaxControlToolkit"/>
    </httpHandlers>
</system.web>
For IIS7:
<system.webServer>
    ....
    <validation validateIntegratedModeConfiguration="false" />
    <handlers>
        <add name="AjaxFileUploadHandler" verb="*" 
          path="AjaxFileUploadHandler.axd"
          type="AjaxControlToolkit.AjaxFileUploadHandler, 
          AjaxControlToolkit"/>
    </handlers>
</system.webServer>
Store To Azure

If you have a Windows Azure account, you may want to upload files directly to your Windows Azure storage. To do that, you need to follow these simple steps:

  1. Set your Windows Azure connection string by adding a setting to web.config file under the appSettings key. This settings key must be named  AjaxFileUploadAzureConnectionString. It should be like this:
    <appSettings>
        <add key="AjaxFileUploadAzureConnectionString" 
            value="[Your Azure Connection String]"/>
    </appSettings>
    To use the Windows Azure emulator with your development environment you can set the Azure connection string to UseDevelopmentStorage=true.
  2. Set StoreToAzure property to True.
  3. Set AzureContainerName property to the appropriate container name (the name of the container where you want the uploaded files to be located on your Windows Azure storage). This property cannot be blank and must follow the rules for valid Windows Azure container names. Check out this link and go to the Container Names section to see more detail.

This feature enables you to store uploaded files directly to Windows Azure. When uploading files directly to Windows Azure, you no longer need to create a temporary file to buffer the upload. Windows Azure has its own mechanism for buffering.


AjaxFileUpload Events, Properties and Methods

The control above is initialized with this code. The italic properties are optional:

<ajaxToolkit:AjaxFileUpload ID="AjaxFileUpload1"
    ThrobberID="myThrobber"
    ContextKeys="fred"
    AllowedFileTypes="jpg,jpeg"
    MaximumNumberOfFiles=10
    runat="server"/>
Events
  • UploadedComplete - Raised on the server when a file is uploaded successfully. In this event an instance of AjaxFileUploadEventArgs is passed in the argument that contains file name, size and content type.
  • UploadedCompleteAll - Raised on the server when all files are uploaded.
  • UploadedStart - Raised on the server before any files are uploaded.

Properties
  • Mode - Determines how upload progress is displayed. Possible values are Auto (the default), Client, and Server. If, for example, you want force the AjaxFileUpload control to display upload progress by using server-side polling then set Mode="Server".
  • ThrobberID - The ID of a control that is shown while the file is uploading. The throbber image is displayed for browsers that do not support the HTML5 File API or server-side polling.
  • ContextKeys - A dictionary that can be used to pass information to the server when a file is uploaded.
  • MaximumNumberOfFiles - This property enables you to limit the number of files that a user can add to the upload queue.
  • AllowedFileTypes - This property enables you to restrict the types of files that can be uploaded. You can assign a comma delimited list of file extensions to this property.
  • IsInFileUploadPostBack - This property has the value true when a page is created in response to an AjaxFileUpload asynchronous postback.
  • OnClientUploadComplete - The name of a JavaScript function executed on the client-side after a file is uploaded successfully.
  • OnClientUploadError - The name of a JavaScript function executed on the client-side if the file upload failed.
  • OnClientUploadCompleteAll - The name of a JavaScript function executed on the client-side after all files are uploaded.
  • OnClientUploadStart - The name of a JavaScript function executed on the client-side before any files are uploaded.

Methods
  • SaveAs(string filename) - Saves the contents of an uploaded file to the file system. Your application must have the required Write permissions.
  • CleanAllTemporaryData() - Delete all temporary uploaded files from temporary folder.
Copyright © 2006-2013 Microsoft Corporation. All Rights Reserved.