New to Telerik UI for BlazorStart a free 30-day trial

Upload Events

This article describes the events of the Telerik Upload for Blazor.

First, get familiar with the Event Arguments section, as it applies to all events. The example at the end also showcases all Upload events.

Make sure to also check the section about Upload security.

The event is an EventCallback. It can be synchronous and return void, or asynchronous and return async Task. Do not use async void.

Event Arguments

The different Upload events use different event argument types, but the exposed properties are similar. Depending on the exact event, the properties will be some of these:

PropertyTypeDescription
FilesList<UploadFileInfo>All Upload events expose a Files collection of UploadFileInfo members. The collection contains one or more files in the OnClear, OnSelect, and OnUpload handlers. The file is always one in OnCancel, OnError, OnProgress, OnRemove, and OnSuccess.
IsCancelledboolSet to true to cancel the event and the respective user action.
OperationUploadOperationType enumCan be Upload or Remove.
ProgressintThe uploaded percentage of the file in the OnProgress event.
RequestUploadHttpRequestInformation about the server response such as status code and any custom messages. The object contains the int property Status and the StatusText, ResponseType, and ResponseText strings.
RequestDataDictionary<string, object>Add KeyValuePair definitions to send custom data to the controller in OnUpload and OnRemove.
RequestHeadersDictionary<string, object>Add KeyValuePair definitions to send custom HTTP headers to the controller in OnUpload and OnRemove.

The custom information in RequestData and RequestHeaders can be related to authentication, CSRF cross-site anti forgery tokens, or any business logic.

UploadFileInfo

The UploadFileInfo object has the following properties:

PropertyTypeDescription
ExtensionstringThe file extension (type), together with the dot.
IdstringThe unique file identifier in GUID format.
InvalidExtensionboolDefines if the file violates the AllowedExtensions value.
InvalidMaxFileSizeboolDefines if the file violates the MaxFileSize value.
InvalidMinFileSizeboolDefines if the file violates the MinFileSize value.
NamestringThe encoded file name, including the extension. One method to decode it is System.Net.WebUtility.HtmlDecode(). The file name received by the controller (endpoint) is not encoded. The file can be renamed in the OnSelect and OnUpload handlers.
ProgressintThe uploaded percentage of the file in the OnProgress event.
SizelongThe file size in bytes.
StatusUploadFileStatus enumThe current status of the file in the context of the Upload component (Selected, Uploading, Uploaded, Failed).

OnCancel

The OnCancel event fires when the user clicks the Cancel icon of a file that is currently uploading.

The UploadCancelEventArgs event argument contains the properties Files and IsCancelled. The Files property contains only one file.

If you cancel the event, the upload process will continue. For example, this can depend on some file information such as size and upload progress.

Using the Upload OnCancel event

RAZOR
<TelerikUpload OnCancel="@OnUploadCancel" />

@code {
    private void OnUploadCancel(UploadCancelEventArgs args)
    {
        var file = args.Files.First();

        if (file.Size < 2 * 1024 * 1024 && file.Progress > 50)
        {
            args.IsCancelled = true;
        }
    }
}

See the full example below.

OnClear

The OnClear event fires when the user clicks the Clear button below the file list. This button is visible when AutoUpload="false".

The UploadClearEventArgs event argument contains the properties Files and IsCancelled. The Files property can contain one or more files.

If you cancel the event, the current file list will remain visible.

Using the Upload OnClear event

RAZOR
<TelerikUpload OnClear="@OnUploadClear" />

@code {
    private void OnUploadClear(UploadClearEventArgs args)
    {
        if (args.Files.Count > 3)
        {
            args.IsCancelled = true;
        }
    }
}

See the full example below.

OnError

The OnError event fires when an upload or remove request fails in the controller.

The UploadErrorEventArgs event argument contains the following properties:

  • Files that contains one file
  • Operation
  • Request

Using the OnError event with message from the controller

RAZOR
<TelerikUpload OnError="@OnUploadError" />

@code {
    private void OnUploadError(UploadErrorEventArgs args)
    {
        string fileName = args.Files.First().Name;
        UploadOperationType operation = args.Operation;
        int statusCode = args.Request.Status;
        string statusMessage = args.Request.StatusText;
        string customMessage = args.Request.ResponseText;
    }
}

See the full example below.

OnProgress

The OnProgress event fires each time a file makes progress in its upload process.

The event is tied directly to the progress event of the XHR object, which sends the file to the controller. The Upload component cannot control when or how often the event will fire. For small files, the Progress value is likely to jump directly to 100, especially on localhost.

The UploadProgressEventArgs event argument contains the properties Files and Progress. The Files property contains only one file.

Using the Upload OnProgress event

RAZOR
<TelerikUpload OnProgress="@OnUploadProgress" />

@code {
    private void OnUploadProgress(UploadProgressEventArgs args)
    {
        string fileName = args.Files.First().Name;
        int percentComplete = args.Progress;
    }
}

See the full example below.

OnRemove

The OnRemove event fires when the users clicks the Remove (X) button of an uploaded or pending file. If the file is already uploaded, the Upload component will send a request to the server, so you can delete it. Then, the component will fire OnSuccess or OnError.

The UploadEventArgs event argument contains the following properties:

If you cancel the event, the Upload component will not send the file deletion request.

Using the OnRemove event to send custom data to the controller

RAZOR
<TelerikUpload OnRemove="@OnUploadRemove" />

@code {
    private async Task OnUploadRemove(UploadEventArgs args)
    {
        var file = args.Files.First();

        if (file.Extension == ".pdf")
        {
            args.IsCancelled = true;
        }
        else
        {
            args.RequestData.Add("dataKey", "dataValue");
            args.RequestHeaders.Add("headerKey", "headerValue");
        }
    }
}

See the full example below.

OnSelect

The OnSelect event fires when the user selects one or more new files for upload. The selection of files is achieved either through the Select files button or by dropping the files anywhere in the component.

The UploadSelectEventArgs event argument contains the Files and IsCancelled properties. The Files property can contain one or more files, and it is possible to count the total number of selected files.

If you cancel the event, the Upload component will neither list, nor upload the selected files.

Renaming a File

In some cases, you may want to rename a selected file when uploading it, for example:

  • A file with the same name already exists on the server.
  • The file name does not meet some requirements.

The file rename process requires two separate steps:

  1. Use the OnSelect event to call a remote endpoint and check for duplicates before the actual upload process starts. If needed, set a new name to the Name property of the file. This new name will appear in the Upload component UI. The controller will always receive IFormFile with the original name from the file system, due to browser security restrictions.
  2. Send the new file name(s) as additional request data in the OnUpload and OnRemove events. Keep in mind that OnUpload can fire once for multiple files, so you may have to send multiple file names to the remote endpoint. Use multiple custom key-value pairs or a single serialized Dictionary. Then, use the Save action in the remote endpoint to set the name(s) of the saved file(s).

Using the Upload OnSelect event to rename files in the UI

RAZOR
<TelerikUpload OnSelect="@OnUploadSelect" />

@code {
    private async Task OnUploadSelect(UploadSelectEventArgs args)
    {
        foreach (var file in args.Files)
        {
            string fileName = file.Name;
            long fileSize = file.Size;

            // Change the file name that is displayed in the TelerikUpload component.
            // Delays here will result in rendering and upload delays.
            // The IFormFile file name in the upload request will remain the original one.
            file.Name = await GetNewFileNameFromServer(file.Name, "currentUserName");
        }
    }

    private async Task<string> GetNewFileNameFromServer(string fileName, string userName)
    {
        await Task.Delay(100); // simulate network delay

        // In a real case this can be a controller action method.
        // Use the same naming logic when actually saving the file on the server.
        string newFileName = $"{userName}-{fileName}";

        return await Task.FromResult(newFileName);
    }
}

See the full example below.

OnSuccess

The OnSuccess event fires when an upload or remove request is successful. The Upload assumes a successful request if the Response.StatusCode of the controller action is between 200 and 299.

The UploadSuccessEventArgs event argument contains the following properties:

For example, the server can return a URL string for an image thumbnail.

Using the OnSuccess event with message from the controller

RAZOR
<TelerikUpload OnSuccess="@OnUploadSuccess" />

@code {
    private async Task OnUploadSuccess(UploadSuccessEventArgs args)
    {
        string fileName = args.Files.First().Name;
        UploadOperationType operation = args.Operation;
        int statusCode = args.Request.Status;
        string statusMessage = args.Request.StatusText;
        string customMessage = args.Request.ResponseText;
    }
}

See the full example below.

OnUpload

The OnUpload event fires when files will be uploaded. By default, it will fire immediately after OnSelect, unless AutoUpload="false".

The UploadEventArgs event argument contains the following properties:

  • Files that contains one or more files
  • IsCancelled
  • RequestData
  • RequestHeaders

If you cancel the event, the file upload will not start. If AutoUpload="false", the user will be able to try uploading the same file(s) again.

Send Custom Data with the File

Use the OnUpload and OnRemove event handlers to send additional custom data and request headers to the server, together with the file. For example, the data may be related to:

To send cookies with the upload request, set the WithCredentials component parameter to true.

To send a complex object or a collection, serialize it first. Receive it as a string argument in the controller method and deserialize it.

Using the OnUpload event to send custom data to the controller

RAZOR
@using System.Text.Json

<TelerikUpload OnUpload="@OnUploadHandler" />

@code {
    private async Task OnUploadHandler(UploadEventArgs args)
    {
        if (args.Files.Count > 3)
        {
            args.IsCancelled = true;
        }

        string[] collection = { "foo", "bar", "baz" };

        args.RequestHeaders.Add("headerKey", "headerValue"); // for example, token
        args.RequestData.Add("dataKey", "dataValue"); // for example, new file name
        args.RequestData.Add("collectionKey", JsonSerializer.Serialize(collection));
    }
}

Example

The UploadController class below assumes that the project name and namespace is TelerikBlazorUpload.

Make sure to enable controller routing in the app startup file (Program.cs). In this case, app.MapDefaultControllerRoute(); is all that's needed.

Also see:

Using the Upload events

RAZOR
@inject NavigationManager NavigationManager

<label>
    <TelerikCheckBox @bind-Value="@AllowRequests" />
    Allow Upload and Remove Requests
</label> (otherwise cancel events)

<TelerikRadioGroup Data="@RadioGroupData"
                   @bind-Value="@ReturnSuccess"
                   TextField="@nameof(RadioGroupModel.Text)"
                   ValueField="@nameof(RadioGroupModel.Value)"
                   Layout="@RadioGroupLayout.Horizontal" />

<TelerikUpload SaveUrl="@UploadSaveUrl"
               RemoveUrl="@UploadRemoveUrl"
               MaxFileSize="@( 16 * 1024 * 1024 )"
               MinFileSize="@( 1 * 1024 )"
               AutoUpload="true"
               OnCancel="@OnUploadCancel"
               OnClear="@OnUploadClear"
               OnError="@OnUploadError"
               OnProgress="@OnUploadProgress"
               OnRemove="@OnUploadRemove"
               OnSelect="@OnUploadSelect"
               OnSuccess="@OnUploadSuccess"
               OnUpload="@OnUploadUpload">
</TelerikUpload>

@code {
    private bool AllowRequests { get; set; } = true;

    private bool ReturnSuccess { get; set; } = true;

    private string UploadSaveUrl => ToAbsoluteUrl("api/upload/save");

    private string UploadRemoveUrl => ToAbsoluteUrl("api/upload/remove");

    private void OnUploadCancel(UploadCancelEventArgs args)
    {
        var file = args.Files.First();

        if (file.Size < 2 * 1024 * 1024 && file.Progress > 50)
        {
            args.IsCancelled = true;
            Console.WriteLine($"OnCancel event cancelled.");
        }
        else
        {
            Console.WriteLine($"OnCancel event for {file.Name}");
        }
    }

    private void OnUploadClear(UploadClearEventArgs args)
    {
        if (args.Files.Count > 3)
        {
            args.IsCancelled = true;
            Console.WriteLine("OnClear event cancelled.");
        }
        else
        {
            Console.WriteLine("OnClear event fired for:");

            foreach (var file in args.Files)
            {
                Console.WriteLine($"  Name: {file.Name}, Size: {file.Size} bytes");
            }
        }
    }

    private void OnUploadError(UploadErrorEventArgs args)
    {
        Console.WriteLine($"OnError event for:");
        Console.WriteLine($"  File: {args.Files.First().Name}");
        Console.WriteLine($"  Operation: {args.Operation}");
        Console.WriteLine($"  Response Status Code: {args.Request.Status}");
        Console.WriteLine($"  Response Status Message: {args.Request.StatusText}");
        Console.WriteLine($"  Response Type: {args.Request.ResponseType}");
        Console.WriteLine($"  Response Text: {args.Request.ResponseText}");
    }

    private void OnUploadProgress(UploadProgressEventArgs args)
    {
        Console.WriteLine($"OnProgress event for:");
        Console.WriteLine($"  File: {args.Files.First().Name}");
        Console.WriteLine($"  Progress: {args.Progress}");
    }

    private async Task OnUploadRemove(UploadEventArgs args)
    {
        var file = args.Files.First();

        if (!AllowRequests)
        {
            args.IsCancelled = true;
            Console.WriteLine($"OnRemove event cancelled for {file.Name}");
        }
        else
        {
            Console.WriteLine($"OnRemove event for {file.Name}");

            args.RequestData.Add("successData", ReturnSuccess);
            args.RequestHeaders.Add("successHeader", ReturnSuccess);
        }
    }

    private async Task OnUploadSelect(UploadSelectEventArgs args)
    {
        Console.WriteLine("OnSelect event for:");

        foreach (var file in args.Files)
        {
            Console.WriteLine($"  File: {file.Name}, Size: {file.Size} bytes");
        }

        if (args.Files.Count > 5)
        {
            args.IsCancelled = true;
            Console.WriteLine("OnSelect event cancelled.");
        }
    }

    private void OnUploadSuccess(UploadSuccessEventArgs args)
    {
        Console.WriteLine($"OnSuccess event for:");
        Console.WriteLine($"  File: {args.Files.First().Name}");
        Console.WriteLine($"  Operation: {args.Operation}");
        Console.WriteLine($"  Response Status Code: {args.Request.Status}");
        Console.WriteLine($"  Response Status Message: {args.Request.StatusText}");
        Console.WriteLine($"  Response Type: {args.Request.ResponseType}");
        Console.WriteLine($"  Response Text: {args.Request.ResponseText}");
    }

    private async Task OnUploadUpload(UploadEventArgs args)
    {
        if (!args.Files.Any())
        {
            return;
        }

        if (!AllowRequests)
        {
            args.IsCancelled = true;
            Console.WriteLine($"OnUpload event cancelled for:");
        }
        else
        {
            args.RequestData.Add("successData", ReturnSuccess);
            args.RequestHeaders.Add("successHeader", ReturnSuccess);
            Console.WriteLine($"OnUpload event for:");
        }

        foreach (var file in args.Files)
        {
            Console.WriteLine($"  File: {file.Name}");
        }
    }

    private string ToAbsoluteUrl(string url)
    {
        return $"{NavigationManager.BaseUri}{url}";
    }

    private List<RadioGroupModel> RadioGroupData { get; set; } = new List<RadioGroupModel>()
    {
        new RadioGroupModel() { Value = true, Text = "Expect Request Success" },
        new RadioGroupModel() { Value = false, Text = "Expect Request Failure" }
    };

    public class RadioGroupModel
    {
        public bool Value { get; set; }
        public string Text { get; set; } = string.Empty;
    }
}

The event is an EventCallback. It can be synchronous and return void, or asynchronous and return async Task. Do not use async void.

See Also