ComnetCaptcha 1.0.0

ComnetSolution.Captcha

A lightweight, cross-platform CAPTCHA image generator for .NET built on SkiaSharp.
Works on Linux Docker and Windows without any system font installation — the font is embedded in the package.

Features

• ✅ Cross-platform: Linux, Windows, macOS, Docker
• ✅ Embedded font — no system fonts required
• ✅ Ripple/wave distortion effect
• ✅ Randomised noise lines
• ✅ Fully configurable character set, image size, and code length
• ✅ Built-in Validate() helper (case-insensitive by default)
• ✅ ASP.NET Core DI extension (AddCaptcha)
• ✅ Returns Base64 / data URI helpers on the result object
• ✅ Targets .NET 10

Installation

dotnet add package ComnetSolution.Captcha

Or via the NuGet Package Manager:

Install-Package ComnetSolution.Captcha

Quick Start

Minimal (no DI)

using ComnetCaptcha;

// Generate with defaults (120×36 px, 4 chars)
CaptchaResult result = CaptchaGenerator.Generate();

// Send the PNG bytes to the client
return File(result.CaptchaByteData, "image/png");

In HTML as a data URI

CaptchaResult result = CaptchaGenerator.Generate();
string imgSrc = result.ToDataUri(); // "data:image/png;base64,..."

<img src="@imgSrc" alt="CAPTCHA" />

Validate user input

string stored = HttpContext.Session.GetString("captcha") ?? "";
string input  = Request.Form["captcha"];

bool valid = CaptchaGenerator.Validate(captchaToken, input); // case-insensitive

ASP.NET Core Integration

Program.cs / Startup

builder.Services.AddCaptcha(options =>
{
    options.Width         = 160;
    options.Height        = 48;
    options.CodeLength    = 6;
    options.NoiseLineCount = 3;
    options.RippleWave    = 4;
    options.Letters       = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
    options.ValidityMinutes = 5;
    options.EncryptionIV = "ComnetCaptchaEncryptionIV";
    options.EncryptionKey = "ComnetCaptchaEncryptionKey";
    options.CaseSensitive  = false;
});

Controller

[ApiController]
[Route("api/[controller]")]
public class CaptchaController : ControllerBase
{
    private readonly CaptchaOptions _options;

    public CaptchaController(CaptchaOptions options)
        => _options = options;

    [HttpGet("image")]
    public IActionResult GetImage()
    {
        var result = CaptchaGenerator.Generate(_options);
        HttpContext.Session.SetString("captcha_code", result.CaptchaCode);
        return File(result.CaptchaByteData, "image/png");
    }

    [HttpPost("verify")]
    public IActionResult Verify([FromForm] string userInput)
    {
        var stored = HttpContext.Session.GetString("captcha_code") ?? "";
        return Ok(new { valid = CaptchaGenerator.Validate(stored, userInput) });
    }
}

Minimal API (here no session, so handle via token, pass token and image data to client, then validate with token on submit)

app.MapGet("/captcha", (CaptchaOptions opts, ISession session) =>
{
    var result = CaptchaGenerator.Generate(opts);
    return new {Img=result.ToDataUri(), Token=result.CaptchaToken};
});
For validate:
app.MapPost("/captcha/verify", (string token, string userInput) =>
{
    return new { valid = CaptchaGenerator.Validate(token, userInput) };
});

Configuration Reference

All options can be set via CaptchaOptions:

CaptchaResult Properties

Font Note

The package ships with an embedded TTF font so it works out-of-the-box on Linux Docker containers where Arial (or other common fonts) may not be installed.

If you build from source, place a .ttf file at:

src/ComnetCaptcha/Fonts/Arial.ttf

For redistribution-safe font alternatives consider:

• Liberation Sans (Apache 2.0 — metrically compatible with Arial)
• Noto Sans (OFL)

Docker / Linux

No extra steps needed. The NuGet package includes SkiaSharp.NativeAssets.Linux.NoDependencies, so you don't need to install libfontconfig or other native libraries in your Dockerfile.

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]

Building & Running Tests

git clone https://github.com/yourusername/ComnetCaptcha
cd ComnetCaptcha

# Place a TTF font at:
# src/ComnetCaptcha/Fonts/Arial.ttf

dotnet build
dotnet test

License

MIT © 2026 Comnet Solutions Pte. Lte.