UUIDNext Documentation

The UuidToolkit class in the UUIDNext.Tools namespace provides a set of static methods for generating specialized or custom UUIDs, such as those based on specific timestamps, names, or byte arrays.

using UUIDNext.Tools;

// Example usage of UuidToolkit methods
Guid v7 = UuidToolkit.CreateUuidV7FromSpecificDate(DateTimeOffset.UtcNow);
Guid sqlServerGuid = UuidToolkit.CreateSequentialUuidForSqlServerFromSpecificDate(DateTimeOffset.UtcNow);

For specialized requirements beyond standard generation, the library provides two utility classes:

• UuidToolkit: Offers a variety of helper methods to create custom UUIDs.
• UuidDecoder: Used to extract metadata from an existing UUID, such as its version or the timestamp of when it was created.

While Guid.NewGuid() produces standard Version 4 (random) UUIDs, UUIDNext provides specialized versions for specific use cases:

• Database Performance: Version 7 and 8 are sequential and database-friendly, whereas Version 4's randomness can degrade database performance when used as a primary key.
• SQL Server Optimization: UUIDNext is the only library that generates UUIDs specifically tailored for MS SQL Server.
• Monotonicity in Batch Inserts: For high-frequency generation, UUIDNext ensures each UUID is greater than the previous one even if generated within the same millisecond, whereas the standard .NET 9 implementation may not guarantee this behavior for all use cases.
• Compatibility: Use UUIDNext if you are targeting a .NET version older than .NET 9.

Use the uuidnext command followed by a specific subcommand to generate different types of UUIDs:

• UUID v4 (Random): Use random to create a standard random UUID.
• UUID v7 (Sequential): Use sequential to create a time-ordered, sequential UUID.
• Database Friendly UUIDs: Use database [dbName] to generate a UUID optimized for specific database primary keys. Supported dbName values are PostgreSQL, SqlServer, SQLite, or Other (which generates v8).

You can append the --clipboard option to any command to automatically copy the generated UUID to your clipboard.

# Creating a UUID Version 4
uuidnext random

# Creating a UUID Version 7
uuidnext sequential

# Creating a database friendly UUID for MS SQL Server (Version 8)
uuidnext database sqlServer

# Copying output to clipboard
uuidnext random --clipboard

You can install the UUIDNext.Cli command line tool globally using the dotnet CLI. This tool allows you to generate and decode various UUID/GUID versions directly from your terminal.

dotnet tool install --global UUIDNext.Cli

UUIDNext is available on NuGet.org. You can install it to your .NET project using the NuGet package manager or the dotnet CLI.

dotnet add package UUIDNext

The decode command allows you to inspect an existing UUID. It can extract the version and, for UUID versions 1, 6, 7, and 8, it can also decode the embedded timestamp and sequence number.

uuidnext decode 017F22E2-79B0-7CC3-98C4-DC0C0C07398F

Use Uuid.NewDatabaseFriendly() to generate UUIDs optimized for database primary keys. This is useful for avoiding the performance penalties of random UUID v4 in databases.

Supported database types include:

• Database.PostgreSql (Version 7)
• Database.SqlServer (Version 8)

Note: Unlike the standard .NET 9 implementation, UUIDNext ensures that UUIDs generated in the same millisecond are strictly monotonic (each is greater than the previous one), which is beneficial for batch inserts.

using System;
using UUIDNext;

// Creating a database friendly UUID for PostgreSQL (version 7)
Guid postgreSqlUuid = Uuid.NewDatabaseFriendly(Database.PostgreSql);

// Creating a database friendly UUID for MS SQL Server (Version 8)
Guid sqlServerUuid = Uuid.NewDatabaseFriendly(Database.SqlServer);

Use UuidDecoder.GetVersion(Guid) to determine the version of a given UUID. It returns the version as an integer.

int version = UuidDecoder.GetVersion(guid);

The TryDecodeSequence method attempts to extract the sequence component from a UUID. This is supported for UUID versions 1, 6, 7, and 8 (specifically if the v8 UUID is a sequential UUID designed for SQL Server).

It returns true if the sequence was successfully decoded, otherwise false.

if (UuidDecoder.TryDecodeSequence(guid, out short sequence))
{
    // Use the decoded sequence
}

Use Uuid.NewNameBased() to create a UUID based on a namespace and a specific name. This produces a deterministic, hash-like UUID.

Example usage requires a namespace (e.g., Uuid.Namespace.URL) and a string name.

using System;
using UUIDNext;

// Creating a name based UUID (Version 5)
Guid nameBasedUuid = Uuid.NewNameBased(Uuid.Namespace.URL, "https://github.com/uuid6/uuid6-ietf-draft");