public class AjaxFileUpload : WebControl, IComponent, IDisposable, IParserAccessor, IUrlResolutionService, IDataBindingsAccessor, IControlBuilderAccessor, IControlDesignerAccessor, IExpressionsAccessor, IAttributeAccessor, IPostBackDataHandler

Constructors

AjaxFileUpload()

Initializes a new instance of the AjaxFileUpload control.

Declaration

public AjaxFileUpload()

Properties

AllowMultiple

Compatibility alias for Multiple that lets older markup keep using the legacy member name.

Declaration

public bool AllowMultiple { get; set; }

Property Value

Type	Description
bool

AllowedExtensions

Compatibility alias for Extensions that keeps older configuration names working.

Declaration

public string AllowedExtensions { get; set; }

Property Value

Type	Description
string

AllowedMimeTypes

Gets or sets the allowed MIME types as a comma-separated list.

Declaration

public string AllowedMimeTypes { get; set; }

Property Value

Type	Description
string

AutoOrient

Gets or sets whether image EXIF orientation data should be applied automatically.

Declaration

public bool AutoOrient { get; set; }

Property Value

Type	Description
bool

AutoPostBack

Automatically posts the page back once every file in the batch has finished uploading, so FileUploaded runs without the user clicking a submit button - the v4 (CuteWebUI) behaviour. The default is enabled when the page handles a server upload-completion event; set it explicitly to true to force a postback for a custom flow, or false to disable it.

Declaration

public bool AutoPostBack { get; set; }

Property Value

Type	Description
bool

AutoUpload

Gets or sets whether uploading starts immediately after file selection. When set to false, client code can start the queue manually.

Declaration

public bool AutoUpload { get; set; }

Property Value

Type	Description
bool

ButtonText

Gets or sets the browse button text.

Declaration

public string ButtonText { get; set; }

Property Value

Type	Description
string

ChunkSize

Gets or sets the chunk size in bytes when chunked uploads are enabled. A value of 0 falls back to ChunkSizeBytes.

Declaration

public int ChunkSize { get; set; }

Property Value

Type	Description
int

Chunked

Gets or sets whether uploads should be sent in chunks. When enabled, the control uses the chunk endpoints and the effective value of ChunkSize.

Declaration

public bool Chunked { get; set; }

Property Value

Type	Description
bool

Concurrent

Gets or sets the number of file uploads processed in parallel. Higher values can improve throughput but use more browser and network resources.

Declaration

public int Concurrent { get; set; }

Property Value

Type	Description
int

ConcurrentUploads

Compatibility alias for Concurrent that uses the older concurrent-upload naming.

Declaration

public int ConcurrentUploads { get; set; }

Property Value

Type	Description
int

Crop

Gets or sets whether client-side image cropping is enabled.

Declaration

public bool Crop { get; set; }

Property Value

Type	Description
bool

CropAspectRatio

Gets or sets the crop aspect ratio applied by the client crop UI.

Declaration

public string CropAspectRatio { get; set; }

Property Value

Type	Description
string

DetectDuplicates

Gets or sets whether duplicate files should be detected on the client before upload.

Declaration

public bool DetectDuplicates { get; set; }

Property Value

Type	Description
bool

DropOverlay

Gets or sets whether the full-page drop overlay is enabled. This only applies when FullPageDrop is also enabled.

Retained for compatibility. The overlay is what FullPageDrop renders rather than a separate layer, so enabling FullPageDrop is what turns it on. Use DropOverlayText to change its caption.

Declaration

public bool DropOverlay { get; set; }

Property Value

Type	Description
bool

DropOverlayText

Gets or sets the text shown inside the full-page drop overlay.

Declaration

public string DropOverlayText { get; set; }

Property Value

Type	Description
string

DropZone

Gets or sets whether the built-in drop zone is rendered inside the control. This is separate from FullPageDrop, which turns the whole page into a drop target.

Declaration

public bool DropZone { get; set; }

Property Value

Type	Description
bool

DuplicateHashAlgorithm

Gets or sets the hash algorithm used for duplicate detection when hash-based checks are enabled. Typical values are crc32 and sha256.

Declaration

public string DuplicateHashAlgorithm { get; set; }

Property Value

Type	Description
string

EmitLegacyClientApi

Gets whether to emit the v4 (CuteWebUI) client-side API onto the container element. Off for the modern control; the legacy wrappers turn it on.

Declaration

protected virtual bool EmitLegacyClientApi { get; }

Property Value

Type	Description
bool

EnableAntiforgery

Gets or sets a reserved option for pages that integrate custom antiforgery handling around upload requests.

Declaration

public bool EnableAntiforgery { get; set; }

Property Value

Type	Description
bool

EnableChunkedUpload

Compatibility alias for Chunked that preserves older chunked-upload settings.

Declaration

public bool EnableChunkedUpload { get; set; }

Property Value

Type	Description
bool

EnableDropZone

Compatibility alias for DropZone that preserves older drag-and-drop settings.

Declaration

public bool EnableDropZone { get; set; }

Property Value

Type	Description
bool

EnableDuplicateCheck

Compatibility alias for DetectDuplicates.

Declaration

public bool EnableDuplicateCheck { get; set; }

Property Value

Type	Description
bool

EnableExifOrient

Compatibility alias for AutoOrient.

Declaration

public bool EnableExifOrient { get; set; }

Property Value

Type	Description
bool

EnableImageCrop

Compatibility alias for Crop.

Declaration

public bool EnableImageCrop { get; set; }

Property Value

Type	Description
bool

EnableImageDimensions

Gets or sets whether client-side image dimension validation is enabled. Pair this with MinWidth, MinHeight, MaxWidth, and MaxHeight.

Declaration

public bool EnableImageDimensions { get; set; }

Property Value

Type	Description
bool

EnableImagePreview

Compatibility alias for ShowThumbnails.

Declaration

public bool EnableImagePreview { get; set; }

Property Value

Type	Description
bool

EnableImageResize

Compatibility alias for ImageResize.

Declaration

public bool EnableImageResize { get; set; }

Property Value

Type	Description
bool

EnableLightbox

Gets or sets whether image preview lightbox behavior is enabled for preview interactions.

Declaration

public bool EnableLightbox { get; set; }

Property Value

Type	Description
bool

EnableMimeCheck

Compatibility alias for ValidateMimeByMagic.

Declaration

public bool EnableMimeCheck { get; set; }

Property Value

Type	Description
bool

EnablePaste

Compatibility alias for Paste.

Declaration

public bool EnablePaste { get; set; }

Property Value

Type	Description
bool

EnableResume

Gets or sets whether resumable upload state is enabled for the client queue. Completed client-side state is persisted under a key derived from the control ID.

Declaration

public bool EnableResume { get; set; }

Property Value

Type	Description
bool

Extensions

Gets or sets the allowed file extensions as a comma-separated list.

Declaration

public string Extensions { get; set; }

Property Value

Type	Description
string

FolderDrop

Gets or sets whether dropped folders are accepted when the browser exposes directory upload support.

Retained for compatibility. Directory drops are handled whenever the browser supports webkitGetAsEntry, so this property does not gate the behaviour and setting it false does not switch folder drops off.

Declaration

public bool FolderDrop { get; set; }

Property Value

Type	Description
bool

FullPageDrop

Gets or sets whether the whole page acts as a drag-and-drop target. This is useful for pages where files may be dropped anywhere, not only on the control body.

Declaration

public bool FullPageDrop { get; set; }

Property Value

Type	Description
bool

Gallery

Gets or sets whether uploaded image previews are presented in a gallery-style layout.

Declaration

public bool Gallery { get; set; }

Property Value

Type	Description
bool

ImageResize

Gets or sets whether client-side image resizing is enabled.

Declaration

public bool ImageResize { get; set; }

Property Value

Type	Description
bool

ImageResizeHeight

Compatibility alias for ResizeMaxHeight.

Declaration

public int ImageResizeHeight { get; set; }

Property Value

Type	Description
int

ImageResizeWidth

Compatibility alias for ResizeMaxWidth.

Declaration

public int ImageResizeWidth { get; set; }

Property Value

Type	Description
int

Inline

Gets or sets whether the control renders in a more compact inline layout.

Declaration

public bool Inline { get; set; }

Property Value

Type	Description
bool

Items

Gets the files uploaded in the current postback, with data access attached - enumerate from any postback handler to read, copy or move each file.

Declaration

[Browsable(false)]
public IList<UploadedFile> Items { get; }

Property Value

Type	Description
IList<UploadedFile>

Remarks

The v4 Items pattern on the modern control. Guids whose stored file is gone (already moved, or swept) are skipped rather than returned as empty entries, matching the event path's stale-guid guard.

KeyboardNavigation

Gets or sets whether deep keyboard navigation of the upload queue is enabled (roving tabindex, Arrow/Home/End focus movement, Delete/Enter row actions). Enabled by default.

Declaration

public bool KeyboardNavigation { get; set; }

Property Value

Type	Description
bool

MaxCount

Gets or sets an overall item limit for the client-side queue.

Declaration

public int MaxCount { get; set; }

Property Value

Type	Description
int

MaxFileCount

Compatibility alias that keeps MaxFiles and MaxCount in sync.

Declaration

public int MaxFileCount { get; set; }

Property Value

Type	Description
int

MaxFileSize

Compatibility alias for MaxSize that keeps older configuration names working.

Declaration

public string MaxFileSize { get; set; }

Property Value

Type	Description
string

MaxFiles

Gets or sets the maximum number of files that can be queued for the control.

Declaration

public int MaxFiles { get; set; }

Property Value

Type	Description
int

MaxHeight

Gets or sets the maximum allowed image height when image-dimension validation is used.

Declaration

public int MaxHeight { get; set; }

Property Value

Type	Description
int

MaxImageHeight

Compatibility alias for MaxHeight.

Declaration

public int MaxImageHeight { get; set; }

Property Value

Type	Description
int

MaxImageWidth

Compatibility alias for MaxWidth.

Declaration

public int MaxImageWidth { get; set; }

Property Value

Type	Description
int

MaxRetries

Gets or sets the number of retry attempts for failed upload requests. This works together with RetryDelay.

Declaration

public int MaxRetries { get; set; }

Property Value

Type	Description
int

MaxSize

Gets or sets the maximum allowed file size. Values can be expressed in bytes or with KB, MB, or GB suffixes.

Declaration

public string MaxSize { get; set; }

Property Value

Type	Description
string

MaxWidth

Gets or sets the maximum allowed image width when image-dimension validation is used.

Declaration

public int MaxWidth { get; set; }

Property Value

Type	Description
int

MetaFields

Gets or sets the per-file editable metadata fields as a JSON array (e.g. [{"id":"caption","label":"Caption"},{"id":"category","required":true}]). Each field renders an inline input on pending/failed queue rows; required fields block that file's upload until filled. Values ship to the server as a metadata form field and an X-Upload-Meta header. Invalid JSON is ignored.

Declaration

public string MetaFields { get; set; }

Property Value

Type	Description
string

MinFileSize

Compatibility alias for MinSize.

Declaration

public string MinFileSize { get; set; }

Property Value

Type	Description
string

MinHeight

Gets or sets the minimum allowed image height when image-dimension validation is used.

Declaration

public int MinHeight { get; set; }

Property Value

Type	Description
int

MinImageHeight

Compatibility alias for MinHeight.

Declaration

public int MinImageHeight { get; set; }

Property Value

Type	Description
int

MinImageWidth

Compatibility alias for MinWidth.

Declaration

public int MinImageWidth { get; set; }

Property Value

Type	Description
int

MinSize

Gets or sets the minimum allowed file size. Values can be expressed in bytes or with KB, MB, or GB suffixes.

Declaration

public string MinSize { get; set; }

Property Value

Type	Description
string

MinWidth

Gets or sets the minimum allowed image width when image-dimension validation is used.

Declaration

public int MinWidth { get; set; }

Property Value

Type	Description
int

Multiple

Gets or sets whether the file picker allows multiple file selection.

Declaration

public bool Multiple { get; set; }

Property Value

Type	Description
bool

OnClientComplete

Gets or sets the JavaScript callback invoked when the current queue run completes successfully.

Declaration

public string OnClientComplete { get; set; }

Property Value

Type	Description
string

OnClientError

Gets or sets the JavaScript callback invoked when an upload request fails or returns an error response.

Declaration

public string OnClientError { get; set; }

Property Value

Type	Description
string

OnClientFileSelected

Compatibility alias for OnClientSelect that preserves older client callback naming.

Declaration

public string OnClientFileSelected { get; set; }

Property Value

Type	Description
string

OnClientMetaChange

Gets or sets the JavaScript callback invoked when a metadata field value changes (receives (task, fieldId, value)).

Declaration

public string OnClientMetaChange { get; set; }

Property Value

Type	Description
string

OnClientProgress

Gets or sets the JavaScript callback invoked during upload progress updates for active tasks.

Declaration

public string OnClientProgress { get; set; }

Property Value

Type	Description
string

OnClientRenditionCreated

Gets or sets the JavaScript callback invoked when a rendition file is generated (receives (renditionTask, originalTask)).

Declaration

public string OnClientRenditionCreated { get; set; }

Property Value

Type	Description
string

OnClientSelect

Gets or sets the JavaScript callback invoked after files are selected and added to the queue.

Declaration

public string OnClientSelect { get; set; }

Property Value

Type	Description
string

OnClientTaskComplete

Gets or sets the JavaScript callback invoked when a single queued file finishes uploading.

Declaration

public string OnClientTaskComplete { get; set; }

Property Value

Type	Description
string

OnClientTaskError

Gets or sets the JavaScript callback invoked when a single queued file fails.

Declaration

public string OnClientTaskError { get; set; }

Property Value

Type	Description
string

OnClientUploadComplete

Compatibility alias for OnClientComplete that preserves older client callback naming.

Declaration

public string OnClientUploadComplete { get; set; }

Property Value

Type	Description
string

ParallelChunks

Compatibility alias for Concurrent used by older parallel-chunk style settings.

Declaration

public int ParallelChunks { get; set; }

Property Value

Type	Description
int

Paste

Gets or sets whether clipboard paste upload is enabled.

Declaration

public bool Paste { get; set; }

Property Value

Type	Description
bool

PrioritizeFirstAndLastChunk

Gets or sets whether chunk 0 and the final chunk upload before the middle chunks, letting the server validate the file's head/tail early.

Declaration

public bool PrioritizeFirstAndLastChunk { get; set; }

Property Value

Type	Description
bool

Renditions

Gets or sets the scaled renditions generated client-side alongside each image upload, as a JSON array (e.g. [{"name":"thumb","maxSize":200},{"name":"medium","maxWidth":1024,"format":"image/webp","quality":0.8}]). Each rendition uploads as its own file linked to the original via renditionOf. Invalid JSON is ignored.

Declaration

public string Renditions { get; set; }

Property Value

Type	Description
string

ResizeFormat

Gets or sets the output format used for client-side image resizing.

Declaration

public string ResizeFormat { get; set; }

Property Value

Type	Description
string

ResizeMaxHeight

Gets or sets the maximum height used for client-side image resizing.

Declaration

public int ResizeMaxHeight { get; set; }

Property Value

Type	Description
int

ResizeMaxWidth

Gets or sets the maximum width used for client-side image resizing.

Declaration

public int ResizeMaxWidth { get; set; }

Property Value

Type	Description
int

ResizeQuality

Gets or sets the quality value used for client-side image resizing.

Declaration

public double ResizeQuality { get; set; }

Property Value

Type	Description
double

RetryDelay

Gets or sets the delay in milliseconds between upload retry attempts.

Declaration

public int RetryDelay { get; set; }

Property Value

Type	Description
int

ShowProgress

Gets or sets whether the built-in progress display is shown.

Declaration

public bool ShowProgress { get; set; }

Property Value

Type	Description
bool

ShowQueue

Gets or sets whether the built-in queue UI is shown.

Declaration

public bool ShowQueue { get; set; }

Property Value

Type	Description
bool

ShowThumbnails

Gets or sets whether thumbnail previews are shown for supported image files.

Declaration

public bool ShowThumbnails { get; set; }

Property Value

Type	Description
bool

Sortable

Gets or sets whether the queue can be reordered in the browser.

Declaration

public bool Sortable { get; set; }

Property Value

Type	Description
bool

UploadUrl

Gets or sets a custom upload endpoint. When left empty, the control chooses the standard AjaxUploader handler endpoints for normal, multiple, or chunked uploads.

Declaration

public string UploadUrl { get; set; }

Property Value

Type	Description
string

UploadedFileGuids

Gets the GUIDs of uploaded files after postback. The list reflects the hidden field maintained by the client uploader during the previous request.

Declaration

[Browsable(false)]
public List<Guid> UploadedFileGuids { get; }

Property Value

Type	Description
List<Guid>

ValidateMimeByMagic

Gets or sets whether MIME types should be validated using file signatures where possible.

Declaration

public bool ValidateMimeByMagic { get; set; }

Property Value

Type	Description
bool

WebkitDirectory

Gets or sets a value indicating whether the browse dialog selects a whole DIRECTORY instead of files (the HTML webkitdirectory mode). Every file in the chosen folder uploads with its relative path preserved - surfaced as RelativePath. Folder drag-and-drop works regardless of this setting.

Declaration

public bool WebkitDirectory { get; set; }

Property Value

Type	Description
bool

WithCredentials

Gets or sets whether the browser should include credentials on upload requests. Use this when the upload endpoint depends on authenticated cookies.

Declaration

public bool WithCredentials { get; set; }

Property Value

Type	Description
bool

Methods

GetClientElementBindings()

Returns engine option name -> client element ID pairs to bind the uploader to elements the page renders itself, or null for none. Values are emitted as CSS id selectors.

Declaration

protected virtual IDictionary<string, string> GetClientElementBindings()

Returns

Type	Description
IDictionary<string, string>

GetClientStringOverrides()

Returns per-instance client string overrides to merge into the engine's strings option, or null for none.

Declaration

protected virtual IDictionary<string, string> GetClientStringOverrides()

Returns

Type	Description
IDictionary<string, string>

Remarks

The modern control has no per-control message properties, so this returns nothing; the legacy CuteWebUI controls override it to forward their v4 message properties.

LoadPostData(string, NameValueCollection)

Loads the hidden uploaded-file GUID list from postback data. This restores the GUIDs written by the client uploader into the control's hidden field.

Declaration

public virtual bool LoadPostData(string postDataKey, NameValueCollection postCollection)

Parameters

Type	Name	Description
string	postDataKey
NameValueCollection	postCollection

Returns

Type	Description
bool

OnPreRender(EventArgs)

Raises the PreRender event.

Declaration

protected override void OnPreRender(EventArgs e)

Parameters

Type	Name	Description
EventArgs	e	An EventArgs object that contains the event data.

Overrides

Control.OnPreRender(EventArgs)

RaisePostDataChangedEvent()

Raises the post-data changed notifications and upload events for files loaded during postback. For each restored GUID, the control reloads file metadata and fires validation, file, and batch-complete events.

Declaration

public virtual void RaisePostDataChangedEvent()

Render(HtmlTextWriter)

Renders the control to the specified HTML writer.

Declaration

protected override void Render(HtmlTextWriter writer)

Parameters

Type	Name	Description
HtmlTextWriter	writer	The HtmlTextWriter object that receives the control content.

Overrides

WebControl.Render(HtmlTextWriter)

Events

FileUploaded

Occurs after a file upload has completed and file metadata has been loaded on postback.

Declaration

public event EventHandler<FileUploadedEventArgs> FileUploaded

Event Type

Type	Description
EventHandler<FileUploadedEventArgs>

FileValidating

Occurs when uploaded file metadata is being validated on the server.

Declaration

public event EventHandler<FileValidatingEventArgs> FileValidating

Event Type

Type	Description
EventHandler<FileValidatingEventArgs>

UploadCompleted

Occurs after all uploaded file GUIDs have been processed during postback.

Declaration

public event EventHandler UploadCompleted

Event Type

Type	Description
EventHandler

Implements

IComponent

IDisposable

IParserAccessor

IUrlResolutionService

IDataBindingsAccessor

IControlBuilderAccessor

IControlDesignerAccessor

IExpressionsAccessor

IAttributeAccessor

IPostBackDataHandler