- API Reference
-
-
- UUID Struct
- The core struct representing a UUID value.
-
-
-
public readonly partial struct UUID : IEquatable<UUID>, IComparable<UUID>, IComparable
-
Properties
-
-
-
- | Property |
- Type |
- Description |
-
-
- | Empty |
- UUID |
- Gets the empty UUID value (all zeros) |
-
-
- | Version |
- byte |
- Gets the UUID version number (7 for UUIDv7) |
-
-
- | Variant |
- byte |
- Gets the UUID variant number (2 for RFC 4122) |
-
-
- | Time |
- DateTimeOffset |
- Gets the timestamp embedded in the UUID (UUIDv7 only) |
-
-
-
Constructors
-
-
// Create a new random UUID
-public UUID()
-
-// Create from bytes
-public UUID(ReadOnlySpan<byte> bytes)
-
-// Create from string
-public static UUID Parse(string input)
-public static UUID Parse(ReadOnlySpan<char> input)
-
-// Try parse from string
-public static bool TryParse(string input, out UUID result)
-public static bool TryParse(ReadOnlySpan<char> input, out UUID result)
-
Methods
-
- String Formatting
-
-
// Convert to standard string format
-public override string ToString()
-
-// Convert to Base32 format
-public string ToBase32()
-
-// Convert to Base64 format
-public string ToBase64()
-
-// Convert from Base64 format
-public static UUID FromBase64(string base64)
-public static bool TryFromBase64(string base64, out UUID result)
-
Byte Array Operations
-
-
// Convert to byte array
-public byte[] ToByteArray()
-public bool TryWriteBytes(byte[] destination)
-public bool TryWriteBytes(Span<byte> destination)
-
-// Convert from byte array
-public static UUID FromByteArray(byte[] bytes)
-public static bool TryFromByteArray(byte[] bytes, out UUID result)
-
Guid Operations
-
-
// Convert to/from Guid (implicit operators)
-public static implicit operator Guid(UUID uuid)
-public static implicit operator UUID(Guid guid)
-
-// Explicit conversion methods
-public Guid ToGuid()
-public static UUID FromGuid(Guid guid)
-
Comparison Methods
-
-
// Standard equality methods
-public bool Equals(UUID other)
-public override bool Equals(object obj)
-public override int GetHashCode()
-
-// Comparison methods (implements IComparable)
-public int CompareTo(UUID other)
-public int CompareTo(object obj)
-
-// Comparison operators
-public static bool operator ==(UUID left, UUID right)
-public static bool operator !=(UUID left, UUID right)
-public static bool operator <(UUID left, UUID right)
-public static bool operator >(UUID left, UUID right)
-public static bool operator <=(UUID left, UUID right)
-public static bool operator >=(UUID left, UUID right)
-
-// UUIDv7 specific comparisons
-public bool IsOrderedAfter(UUID other)
-public static int CompareTimestamps(UUID a, UUID b)
-public static bool AreMonotonicallyOrdered(UUID[] uuids)
-
Extension Methods
-
-
// Array extensions
-public static class ArrayExtension
-{
- // Generate array of UUIDs
- public static UUID[] Generate(int count)
-
- // Try generate array of UUIDs
- public static bool TryGenerate(int count, out UUID[]? result)
-
- // Fill array with UUIDs
- public static void Fill(this UUID[] array)
-
- // Try fill array with UUIDs
- public static bool TryFill(this UUID[] array)
-}
-
Exceptions
-
-
FormatException
-
Thrown when:
-
- - Invalid string format in Parse methods
- - Invalid byte array length in constructor
-
-
-
ArgumentNullException
-
Thrown when:
-
- - Null input string in Parse methods
- - Null byte array in constructor
-
-
Getting Started
-
-
- Installation
- Install the UUID package via NuGet using one of the following methods:
-
-
-
# .NET CLI
-dotnet add package UUID
-
-# Package Manager Console
-Install-Package UUID
-
Basic Usage
- Here's how to get started with basic UUID operations:
-
-
-
// Generate a new UUID
-var id = new UUID();
-
-// Convert to string
-string str = id.ToString(); // "0123456789abcdef0123456789abcdef"
-
-// Parse from string
-UUID parsed = UUID.Parse("0123456789abcdef0123456789abcdef");
-
-// Check UUID version and variant
-Console.WriteLine($"Version: {id.Version}"); // 7 (UUIDv7)
-Console.WriteLine($"Variant: {id.Variant}"); // 2 (RFC 4122)
-
-// Get timestamp from UUID
-Console.WriteLine($"Time: {id.Time:yyyy-MM-dd HH:mm:ss.fff}");
-
-
Bulk Operations
- For high-performance scenarios where you need to generate multiple UUIDs efficiently:
-
-
-
// Fill an existing array with UUIDs
-UUID[] uuids = new UUID[1000];
-uuids.Fill(); // Thread-safe, efficient bulk generation
-
-// Generate a new array of UUIDs
-UUID[] generated = ArrayExtension.Generate(1000);
-
-// With error handling
-if (ArrayExtension.TryGenerate(1000, out UUID[]? result))
-{
- foreach (var uuid in result)
- {
- // Process each UUID
- Console.WriteLine(uuid);
- }
-}
-
-
Performance Tips
-
- - Use
Fill() for existing arrays to avoid allocation overhead
- - Use
TryGenerate() for safe bulk generation with error handling
- - All bulk operations are thread-safe and optimized for concurrent use
-
-
Byte Array Operations
- UUID provides methods for converting to and from byte arrays:
-
-
-
// Convert UUID to byte array
-UUID id = UUID.New();
-byte[] bytes = id.ToByteArray();
-Console.WriteLine($"UUID -> Bytes: {BitConverter.ToString(bytes)}");
-
-// Convert byte array back to UUID
-UUID fromBytes = UUID.FromByteArray(bytes);
-Console.WriteLine($"Bytes -> UUID: {fromBytes}");
-
-// Safe parsing with TryFromByteArray
-if (UUID.TryFromByteArray(bytes, out UUID parsedFromBytes))
-{
- Console.WriteLine($"Successfully parsed from bytes: {parsedFromBytes}");
-}
-
-// Writing directly to a byte array
-byte[] destination = new byte[16];
-if (id.TryWriteBytes(destination))
-{
- Console.WriteLine($"Successfully wrote to byte array: {BitConverter.ToString(destination)}");
-}
-
Security Guide
-
-
- Security Overview
- UUID library is designed with security in mind, using cryptographically secure random number generation by default.
-
-
-
Key Security Features
-
- - Cryptographically secure random number generation
- - Protection against timing attacks
- - Safe string parsing and validation
- - Thread-safe operations
-
-
Random Number Generation
-
-
-
Secure Generation
-
UUID uses System.Security.Cryptography.RandomNumberGenerator for secure random number generation:
-
-
// Automatically uses secure RNG
-var uuid = new UUID();
-
-// For bulk operations
-UUID[] uuids = new UUID[1000];
-ArrayExtension.Fill(uuids); // Still uses secure RNG
-
-
Security Best Practices
-
-
-
Recommended Practices
-
- - Always validate UUID inputs
- - Use TryParse for untrusted input
- - Store UUIDs in their binary form when possible
- - Use URL-safe Base32 encoding for web contexts
-
-
-
Practices to Avoid
-
- - Don't use UUIDs for sensitive data encoding
- - Don't use UUIDs as security tokens
- - Don't assume sequential UUIDs are secure
- - Don't expose internal UUID representation
-
-
Secure Storage
-
-
-
Database Storage
-
Best practices for storing UUIDs in databases:
-
-
-- SQL Server
-CREATE TABLE Users (
- Id BINARY(16) PRIMARY KEY, -- Most efficient
- -- or
- Id UNIQUEIDENTIFIER PRIMARY KEY -- If you need native UUID type
-);
-
-
-
Entity Framework
-
Configure EF Core for secure UUID handling:
-
-
protected override void OnModelCreating(ModelBuilder modelBuilder)
-{
- modelBuilder.Entity<User>()
- .Property(e => e.Id)
- .HasConversion(
- v => v.ToByteArray(), // Store as binary
- v => new UUID(v));
-}
-
-
Cryptographic Notes
-
-
-
Important Security Notes
-
- - UUIDs are not suitable for cryptographic purposes
- - Do not use UUIDs to store sensitive information
- - UUIDs are not guaranteed to be unique across systems
- - Use proper cryptographic functions for security-critical operations
-
-
-
Modern UUID Generator for .NET
-
High-performance, secure, and thread-safe UUID implementation
-
-
Features
-
-
-
-
High Performance
-
Optimized for speed with zero-allocation operations
-
-
-
-
Secure by Default
-
Cryptographically secure random number generation
-
-
-
-
Thread Safe
-
Safe for concurrent operations in multi-threaded environments
-
-
-
-
Memory Efficient
-
Zero-allocation options for high-throughput scenarios
-
-
-
-
UUIDv7 Support
-
Time-ordered, monotonic UUIDs with enhanced uniqueness
-
-
-
-
Bulk UUID Generation
-
Efficiently generate large arrays of UUIDs with minimal overhead
-
-
Quick Start
-
-
// Install via NuGet
-dotnet add package UUID
-
-// Generate a new UUID
-var id = new UUID();
-
-// Convert to string
-string str = id.ToString();
-
-// Parse from string
-UUID parsed = UUID.Parse("0123456789abcdef0123456789abcdef");
-
-// Bulk UUID Generation
-UUID[] uuids = new UUID[1000];
-uuids.Fill(); // Efficiently fills array with new UUIDs
-
-// Generate with error handling
-if (UUID.TryGenerate(1000, out UUID[]? result))
-{
- // Use the generated UUIDs
- foreach (var uuid in result)
- {
- Console.WriteLine(uuid);
- }
-}
-
Performance Benchmarks
-
-
-
Single Thread
-
20.5M
-
UUIDs/second
-
-
-
4 Threads
-
78.2M
-
UUIDs/second
-
-
-
8 Threads
-
152.3M
-
UUIDs/second
-
-
-
16 Threads
-
289.8M
-
UUIDs/second
-
-
+