Odex.AspNetCore.Generators.OidGen 0.2.0

Odex.AspNetCore.Generators.OidGen

Lightweight unique ID generation for ASP.NET Core. Produce numeric, alphabetic, or mixed strings; apply prefixes, suffixes, and mask-based formats; configure special characters and register everything with a single DI extension.

Table of contents

• About
• Installation
• Requirements
• Configuration
• Quick start
• Capabilities
• Mask format
• Examples
• API reference
• Testing
• Upgrading
• CI/CD
• Contributing
• License
• Links

About

Odex.AspNetCore.Generators.OidGen (O'shabi Unique ID Generator) exposes IOidGen for building human-friendly identifiers in web APIs and services. Generation uses cryptographically secure randomness (RandomNumberGenerator), and options are validated at startup when registered through AddOidGen.

Installation

dotnet add package Odex.AspNetCore.Generators.OidGen

Pin a version for reproducible builds:

dotnet add package Odex.AspNetCore.Generators.OidGen --version 0.2.0

Requirements

NuGet dependencies: Microsoft.Extensions.DependencyInjection.Abstractions, Microsoft.Extensions.Options.

Configuration

Configure defaults when registering services:

builder.Services.AddOidGen(options =>
{
    options.Placeholder = '#';
    options.SpecialChars = "-_";
});

Quick start

1. Register in Program.cs:

using Odex.AspNetCore.Generators.OidGen;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOidGen();
var app = builder.Build();

2. Inject IOidGen:

using Odex.AspNetCore.Generators.OidGen.Interfaces;

public class OrdersController(IOidGen oidGen) : ControllerBase
{
    [HttpPost]
    public IActionResult Create()
    {
        var orderId = oidGen.WithPrefix(12, "ORD-", useSpecialCharacters: false);
        return Ok(new { OrderId = orderId });
    }
}

Capabilities

Mask format

Formatted walks the mask left to right. Each character equal to the effective placeholder is replaced with a random symbol from the mixed charset; all other characters are copied verbatim.

When placeholder is omitted, OidOptions.Placeholder is used.

Examples

Numeric ID

var numericId = oidGen.Digit(10);
// e.g. "8472910536"

Uppercase alphabetic ID

var upperId = oidGen.Character(8, uppercaseOnly: true);
// e.g. "KXMVRQPT"

Mixed ID with special characters

var mixedId = oidGen.Mixed(12, useSpecialCharacters: true);
// e.g. "aB3-xK9_mP2q"

Prefixed order number

var orderId = oidGen.WithPrefix(8, "ORD-", useSpecialCharacters: false);
// e.g. "ORD-a3Fk9M2x"

Masked product code

var productCode = oidGen.Formatted("PROD-###-####", useSpecialCharacters: false);
// e.g. "PROD-a3F-k9M2"

Custom placeholder per call

var txnId = oidGen.Formatted("TXN-***-***", placeholder: '*', useSpecialCharacters: false);

API reference

IOidGen

ServiceCollectionExtensions

XML documentation is included in the NuGet package for IntelliSense.

Testing

Unit tests live in Odex.AspNetCore.Generators.OidGen.Tests. Run:

dotnet test

Upgrading

See the changelog for version history and breaking changes.

0.1.x → 0.2.0 (summary):

• AddOidGen registers IOptions<OidOptions> and validates options on startup.
• IOidGen is registered as a singleton (was scoped).
• Formatted uses char? placeholder — omit to use OidOptions.Placeholder.
• Thread-safe randomness via RandomNumberGenerator (replaces System.Random).
• Argument validation for length, mask, prefix, and suffix.
• Use ServiceCollectionExtensions.AddOidGen (replaces ServiceCollectionExtension).

CI/CD

Contributing

See CONTRIBUTING.md for local setup, pull-request guidelines, and the release process.

License

This project is released under the MIT License.

Copyright (c) Asen O'Shabi.

Links