Canducci.FileUpload 1.0.0

Canducci.FileUpload

A file upload library for ASP.NET Core with validation, flexible configuration, and support for synchronous and asynchronous operations.

Portugues: README_PTBR.md

Installation

Package Manager

Install-Package Canducci.FileUpload

.NET CLI

dotnet add package Canducci.FileUpload

PackageReference

<PackageReference Include="Canducci.FileUpload" Version="1.0.0" />

Configuration

Program.cs

Add the service in Program.cs:

using Canducci.FileUpload.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add FileUpload with default configuration (random filename)
builder.Services.AddFileUpload();

// OR with custom configuration (GUID filename)
builder.Services.AddFileUpload(config =>
{
    config.FileUploadConfigurationName = FileUploadConfigurationName.Guid;
});

var app = builder.Build();

Configuration Options

Controller Usage

Basic Example

using Canducci.FileUpload;
using Canducci.FileUpload.Interfaces;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class UploadController : ControllerBase
{
    [HttpPost]
    public IActionResult Upload(FileUpload fileUpload)
    {
        var result = fileUpload.Save("uploads", options =>
        {
            options.MaxFileSizeBytes = 5 * 1024 * 1024; // 5 MB
            options.RejectEmptyFiles = true;
            options.AllowedExtensions.Add(".jpg");
            options.AllowedExtensions.Add(".png");
            options.AllowedExtensions.Add(".pdf");
        });

        if (result.Success)
        {
            return Ok(new
            {
                Message = "Upload successful!",
                Files = result.Files.Select(f => new
                {
                    f.FileNameSent,
                    f.FileNameSave,
                    f.Extension,
                    f.Length,
                    f.Path
                })
            });
        }

        return BadRequest(new
        {
            Message = "Upload failed",
            Errors = result.Files
                .Where(f => !f.Success)
                .Select(f => new
                {
                    f.FileNameSent,
                    Error = f.Exception?.Message
                })
        });
    }
}

Async Example

[HttpPost("async")]
public async Task<IActionResult> UploadAsync(FileUpload fileUpload, CancellationToken cancellationToken)
{
    var result = await fileUpload.SaveAsync("uploads", options =>
    {
        options.MaxFileSizeBytes = 10 * 1024 * 1024; // 10 MB
        options.RejectEmptyFiles = true;
    }, cancellationToken);

    if (result.Success)
    {
        return Ok(new { Message = "Async upload completed!" });
    }

    return BadRequest(new { Message = "Upload failed" });
}

Multiple Files Example

[HttpPost("multiple")]
public IActionResult UploadMultiple(FileUpload fileUpload)
{
    if (fileUpload.Count == 0)
    {
        return BadRequest("No files uploaded");
    }

    var result = fileUpload.Save("documents", options =>
    {
        options.MaxFileSizeBytes = 20 * 1024 * 1024; // 20 MB
        options.AllowedExtensions.Add(".docx");
        options.AllowedExtensions.Add(".xlsx");
        options.AllowedExtensions.Add(".pdf");
    });

    var successFiles = result.Files.Where(f => f.Success).ToList();
    var failedFiles = result.Files.Where(f => !f.Success).ToList();

    return Ok(new
    {
        TotalUploaded = fileUpload.Count,
        Succeeded = successFiles.Count,
        Failed = failedFiles.Count,
        Files = successFiles.Select(f => f.FileNameSave),
        Errors = failedFiles.Select(f => new { f.FileNameSent, Error = f.Exception?.Message })
    });
}

Predefined Options Example

[HttpPost("images")]
public IActionResult UploadImages(FileUpload fileUpload)
{
    var options = new FileUploadOptions
    {
        MaxFileSizeBytes = 2 * 1024 * 1024, // 2 MB
        RejectEmptyFiles = true
    };
    options.AllowedExtensions.Add(".jpg");
    options.AllowedExtensions.Add(".jpeg");
    options.AllowedExtensions.Add(".png");
    options.AllowedExtensions.Add(".gif");
    options.AllowedExtensions.Add(".webp");

    var result = fileUpload.Save("images", options);

    return result.Success 
        ? Ok(result.Files.Select(f => f.Path)) 
        : BadRequest("Failed to save images");
}

Validation Options

Result Properties

IFileUploadResult

IFileItemResult

Error Messages

Complete Controller Example

using Canducci.FileUpload;
using Canducci.FileUpload.Interfaces;
using Microsoft.AspNetCore.Mvc;

namespace MyApp.Controllers;

[ApiController]
[Route("api/[controller]")]
public class FilesController : ControllerBase
{
    [HttpPost("upload")]
    [RequestSizeLimit(50 * 1024 * 1024)] // 50 MB request limit
    public async Task<IActionResult> Upload(
        FileUpload fileUpload,
        CancellationToken cancellationToken)
    {
        if (fileUpload.Count == 0)
        {
            return BadRequest(new { Error = "No files uploaded" });
        }

        var result = await fileUpload.SaveAsync("uploads", options =>
        {
            options.MaxFileSizeBytes = 10 * 1024 * 1024;
            options.RejectEmptyFiles = true;
            options.AllowedExtensions.Add(".jpg");
            options.AllowedExtensions.Add(".jpeg");
            options.AllowedExtensions.Add(".png");
            options.AllowedExtensions.Add(".pdf");
            options.AllowedExtensions.Add(".docx");
        }, cancellationToken);

        if (result.Success)
        {
            return Ok(new
            {
                Message = "Upload completed successfully",
                Files = result.Files.Select(f => new
                {
                    Original = f.FileNameSent,
                    Saved = f.FileNameSave,
                    Size = f.Length,
                    FullPath = f.Path
                })
            });
        }

        var errors = result.Files
            .Where(f => !f.Success)
            .Select(f => new
            {
                File = f.FileNameSent,
                Error = f.Exception?.Message ?? "Unknown error"
            });

        return BadRequest(new
        {
            Message = "Some files failed to upload",
            Errors = errors
        });
    }
}

Requirements

• .NET 8.0 or later
• ASP.NET Core

License

MIT License