SaMirzaei.DevTools.Base64 0.1.0-alpha.2

Tools.Base64

A small, dependency-light .NET library for encoding, decoding, and validating Base64 data with an extensible MIME type detection system built on the Strategy pattern.

Features

• Encode plain text as Base64.
• Decode Base64 back into UTF-8 text, or preserve it for binary/file-oriented workflows.
• Validate Base64 input and get structured metadata:
  • Valid/invalid state
  • Decoded size in bytes
  • Heuristic MIME type detection for common file signatures
• Extensible MIME detection via the Strategy pattern (IMimeTypeDetector).
• Whitespace-tolerant decoding and validation: spaces and line breaks are ignored.
• File-aware requests and responses with optional filename, MIME type, and file size metadata.
• No heavy dependencies — built on the .NET base class library.

Architecture

MIME type detection uses the Strategy pattern, allowing consumers to add custom detectors without modifying existing code.

classDiagram
    class IMimeTypeDetector {
        <<interface>>
        +int Order
        +string Detect(string base64String)
    }

    class DefaultMimeTypeDetector {
        +int Order = 0
        +string Detect(string base64String)
    }

    class RiffMimeTypeDetector {
        +int Order = 10
        +string Detect(string base64String)
    }

    class Base64Service {
        -IEnumerable~IMimeTypeDetector~ _detectors
        +Encode(Base64EncodeRequest) Base64Response
        +Decode(Base64DecodeRequest) Base64Response
        +Validate(Base64ValidateRequest) Base64ValidateResponse
    }

    Base64Service --> IMimeTypeDetector : iterates ordered detectors
    DefaultMimeTypeDetector ..|> IMimeTypeDetector
    RiffMimeTypeDetector ..|> IMimeTypeDetector

Detection flow:

flowchart LR
    A[Base64 input] --> B{Detector Order 0}
    B -->|match| C[Return MIME type]
    B -->|no match| D{Detector Order 10}
    D -->|match| C
    D -->|no match| E{Next detector...}
    E -->|no match| F["application/octet-stream"]

Detectors are evaluated in ascending Order. The first non-empty result wins.

Installation

Add a project reference to the library:

dotnet add reference ../Tools.Base64/Tools.Base64.csproj

Or include it in your solution and reference it from your project.

Usage

Dependency injection (recommended)

using Microsoft.Extensions.DependencyInjection;
using Tools.Base64;

var services = new ServiceCollection();
services.AddBase64Tools();

This registers the built-in detectors (DefaultMimeTypeDetector, RiffMimeTypeDetector) and Base64Service.

Encoding text

using Tools.Base64.Abstractions;
using Tools.Base64.Models;

// Resolve from DI
IBase64Service service = provider.GetRequiredService<IBase64Service>();

var response = service.Encode(new Base64EncodeRequest
{
    Input = "Hello, Base64!"
});

if (response.Success)
    Console.WriteLine(response.Output);

Decoding Base64

var response = service.Decode(new Base64DecodeRequest
{
    Input = "SGVsbG8sIEJhc2U2NCE=",
    OutputAsFile = false
});

if (response.Success && response.IsTextOutput)
    Console.WriteLine(response.Output);
else if (response.Success)
    Console.WriteLine($"Binary content detected: {response.MimeType} ({response.FileSize} bytes)");

Validating Base64

var validation = service.Validate(new Base64ValidateRequest
{
    Input = "SGVsbG8sIEJhc2U2NCE="
});

if (validation.IsValid)
{
    Console.WriteLine($"Decoded size: {validation.DecodedSize} bytes");
    Console.WriteLine($"Estimated MIME type: {validation.EstimatedMimeType}");
}

Adding a custom MIME type detector

Implement IMimeTypeDetector and register it:

using Tools.Base64.Abstractions;

public class FontMimeTypeDetector : IMimeTypeDetector
{
    public int Order => 5; // Runs between default (0) and RIFF (10)

    public string Detect(string base64String)
    {
        if (string.IsNullOrEmpty(base64String) || base64String.Length < 8)
            return string.Empty;

        var prefix = base64String.Substring(0, Math.Min(12, base64String.Length));

        if (prefix.StartsWith("d09GRgAB"))
            return "font/woff2";

        return string.Empty; // Not recognized — pass to next detector
    }
}

Register alongside the built-in detectors:

services.AddBase64Tools();
services.AddSingleton<IMimeTypeDetector, FontMimeTypeDetector>();

Convention: Return string.Empty when your detector does not recognize the input. The service treats any non-empty result as a match and stops the chain.

API

IMimeTypeDetector

IBase64Service

Request model — Base64EncodeRequest

Request model — Base64DecodeRequest

Response model — Base64Response

Request model — Base64ValidateRequest

Validate response — Base64ValidateResponse

Built-in MIME type detectors

If no detector matches, the fallback MIME type is application/octet-stream.

Target framework

• netstandard2.1 — usable from .NET Core 3.x, .NET 5+, and Xamarin/Mono.

Testing

Run the dedicated test project:

dotnet test tests/Tools.Base64.Tests/Tools.Base64.Tests.csproj

License

Licensed under the MIT License.