NetUlid 2.0.0

NetUlid

This is a dependency-free, high quality and high performance ULID implementation for .NET. It is 100% conformance to the specifications.

Package	Version
NetUlid
NetUlid.Tool

Benchmark

The following is a result of benchmark agains Ulid and NUlid:

BenchmarkDotNet=v0.13.1, OS=arch
AMD Ryzen 7 PRO 4750U with Radeon Graphics, 1 CPU, 16 logical and 8 physical cores
.NET SDK=6.0.102
  [Host]     : .NET 6.0.2 (6.0.222.11801), X64 RyuJIT
  DefaultJob : .NET 6.0.2 (6.0.222.11801), X64 RyuJIT

The reasons for no ULID generating benchmark is because both Ulid and NUlid fail to conforming to the specifications when timestamp is the same as previously generated.

When to use ULID

You should use ULID if you plan to migrate your data to the distributed database in the future and your data requires sorting. What sorting mean not only display sorting but also including data paging. If your data don't need sorting ability you should stick with Guid. Keep in mind that ULID will expose data creation time automatically to anyone who can access it.

Different from GUID

The main difference with Guid is ULID is sortable, which will make it shine on distributed system. You can think it is a data type to replace auto-increment in SQL, but for distributed database like Cassandra.

Different from UUID version 1

UUID version 1 (AKA timestamp UUID) require a special logic on the database in order to sort it correctly while ULID is not.

Different from Twitter Snowflake

ULID and Twitter Snowflake is very similar. In term of functionalities Twitter Snowflake is better due to it can embed additional data. So if you need to embed additional data to the value you should use Twitter Snowflake instead.

Usage

Generate a new ULID with current time

using NetUlid;

var ulid = Ulid.Generate();

Create a ULID with specified timestamp and randomness

using NetUlid;

var ulid = new Ulid(timestamp, randomness);

Create a ULID from binary representation

using NetUlid;

var ulid = new Ulid(binary);

Compare two ULIDs

if (ulid1 > ulid2)
{
    // Do something.
}
else if (ulid1 < ulid2)
{
    // Do something.
}
else if (ulid1 == ulid2)
{
    // Do something.
}

Get a raw binary representation

var binary = ulid.ToByteArray();

Get canonical representation

var canonical = ulid.ToString();

Create a ULID from canonical representation

using NetUlid;

var ulid = Ulid.Parse(canonical);

Integration with other libraries

ASP.NET Core

The Ulid structure can be using as argument on the action (e.g. query string, route parameter, etc.) without any additional works. The input will be accepted as canonical form.

System.Text.Json

The Ulid structure has JsonConverterAttribute applied so that mean it can be using with System.Text.Json without any additional works.

CLI Tool

We also provide .NET Tool for ULID related tasks. Follow the guide how to use .NET Tool here for the instructions how to install and use it.

The Ulid structure

The struct itself is in a binary form. What is mean is it can be interop with unmanaged code directly.

License

MIT