Canducci.FileUpload 1.0.0.4

Canducci.FileUpload

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

Portuguese: README_PTBR.md

Version 1.0.0.4 (stable version)

What's New

• FileUploadStatus enum: Replaces the ambiguous Success boolean property with a clear status indicator
  • AllSucceeded - All files were uploaded successfully
  • PartialSuccess - Some files succeeded, some failed
  • AllFailed - All files failed to upload
  • Empty - No files were provided
• SuccessCount property: Returns the count of successfully uploaded files
• FailureCount property: Returns the count of failed uploads
• Complete XML documentation in English for all public APIs
• FileUploadValidationAttribute: Integration with ASP.NET Core Data Annotations
• Multiple FileUploadOptions constructors: Different ways to initialize with various constraints
• Case-insensitive extension validation: Safe extension comparison
• .NET 8, 9, and 10 support: Compatibility with multiple .NET versions
• 91 comprehensive unit tests: Complete test coverage for reliability

Installation

Package Manager

Install-Package Canducci.FileUpload

.NET CLI

dotnet add package Canducci.FileUpload

PackageReference

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

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.Enuns;
using Canducci.FileUpload.Interfaces;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class UploadController : ControllerBase
{
    [HttpPost]
    public IActionResult Upload(IFileUpload 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");
        });

        switch (result.Status)
        {
            case FileUploadStatus.AllSucceeded:
                return Ok(new
                {
                    Message = "Upload successful!",
                    SuccessCount = result.SuccessCount,
                    Files = result.Files.Select(f => new
                    {
                        f.FileNameSent,
                        f.FileNameSave,
                        f.Extension,
                        f.Length,
                        f.Path
                    })
                });

            case FileUploadStatus.PartialSuccess:
                return Ok(new
                {
                    Message = "Some files uploaded successfully",
                    SuccessCount = result.SuccessCount,
                    FailureCount = result.FailureCount,
                    Files = result.Files.Where(f => f.Success).Select(f => f.FileNameSave),
                    Errors = result.Files.Where(f => !f.Success).Select(f => new
                    {
                        f.FileNameSent,
                        Error = f.Exception?.Message
                    })
                });

            case FileUploadStatus.AllFailed:
                return BadRequest(new
                {
                    Message = "All files failed to upload",
                    FailureCount = result.FailureCount,
                    Errors = result.Files.Select(f => new
                    {
                        f.FileNameSent,
                        Error = f.Exception?.Message
                    })
                });

            case FileUploadStatus.Empty:
            default:
                return BadRequest(new { Message = "No files provided" });
        }
    }
}

Async Example

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

    if (result.Status == FileUploadStatus.AllSucceeded)
    {
        return Ok(new { Message = "Async upload completed!", result.SuccessCount });
    }

    return BadRequest(new { Message = "Upload failed", result.FailureCount });
}

Multiple Files Example

[HttpPost("multiple")]
public IActionResult UploadMultiple(IFileUpload 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");
    });

    return Ok(new
    {
        Status = result.Status.ToString(),
        TotalUploaded = fileUpload.Count,
        Succeeded = result.SuccessCount,
        Failed = result.FailureCount,
        Files = result.Files.Where(f => f.Success).Select(f => f.FileNameSave),
        Errors = result.Files.Where(f => !f.Success).Select(f => new { f.FileNameSent, Error = f.Exception?.Message })
    });
}

Predefined Options Example

[HttpPost("images")]
public IActionResult UploadImages(IFileUpload fileUpload)
{
    // Parameterized constructor with multiple extensions
    var options = new FileUploadOptions(2 * 1024 * 1024, true, ".jpg", ".jpeg", ".png", ".gif", ".webp");

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

    return result.Status == FileUploadStatus.AllSucceeded
        ? Ok(result.Files.Select(f => f.Path)) 
        : BadRequest($"Failed: {result.FailureCount} of {fileUpload.Count} images");
}

Fluent API Example

[HttpPost("fluent")]
public IActionResult UploadFluent(IFileUpload fileUpload)
{
    var options = new FileUploadOptions();
    options.AllowedExtensions
        .AddImages()      // All 10 image extensions
        .AddDocuments()   // All 10 document extensions
        .AddArchives();   // All 5 archive extensions

    var result = fileUpload.Save("uploads", options);
    return Ok(result);
}

Data Annotations Example

using System.ComponentModel.DataAnnotations;
using Canducci.FileUpload.Attributes;

public class FileUploadModel
{
    [FileUploadValidation(
        MaxFileSizeBytes = 5242880, 
        RejectEmptyFiles = true,
        AllowedExtensions = new[] { ".pdf", ".docx", ".xlsx" }
    )]
    public IFileUpload Files { get; set; }
}

[HttpPost("validated")]
public IActionResult ValidatedUpload(FileUploadModel model)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }

    var result = model.Files.Save("documents");
    return Ok(result);
}

Validation Options

FileUploadOptions Constructors

// Default constructor with default values
var options1 = new FileUploadOptions();

// Constructor with max size and empty file rejection
var options2 = new FileUploadOptions(5_000_000, false);

// Constructor with all constraints
var options3 = new FileUploadOptions(2_000_000, true, ".pdf", ".docx", ".xlsx");

Result Properties

IFileUploadResult

FileUploadStatus Enum

IFileItemResult

Error Messages

Complete Controller Example

using Canducci.FileUpload;
using Canducci.FileUpload.Enuns;
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(
        IFileUpload fileUpload,
        CancellationToken cancellationToken)
    {
        if (fileUpload.Count == 0)
        {
            return BadRequest(new { Error = "No files uploaded" });
        }

        // Using parameterized constructor
        var options = new FileUploadOptions(
            maxFileSizeBytes: 10 * 1024 * 1024,
            rejectEmptyFiles: true,
            allowedExtensions: ".jpg", ".jpeg", ".png", ".pdf", ".docx");

        var result = await fileUpload.SaveAsync("uploads", options, cancellationToken);

        return result.Status switch
        {
            FileUploadStatus.AllSucceeded => Ok(new
            {
                Message = "All files saved successfully",
                Count = result.SuccessCount,
                Files = result.Files.Select(f => new { f.FileNameSave, f.Path })
            }),
            FileUploadStatus.PartialSuccess => Ok(new
            {
                Message = "Some files were saved",
                Succeeded = result.SuccessCount,
                Failed = result.FailureCount
            }),
            FileUploadStatus.AllFailed => BadRequest(new
            {
                Message = "Failed to save all files",
                Errors = result.Files.Select(f => f.Exception?.Message)
            }),
            _ => BadRequest(new { Error = "No files provided" })
        };
    }

    [HttpPost("images")]
    public IActionResult UploadImages(IFileUpload fileUpload)
    {
        var options = new FileUploadOptions();
        options.AllowedExtensions.AddImages(); // All image extensions

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

        return result.Status == FileUploadStatus.AllSucceeded
            ? Ok(result.Files)
            : BadRequest(result.Files.Where(f => !f.Success));
    }

    [HttpPost("documents")]
    public IActionResult UploadDocuments(IFileUpload fileUpload)
    {
        var options = new FileUploadOptions(5 * 1024 * 1024, true);
        options.AllowedExtensions.AddDocuments(); // All document extensions

        var result = fileUpload.Save("documents", options);
        return Ok(result);
    }
}

Security Features

• Filename sanitization: Removes dangerous characters and handles path traversal
• Case-insensitive extension validation: Protects against case-based bypasses
• Overwrite prevention: Generates unique names using UUID or random
• Atomic save: Saves to temporary file first, then renames atomically
• CancellationToken support: Safely cancels long-running operations
• Granular error handling: Returns detailed status per file

Supported File Extensions

The library provides constants and fluent methods for common extensions:

Images (10 extensions)

.jpg, .jpeg, .png, .gif, .webp, .svg, .bmp, .tiff, .tif, .heic

Documents (10 extensions)

.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv, .odt

Archives (5 extensions)

.zip, .rar, .7z, .tar, .gz

Audio/Video (5 extensions)

.mp3, .wav, .mp4, .mkv, .avi

Library Highlights

Developed with focus on:

• ✅ Security: Rigorous validation and protection against common attacks
• ✅ Performance: Async operations and streaming for large files
• ✅ Usability: Simple and intuitive API with Fluent API support
• ✅ Documentation: Complete XML comments in English
• ✅ Testing: Comprehensive 91 unit test suite
• ✅ Compatibility: Supports .NET 8, 9, and 10

What's New

• FileUploadStatus enum: Replaces the ambiguous Success boolean property with a clear status indicator
  • AllSucceeded - All files were uploaded successfully
  • PartialSuccess - Some files succeeded, some failed
  • AllFailed - All files failed to upload
  • Empty - No files were provided
• SuccessCount property: Returns the count of successfully uploaded files
• FailureCount property: Returns the count of failed uploads
• Complete XML documentation in English for all public APIs

Installation

Package Manager

Install-Package Canducci.FileUpload

.NET CLI

dotnet add package Canducci.FileUpload

PackageReference

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

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.Enuns;
using Canducci.FileUpload.Interfaces;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class UploadController : ControllerBase
{
    [HttpPost]
    public IActionResult Upload(IFileUpload 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");
        });

        switch (result.Status)
        {
            case FileUploadStatus.AllSucceeded:
                return Ok(new
                {
                    Message = "Upload successful!",
                    SuccessCount = result.SuccessCount,
                    Files = result.Files.Select(f => new
                    {
                        f.FileNameSent,
                        f.FileNameSave,
                        f.Extension,
                        f.Length,
                        f.Path
                    })
                });

            case FileUploadStatus.PartialSuccess:
                return Ok(new
                {
                    Message = "Some files uploaded successfully",
                    SuccessCount = result.SuccessCount,
                    FailureCount = result.FailureCount,
                    Files = result.Files.Where(f => f.Success).Select(f => f.FileNameSave),
                    Errors = result.Files.Where(f => !f.Success).Select(f => new
                    {
                        f.FileNameSent,
                        Error = f.Exception?.Message
                    })
                });

            case FileUploadStatus.AllFailed:
                return BadRequest(new
                {
                    Message = "All files failed to upload",
                    FailureCount = result.FailureCount,
                    Errors = result.Files.Select(f => new
                    {
                        f.FileNameSent,
                        Error = f.Exception?.Message
                    })
                });

            case FileUploadStatus.Empty:
            default:
                return BadRequest(new { Message = "No files provided" });
        }
    }
}

Async Example

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

    if (result.Status == FileUploadStatus.AllSucceeded)
    {
        return Ok(new { Message = "Async upload completed!", result.SuccessCount });
    }

    return BadRequest(new { Message = "Upload failed", result.FailureCount });
}

Multiple Files Example

[HttpPost("multiple")]
public IActionResult UploadMultiple(IFileUpload 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");
    });

    return Ok(new
    {
        Status = result.Status.ToString(),
        TotalUploaded = fileUpload.Count,
        Succeeded = result.SuccessCount,
        Failed = result.FailureCount,
        Files = result.Files.Where(f => f.Success).Select(f => f.FileNameSave),
        Errors = result.Files.Where(f => !f.Success).Select(f => new { f.FileNameSent, Error = f.Exception?.Message })
    });
}

Predefined Options Example

[HttpPost("images")]
public IActionResult UploadImages(IFileUpload 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.Status == FileUploadStatus.AllSucceeded
        ? Ok(result.Files.Select(f => f.Path)) 
        : BadRequest($"Failed: {result.FailureCount} of {fileUpload.Count} images");
}

Validation Options

Result Properties

IFileUploadResult

FileUploadStatus Enum

IFileItemResult

Error Messages

Complete Controller Example

using Canducci.FileUpload;
using Canducci.FileUpload.Enuns;
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(
        IFileUpload 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);

        switch (result.Status)
        {
            case FileUploadStatus.AllSucceeded:
                return Ok(new
                {
                    Message = "Upload completed successfully",
                    SuccessCount = result.SuccessCount,
                    Files = result.Files.Select(f => new
                    {
                        Original = f.FileNameSent,
                        Saved = f.FileNameSave,
                        Size = f.Length,
                        FullPath = f.Path
                    })
                });

            case FileUploadStatus.PartialSuccess:
                return Ok(new
                {
                    Message = "Some files uploaded successfully",
                    SuccessCount = result.SuccessCount,
                    FailureCount = result.FailureCount,
                    SuccessfulFiles = result.Files.Where(f => f.Success).Select(f => f.FileNameSave),
                    Errors = result.Files.Where(f => !f.Success).Select(f => new
                    {
                        File = f.FileNameSent,
                        Error = f.Exception?.Message ?? "Unknown error"
                    })
                });

            case FileUploadStatus.AllFailed:
                return BadRequest(new
                {
                    Message = "All files failed to upload",
                    FailureCount = result.FailureCount,
                    Errors = result.Files.Select(f => new
                    {
                        File = f.FileNameSent,
                        Error = f.Exception?.Message ?? "Unknown error"
                    })
                });

            case FileUploadStatus.Empty:
            default:
                return BadRequest(new { Error = "No files provided" });
        }
    }
}

Example Projects

The Web example applications are located in the Web folder of the repository. Below are the sample projects with direct GitHub links and a short description of what each demonstrates.

• WebAppTest — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebAppTest

  • A complete sample application with UI (Razor Views) and controllers demonstrating synchronous and asynchronous upload endpoints, multiple file uploads, and the use of configuration and validation options. Use this project to see full integration in an ASP.NET Core application.

• WebFileUploadBasic — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebFileUploadBasic

  • A minimal project demonstrating basic configuration and upload flow that saves files to disk with randomly generated names.

• WebFilesUploadBasic — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebFilesUploadBasic

  • Demonstrates multiple file uploads and how to collect per-file results (success/failure). Useful to learn FileUploadResult and FileItemResult usage.

• WebFilesUploadBasicGuidNameGenerate — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebFilesUploadBasicGuidNameGenerate

  • Example that generates GUID-based filenames. Useful when avoiding collisions and maintaining unique, predictable filenames.

• WebFilesUploadBasicOnlyImages — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebFilesUploadBasicOnlyImages

  • Demonstrates configuring AllowedExtensions to accept only image types (e.g., .jpg, .png, .webp). Ideal for image-only upload scenarios.

• WebFilesUploadBasicOnlyImagensDataAnnotation — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebFilesUploadBasicOnlyImagensDataAnnotation

  • Same image-only scenario but demonstrating use of FileUploadValidationAttribute with Data Annotations on the model for automatic binding validation.

• Canducci.FileUpload.FluentValidation — https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/Canducci.FileUpload.FluentValidation

  • An extension project integrating the popular FluentValidation library (FluentValidation.AspNetCore) to validate IFileUpload/IFileItem using fluent validator classes. Use this project to see how to enforce validation rules with FluentValidation and integrate them into the ASP.NET Core pipeline.
  • Project Web - https://github.com/fulviocanducci/Canducci.FileUpload/tree/master/WebFilesUploadBasicOnlyImagesFluentValidation

Requirements

• .NET 8.0 or later
• ASP.NET Core

License

MIT License