Canducci.FileUpload 1.0.0.3

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.3 (stable version)

Version 1.0.0.2 (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" });
        }
    }
}

Requirements

• .NET 8.0 or later
• ASP.NET Core

License

MIT License