Version

Configuring WebUpload

Topic Overview

Purpose

This topic explains, with code examples, how to configure the WebUpload™ control.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic explains conceptually the WebUpload control and its features. It also demonstrates how to add the control to an ASPX page.

This topic demonstrates how to configure the HTTP Module and HTTP Handler to process the server events necessary to accept the data uploaded with the WebUpload control.

WebUpload Configuration Overview

WebUpload Configuration summary

The WebUpload control has a large set of options which allow you to customize it for your specific needs. You can control the allowed file types, specify the number of files that can upload simultaneously, configure the user interactions in the file panel (how many files they can select for upload in one pass and how this is displayed in the WebUpload panel ), and choose whether the upload will start automatically or after some explicit user action. For further details, refer to WebUpload Configuration summary chart and the sections that follow it.

WebUpload Configuration summary chart

The following table lists the configurable aspects of WebUpload . Additional details are available after the table.

Configurable aspects Details Properties

You can configure whether users, when selecting the files to upload, will be able to select multiple files or only one file at a time.

You can configure whether the upload will start automatically once the user has added the file(s) to the WebUpload panel or manually (on user’s pressing the Upload button).

You can configure which types of files will be allowed for users to upload.

You can configure the maximum number of files that can be uploaded per page refresh.

This setting configures the threshold on the number of simultaneous file uploads.

You can configure how many files to be displayed in the panel of the WebUpload control.

Configuring the File Selection Mode (Single/Multiple)

Overview

You can configure whether users, when selecting the files to upload, will be able to select multiple files or only one file at a time. This functionality is managed by the file selection mode of WebUpload . The file selection mode can be either Single File (users can select only one file at one pass) or Multiple Files (users can select multiple files at one pass).

In Multiple Files file selection mode, users can:

  • Select multiple files at once from the file Open dialog

  • Drag-and-drop the files from Windows® Explorer onto the WebUpload control

In Single File selection mode, users can select only one file in the file Open dialog and cannot drag-and-drop files. If they want to upload multiple files, they will have to add the files to the WebUpload control panel repeating the adding procedure for each file.

The following pictures illustrate the two alternative file selection approaches: selecting multiple files in the file Open dialog (left) or dragging and dropping them from Windows Explorer onto the WebUpload control panel (right).

Multiple files selection in the file Open dialog Dropping selected files from Windows Explorer onto WebUpload
Configuring WebUpload 1.png
Configuring WebUpload 2.png

The default file selection mode is Single File.

The file selection mode is managed by the Mode and MultipleFiles options. Setting MultipleFiles to true makes sense only when Mode is Multiple . When Mode is Single , MultipleFiles has no effect.

The File Selection Mode feature employs the HTML 5 multiple attribute of the input element. This makes the feature browser-dependent. If an unsupported browser is used, then setting the feature’s properties has no effect, meaning that users will not be able to select multiple files from the file Open dialog or drag-and-drop them onto the WebUpload control. For the list of the supported browsers, see Requirements.

Requirements

Following are the requirements for configuring the file selection type:

  • A browser supporting HTML 5 multiple attribute of the input element

This functionality is available only in the following browsers:

Chrome Firefox Internet Explorer Opera Safari

1.0 or higher

3.6 or higher

10 or higher

10.62 or higher

5 or higher

Property settings

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Set the file selection mode to Multiple Files

  • “Multiple”

  • True

Set the file selection mode to Single File

  • “Single”

Example

This example demonstrates how to enable multiple files selection as a result of the following settings:

Property Value

Mode

"Multiple"

MultipleFiles

True

Configuring WebUpload 1.png

Following is the code that implements this example.

In ASPX:

<ig:WebUpload ID="WebUpload1" runat="server" Mode="Multiple" MultipleFiles="True">
</ig:WebUpload>

Configuring the Upload Trigger (Manual/Auto)

Overview

You can configure whether the upload will start automatically once the user has added the file(s) to the WebUpload panel or manually (on user’s pressing the Upload button). This functionality of the WebUpload control is called “upload trigger”. The upload trigger enables or disables the automatic start of the file upload.

The default upload trigger is Manual.

The upload trigger is managed by the AutoStartUpload option of the WebUpload control.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Enable automatic upload

True

Disable automatic upload

False

Example

This example demonstrates how to enable automatic upload for users a result of the following settings:

Property Value

True

Following is the code that implements this example.

In ASPX:

<ig:WebUpload ID="WebUpload1" runat="server" AutoStartUpload="True">
</ig:WebUpload>

Configuring the Allowed File Types

Overview

You can configure which types of files will be allowed for users to upload. This functionality is handled by explicitly listing the file name extensions of the allowed file types in a list of permissible file types. This list is a collection of FileUploadExtension objects representing the allowed file extensions as the value of the AllowedExtensions property.

By default, all file types can be uploaded.

The file extension validation compares the selected file extension against the list of extensions declared in AllowedExtenstions property. When the file extension validation fails, the WebUpload ‘s onError event is raised. The second parameter of the onError handler contains an object with property errorCode = 2 and the errorMessage = “File extension validation failed.” It is up to you to decide how to present the error to the user.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Define allowed extensions

Collection of FileUploadExtension objects

Example

This example demonstrates how to set allowed users to upload .xls and .doc files:

Property Value

Collection of FileUploadExtension objects

Configuring WebUpload 4.png

Following is the code that implements this example.

In ASPX:

<ig:WebUpload ID="WebUpload1" runat="server">
    <AllowedExtensions>
        <ig:FileUploadExtension Extension="doc" />
        <ig:FileUploadExtension Extension="xls" />
    </AllowedExtensions>
</ig:WebUpload>

Configuring the Maximum Number of Files to Upload

Overview

You can configure the maximum number of files that can be uploaded per page refresh. Once this limit is reached, the Add button in the WebUpload control’s panel is disabled. When File Selection mode is Multiple, an error is thrown when the number of selected files exceeds the limit.

By default, there is no restriction on the number of files to upload.

When you have MultipleFiles = True users can select files exceeding this threshold raising an WebUpload onError event. The second parameter of the onError handler contains object with property errorCode = 1 and the errorMessage = “Maximum count of uploading files exceeded.” It is up to you to decide how to present the error to the user.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Set maximum uploaded files

The desired integer value

Example

This example demonstrates how to set the maximum number of files to upload to 2:

Property Value

2

The following picture demonstrates the Add button disabled as a result of reaching the maximum number of allowed files for upload.

Configuring WebUpload 5.png

Following is the code that implements this example.

In ASPX:

<ig:WebUpload ID="WebUpload1" runat="server" MaxUploadedFiles="2">
</ig:WebUpload>

Configuring the Maximum Number of Simultaneously Uploading Files

Overview

You can limit the number of files that can be simultaneously uploaded. Selecting files in excess of this threshold, limits the number of simultaneously uploaded files to this threshold, on a first come first serve basis, holding the excess files in abeyance until the number of files being uploaded falls below this threshold. This process continues with each of the remaining files being added to the simultaneous upload as other files complete their upload.

The maximum number of files that can be uploading simultaneously is managed by the MaxSimultaneousFilesUploads property.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Set the maximum number of simultaneous file uploads

The desired integer value

Example

The code samples below demonstrate how to set maximum simultaneous files uploads:

Property Value

2

Configuring WebUpload 6.png

Following is the code that implements this example.

In ASPX:

<ig:WebUpload ID="WebUpload1" runat="server" MaxSimultaneousFilesUploads="2">
</ig:WebUpload>

Configuring the File Display Mode

Overview

You can configure how many files can be displayed in the panel of the WebUpload control. This functionality is managed by the file display mode of WebUpload . The file selection mode can be either Single File (only one file is shown in the panel) or Multiple Files (multiple files shown in the panel).

In Multiple Files mode, the panel displays several files (arranged vertically).

In Single File mode, only one file at a time can be displayed.

The following pictures compare Single File mode and Multiple Files mode.

Single File mode Multiple Files mode
Configuring WebUpload 7.png
Configuring WebUpload 8.png

The default file mode setting is Single File.

The number of displayed files in Multiple Files mode cannot exceed the MaxUploadedFiles setting. Depending on the situation, exceeding the MaxUploadedFiles setting result with the following:

  • When MultipleFiles = False, disables the Add button when the number of files equals the MaxUploadedFiles setting.

  • When MultipleFiles = True, throws an error if the number of selected files exceeds the MaxUploadedFiles setting.

Property settings

The following table maps the desired configuration to its respective property settings.

In order to: Use this property: And set it to:

Set the display mode to Single File

“single”

Set the display mode to Multiple Files

"multiple"

Example

This example demonstrates setting the display mode to Multiple Files. This is a result of the following settings:

Property Value

" Multiple "

Configuring WebUpload 8.png

Following is the code that implements this example.

In ASPX:

<ig:WebUpload ID="WebUpload1" runat="server" Mode="Multiple">
</ig:WebUpload>

Related Content

Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic explains how to process and save upload files as either file or memory streams. A detailed procedure is provided on saving files as memory stream by individual processing of each uploaded file chunk.

Samples

The following samples provide additional information related to this topic.

Sample Purpose

This sample demonstrates setting up WebUpload ’s auto-start upload option.

This sample demonstrates configuring WebUpload to upload multiple files.

This sample demonstrates setting up the maximum number of uploaded files and the maximum simultaneous file uploads for the WebUpload control.