DeterministicGuids 1.0.9

 DeterministicGuids

A small, allocation-conscious, thread-safe .NET utility for generating name-based deterministic UUIDs (a.k.a. GUIDs) using RFC 9562 v3 (MD5), v5 (SHA-1) and v8 (SHA-256).

You give it:

• a namespace GUID (for a logical domain like "Orders", "Users", "Events")
• a name (string within that namespace)
• and (optionally) the UUID version (3, 5 or 8).
  If you don't specify it, it defaults to version 5 (SHA-1). v8 is implemented using SHA-256.

It will always return the same GUID for the same (namespace, name, version) triplet.

This is useful for:

• Stable IDs across services or deployments
• Idempotent commands / events
• Importing external data but keeping predictable identifiers
• Deriving IDs from business keys without storing a lookup table

Features

• ✅ Deterministic
  Same (namespace, name, version) → same output every time.

• ✅ Standards-based
  Implements RFC 9562 §5.3 for UUIDv3 (MD5-based), RFC 9562 §5.5 UUIDv5 (SHA-1-based) and RFC 9562 §5.8 for UUIDv8 (SHA-256-based).

• ✅ Thread-safe
  No shared mutable state, no static caches, no locks. You can call it from many threads at once.

• ✅ Optimized memory profile

  • Uses Span<byte> and stackalloc for fixed-size work.
  • Uses ArrayPool<byte> for variable-length buffers (the UTF-8 input string), instead of allocating on every call.
  • Uses incremental hashing on modern runtimes, so we never build a giant namespace+name concatenated array.

• ✅ Zero runtime GUID parsing for known namespaces
  Namespaces are defined using the numeric Guid constructor, not Guid.Parse(...), so there is no string parsing cost at first use.

• ✅ Multi-targeted

  • netstandard2.0
  • netstandard2.1
  • net5.0
  • net6.0
  • net7.0
  • net8.0 (and above)

On newer targets we take advantage of newer BCL APIs to reduce allocations to zero.

Quick Start

using DeterministicGuids;

// Choose a namespace (either one of the built-ins or your own Guid)
var ns = DeterministicGuid.Namespaces.Events;

// Define the stable name/key within that namespace
var key = "order:12345";

// Generate a deterministic GUID.
// This uses version 5 (SHA-1) by default.
Guid idV5 = DeterministicGuid.Create(ns, key);

Console.WriteLine(idV5);
// Same ns + key + version (5) will always produce the same Guid

Benchmarks

DeterministicGuids stacks very well against other libraries in terms of speed, whilst being allocation-free. Here are some benchmarks with values taken directly from a run in GitHub Actions.

.NET 10.0.2 (10.0.2, 10.0.225.61305), X64 RyuJIT x86-64-v3

.NET 9.0.12 (9.0.12, 9.0.1225.60609), X64 RyuJIT x86-64-v3

.NET 8.0.23 (8.0.23, 8.0.2325.60607), X64 RyuJIT x86-64-v3

.NET 6.0.36 (6.0.36, 6.0.3624.51421), X64 RyuJIT x86-64-v3

.NET 5.0.17 (5.0.17, 5.0.1722.21314), X64 RyuJIT x86-64-v3

.NET Core 3.1.32 (3.1.32, 4.700.22.55902), X64 RyuJIT VectorSize=256

.NET Framework 4.8.1 (4.8.9310.0), X64 RyuJIT VectorSize=256

Credits

Check out our list of contributors!