Atulin.Sqids.AspNetCore 1.1.0

Sqids.AspNetCore

A strongly-typed Sqid for ASP.NET Core, built on the Sqids ID generation scheme. It encodes non-negative integers into short, URL-safe, non-sequential IDs and decodes them back.

This library provides first-class integration with ASP.NET Core: route/query/form/model binding for Minimal APIs, MVC, and Razor Pages; JSON serialization/deserialization via a built-in JsonConverter; and OpenAPI schema generation. IDs are validated to be in canonical form, matching the behavior of other official Sqids implementations.

Differences from Sqids.NET

This library is not a fork of the core Sqids library; it builds a higher-level Sqid type and ASP.NET Core integration on top of the same spec. Key differences:

If you only need core encoding/decoding (not ASP.NET Core binding/JSON/OpenAPI), use sqids-dotnet. If you're building an ASP.NET Core app and want a Sqid value type that "just works" with model binding, JSON, and OpenAPI, this library is a better fit.

References

• Sqids.org – original Sqids library and documentation
• Sqids Specification – the canonical Sqids specification this implementation follows
• sqids-dotnet – core .NET implementation of Sqids
• Sqids GitHub Organization – official implementations across languages

Installation

Add the package to your project:

dotnet add package Atulin.Sqids.AspNetCore

Quick Start

Register Sqids and (optionally) OpenAPI support in Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSqids(options =>
{
    options.MinLength = 8; // pad IDs to at least this length
    // options.Alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
    // options.Blocklist.Add("badword");
});

builder.Services.AddOpenApi(o => o.AddSqidSchema());

var app = builder.Build();

app.MapOpenApi();
app.Run();

Usage

The Sqid type

Sqid is a readonly struct wrapping a non-negative long. It supports equality, ordering (numeric), parsing, and formatting. Parsing accepts only the canonical form produced by encoding the same value with the same alphabet, MinLength, and blocklist rules.

// Create from a number
Sqid id = Sqid.From(42);
Console.WriteLine(id.ToString()); // e.g. "Lk"

// Parse
Sqid parsed = Sqid.Parse("Lk");
bool ok = Sqid.TryParse("Lk", out var value);

// Span/UTF-8 overloads are also supported
Sqid.Parse("Lk".AsSpan());
Sqid.TryParse("Lk"u8, out _);

Dependency Injection: SqidCodec

AddSqids() registers the process-wide codec as a singleton SqidCodec, so you can inject it for programmatic encoding/decoding:

app.MapGet("/encode/{n:long}", (long n, SqidCodec codec) => codec.Encode(n));
app.MapGet("/decode/{id}", (string id, SqidCodec codec) =>
    codec.TryDecode(id, out var v) == SqidParseError.None
        ? Results.Ok(v)
        : Results.BadRequest("Invalid id"));

Minimal APIs

Sqid binds directly from route, query, or body parameters:

// Route binding
app.MapGet("/users/{id:sqid}", (Sqid id) => $"User {id.Value}");

// Query binding
app.MapGet("/users", (Sqid? id) => id is null ? "All" : $"User {id.Value}");

// JSON body binding (works automatically via the built-in JsonConverter)
app.MapPost("/users", (UserDto user) => Results.Ok(user));

MVC Controllers & Razor Pages

Sqid works as an action parameter, model property, or route constraint. The included model binder, TypeConverter, and {id:sqid} route constraint are registered automatically when you call AddSqids().

public class User
{
    public Sqid Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

public class UsersController : Controller
{
    [HttpGet("{id:sqid}")]
    public IActionResult Get(Sqid id) => Ok(id);
}

JSON Serialization

Sqid is serialized as a string and deserialized from a string only. Dictionary keys are also supported. Numbers are rejected during deserialization.

var user = new User { Id = Sqid.From(123), Name = "Alice" };
string json = JsonSerializer.Serialize(user); // {"Id":"Uk","Name":"Alice"}
var restored = JsonSerializer.Deserialize<User>(json)!;

OpenAPI

Call AddSqidSchema() when configuring OpenAPI to add a reusable Sqid component schema with proper constraints (type: string, format: sqid, pattern: ^[0-9A-Za-z]+$, minLength: 2, maxLength: 12, description, and example). All Sqid and Sqid? properties in your models will reference the shared component, and route/query/header parameters of type Sqid (Minimal APIs and MVC alike) are described with the same constraints inline.

builder.Services.AddOpenApi(o => o.AddSqidSchema());

// Then serve the document as normal
app.MapOpenApi();

Configuration

SqidOptions lets you customize the codec:

builder.Services.AddSqids(o => {
    o.MinLength = 10;
    o.Alphabet = "abcdef0123456789";
    o.Blocklist = new HashSet<string> { "abc", "def" };
});

Synthetic Benchmark

• SqidsNet → Sqids.NET library
• SquidCodec → this library, raw codec performance

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26300.9711)
AMD Ryzen 9 9900X 4.40GHz, 1 CPU, 24 logical and 12 physical cores
.NET SDK 11.0.100-rc.2.26504.105
  [Host]     : .NET 10.0.13 (10.0.13, 10.0.1326.50504), X64 RyuJIT x86-64-v4
  DefaultJob : .NET 10.0.13 (10.0.13, 10.0.1326.50504), X64 RyuJIT x86-64-v4

Notes on Canonicality & Safety

• Canonical form required: Parsing/accepting an ID re-encodes its decoded value and requires the result to match exactly. This rejects non-canonical forms such as leading-zero-like artifacts, wrong padding, IDs produced with different options, blocked IDs, or IDs that do not represent a single value.
• Single-value only: The library encodes and decodes a single integer per ID (matching the Sqids design). Multi-number encodings are rejected on parse with a distinct parse error.
• Not encryption or obfuscation of sensitive data: Sqids are intended for public, non-sensitive identifiers. Do not rely on them for security.
• Blocklist aware: When a generated ID would contain a blocked word, the encoder retries with a different permutation until it finds a safe ID or exhausts attempts.

Building & Testing

This project targets net10.0. Tests use TUnit on Microsoft.Testing.Platform.

# Build everything
dotnet build

# Run tests
dotnet test

License

MIT License