- Overview
- Short Comparison of ULID vs UUID (
System.Guid) - Prerequisites
- Install the Package (NuGet)
- Quick Start
- Get the Code
- Build from the Source Code
- Tests
- Benchmark Tests
- Build and Run the Example
- Basic Usage
- Why Do I Need
UlidFactory? - Performance
- Related Packages
- License
A small, fast, and spec-compliant .NET package that implements Universally Unique Lexicographically Sortable Identifier (ULID).
ULIDs combine a 48-bit timestamp (milliseconds since Unix epoch) with 80 bits of randomness, producing compact 128-bit identifiers that are lexicographically sortable by creation time.
This package exposes a vm2.Ulid value type and a vm2.UlidFactory for stable, monotonic generation.
Universally unique lexicographically sortable identifiers (ULIDs) offer advantages over traditional globally unique identifiers (GUIDs, or UUIDs) in some scenarios:
- Lexicographic sorting: lexicographically sortable identifiers, useful for database indexing
- Timestamp component: most significant six bytes encode time, enabling chronological ordering
- Monotonic change: reduced fragmentation for high-frequency generation within the same millisecond
- Compact representation: 26-character Crockford Base32 string vs 36-character GUID hex with hyphens (8-4-4-4-12)
- Readable time hint: first 10 characters encode the timestamp; GUIDs do not expose creation time in a consistent way
- Binary compatibility: 128-bit values, easy integration with GUID-based systems
- .NET 10.0 or later
-
Using the dotnet CLI:
dotnet add package vm2.Ulid
-
From Visual Studio Package Manager Console:
Install-Package vm2.Ulid
-
Install package
dotnet add package vm2.Ulid
-
Generate ULID
using vm2; UlidFactory factory = new UlidFactory(); Ulid ulid = factory.NewUlid();
For testing, database seeding, and other automation, use the vm2.UlidTool CLI.
You can clone the GitHub repository. The project is in the src/UlidType directory.
-
Command line:
dotnet build src/UlidType/UlidType.csproj
-
Visual Studio:
- Open the solution and choose Build Solution (or Rebuild as needed).
The test project is in the test directory. It uses MTP v2 with xUnit v3.2.2. Compatibility varies by Visual Studio version.
Tests are buildable and runnable from the command line using the dotnet CLI and from Visual Studio Code across OSes.
-
Command line:
dotnet test --project test/UlidType.Tests/UlidType.Tests.csproj -
The tests can also be run standalone after building the solution or the test project:
-
build the solution or the test project only:
dotnet build # build the full solution or dotnet build test/UlidType.Tests/UlidType.Tests.csproj # the test project only
-
Run the tests standalone:
test/UlidType.Tests/bin/Debug/net10.0/UlidType.Tests
-
The benchmark tests project is in the benchmarks directory. It uses BenchmarkDotNet v0.13.8. Benchmarks are buildable and
runnable from the command line using the dotnet CLI.
-
Command line:
dotnet run --project benchmarks/UlidType.Benchmarks/UlidType.Benchmarks.csproj -c Release
-
The benchmarks can also be run standalone after building the benchmark project:
-
build the benchmark project only:
dotnet build -c Release benchmarks/UlidType.Benchmarks/UlidType.Benchmarks.csproj
-
Run the benchmarks standalone (Linux/macOS):
benchmarks/UlidType.Benchmarks/bin/Release/net10.0/UlidType.Benchmarks
-
Run the benchmarks standalone (Windows):
benchmarks/UlidType.Benchmarks/bin/Release/net10.0/UlidType.Benchmarks.exe
-
The example is a file-based application GenerateUlids.cs in the examples directory. It demonstrates basic usage of the
vm2.Ulid library. The example is buildable and runnable from the command line using the dotnet CLI.
-
Command line:
dotnet run --file examples/GenerateUlids.cs
or just:
dotnet examples/GenerateUlids.cs
-
On a Linux/macOS system with the .NET SDK installed, you can also run the example app directly:
examples/GenerateUlids.cs
Provided that:
- execute permission set
- first line ends with
\n(LF), not\r\n(CRLF) - no UTF-8 Byte Order Mark (BOM) at the beginning
These conditions can be met by running the following commands on a Linux system:
chmod u+x examples/GenerateUlids.cs dos2unix examples/GenerateUlids.cs
using vm2;
// Recommended: reuse multiple UlidFactory instances, e.g. one per table or entity type.
// Ensures independent monotonicity per context.
UlidFactory factory = new UlidFactory();
Ulid ulid1 = factory.NewUlid();
Ulid ulid2 = factory.NewUlid();
// Default internal factory ensures thread safety and same-millisecond monotonicity across contexts.
Ulid ulid = Ulid.NewUlid();
Debug.Assert(ulid1 != ulid2); // uniqueness
Debug.Assert(ulid1 < ulid2); // comparable
Debug.Assert(ulid > ulid2); // comparable
var ulid1String = ulid1.String(); // get the ULID canonical string representation
var ulid2String = ulid1.String();
Debug.Assert(ulid1String != ulid2String); // ULID strings are unique
Debug.Assert(ulid1String < ulid2String); // ULID strings are lexicographically sortable
Debug.Assert(ulid1String.Length == 26); // ULID string representation is 26 characters long
Debug.Assert(ulid1 <= ulid2);
Debug.Assert(ulid1.Timestamp < ulid2.Timestamp || // ULIDs are time-sortable and the timestamp can be extracted
ulid1.Timestamp == ulid2.Timestamp && // if generated in the same millisecond
ulid1.RandomBytes != ulid2.RandomBytes); // the random parts are guaranteed to be different
Debug.Assert(ulid1.RandomBytes.Length == 10); // ULID has 10 bytes of randomness
Debug.Assert(ulid1.Bytes.Length == 16); // ULID is a 16-byte (128-bit) value
var ulidGuid = ulid1.ToGuid(); // ULID can be converted to Guid
var ulidFromGuid = new Ulid(ulidGuid); // ULID can be created from Guid
var ulidUtf8String = Encoding.UTF8.GetBytes(ulid1String);
Ulid.TryParse(ulid1String, out var ulidCopy1); // parse ULID from UTF-16 string (26 UTF-16 characters)
Ulid.TryParse(ulidUtf8String, out var ulidCopy2); // parse ULID from its UTF-8 string (26 UTF-8 characters/bytes)
Debug.Assert(ulid1 == ulidCopy1 && // Parsed ULIDs are equal to the original
ulid1 == ulidCopy2);ULIDs must increase monotonically within the same millisecond. When multiple ULIDs are generated in a single millisecond, each subsequent ULID is greater by one in the least significant byte(s). A ULID factory tracks the timestamp and the last random bytes for each call. When the timestamp matches the previous generation, the factory increments the prior random part instead of generating a new random value.
The vm2.UlidFactory class encapsulates the requirements and exposes a simple interface for generating ULIDs. Use multiple
vm2.UlidFactory instances when needed, e.g. one per database table or entity type.
ULID factories are thread-safe and ensure monotonicity of generated ULIDs across application contexts. The factory uses two providers: one for the random bytes and one for the timestamp.
Use dependency injection to construct the factory and manage the providers. DI keeps the provider lifetimes explicit, makes testing simple, and enforces a single, consistent configuration across the app or service.
In simple scenarios, use the static method vm2.Ulid.NewUlid() instead of vm2.UlidFactory. It uses an internal single static
factory instance with a cryptographic random number generator and DateTimeOffset.UtcNow based clock.
By default the vm2.UlidFactory uses a thread-safe, cryptographic random number generator
(vm2.UlidRandomProviders.CryptoRandom), which is suitable for most applications. If you need a different source of randomness,
e.g. for testing purposes, for performance reasons, or if you are concerned about your source of entropy (/dev/random), you
can explicitly specify that the factory should use the pseudo-random number generator vm2.UlidRandomProviders.PseudoRandom.
You can also provide your own, thread-safe implementation of vm2.IRandomNumberGenerator to the factory.
By default, the timestamp provider uses DateTimeOffset.UtcNow converted to Unix epoch time in milliseconds. If you need a
different source of time, e.g. for testing purposes, you can provide your own implementation of vm2.ITimestampProvider to the
factory.
In distributed database applications and services, ULIDs are often generated across many nodes. Design for collision avoidance and monotonicity from the start. Node-local monotonicity does not imply global monotonicity, and clock skew can surface quickly under load.
One approach uses a separate UlidFactory instance on each node with a unique node identifier. ULIDs remain distinct even when
generated in the same millisecond. However, global monotonicity across all nodes does not hold under this approach.
To maintain global monotonicity, a centralized ULID service can generate ULIDs for all nodes. This ensures uniqueness and monotonicity across the system, at the cost of a single point of failure and a potential performance bottleneck. Time synchronization across nodes remains a challenge; clock skew can cause non-monotonic ULIDs if not handled properly.
Another approach uses a consensus algorithm to coordinate ULID generation across nodes. This adds complexity and overhead.
The choice depends on system requirements and constraints. Consider trade-offs among uniqueness, monotonicity, performance, and complexity when designing a distributed ULID strategy.
Benchmark results vs similar Guid-generating functions, run on GitHub Actions:
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.61GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.103
[Host] : .NET 10.0.3 (10.0.3, 10.0.326.7603), X64 RyuJIT x86-64-v3
ShortRun : .NET 10.0.3 (10.0.3, 10.0.326.7603), X64 RyuJIT x86-64-v3
Job=ShortRun IterationCount=3 LaunchCount=1
WarmupCount=3
| Type | Method | RandomProviderType | Mean | Error | StdDev | Ratio | RatioSD | Gen0 | Allocated | Alloc Ratio |
|---|---|---|---|---|---|---|---|---|---|---|
| UlidToString | Guid.ToString | ? | 17.24 ns | 6.198 ns | 0.340 ns | 1.00 | 0.02 | 0.0057 | 96 B | 1.00 |
| ParseUlid | Guid.Parse(string) | ? | 30.29 ns | 3.002 ns | 0.165 ns | 1.76 | 0.03 | - | - | 0.00 |
| UlidToString | Ulid.ToString | ? | 60.26 ns | 18.434 ns | 1.010 ns | 3.50 | 0.08 | 0.0114 | 192 B | 2.00 |
| ParseUlid | Ulid.Parse(StringUtf16) | ? | 72.48 ns | 8.615 ns | 0.472 ns | 4.20 | 0.07 | 0.0024 | 40 B | 0.42 |
| ParseUlid | Ulid.Parse(StringUtf8) | ? | 73.60 ns | 3.424 ns | 0.188 ns | 4.27 | 0.07 | 0.0024 | 40 B | 0.42 |
| NewUlid | Factory.NewUlid | CryptoRandom | 62.74 ns | 1.768 ns | 0.097 ns | 0.11 | 0.00 | 0.0024 | 40 B | NA |
| NewUlid | Ulid.NewUlid | CryptoRandom | 63.09 ns | 7.026 ns | 0.385 ns | 0.11 | 0.00 | 0.0024 | 40 B | NA |
| NewUlid | Guid.NewGuid | CryptoRandom | 590.64 ns | 53.067 ns | 2.909 ns | 1.00 | 0.01 | - | - | NA |
| NewUlid | Factory.NewUlid | PseudoRandom | 63.25 ns | 2.600 ns | 0.142 ns | 0.11 | 0.00 | 0.0024 | 40 B | NA |
| NewUlid | Ulid.NewUlid | PseudoRandom | 63.75 ns | 2.418 ns | 0.133 ns | 0.11 | 0.00 | 0.0024 | 40 B | NA |
| NewUlid | Guid.NewGuid | PseudoRandom | 592.70 ns | 12.714 ns | 0.697 ns | 1.00 | 0.00 | - | - | NA |
Legend:
- Mean : Arithmetic mean of all measurements
- Error : Half of 99.9% confidence interval
- StdDev : Standard deviation of all measurements
- Ratio : Mean of the ratio distribution ([Current]/[Baseline])
- RatioSD : Standard deviation of the ratio distribution ([Current]/[Baseline])
- Gen0 : GC Generation 0 collects per 1000 operations
- Allocated : Allocated memory per single operation (managed only, inclusive, 1KB = 1024B)
- 1 ns : 1 Nanosecond (0.000000001 sec)
random number generator on every call, whereas Ulid.NewUlid only uses it when the millisecond timestamp changes and if it
doesn't, it simply increments the random part of the previous call.
- ULID Specification - Official ULID spec
- vm2.UlidTool - ULID Generator Command Line Tool
MIT - See LICENSE