Frequently Asked Questions

What is UUID?

UUID (Universally Unique Identifier) is a 128-bit identifier that's guaranteed to be unique across space and time. Our UUID library provides a high-performance, secure implementation for .NET applications.

How is UUID different from Guid?

While UUID and Guid represent the same concept, our UUID implementation offers:

• Better performance (up to 70% faster)
• More modern API design
• Additional string format options (Base32, Base64)
• Better security by default

Is UUID thread-safe?

Yes, UUID operations are thread-safe. You can safely generate and manipulate UUIDs from multiple threads without any synchronization.

How do I generate a new UUID?

// Simple generation
var uuid = new UUID();

// Generate multiple
UUID[] uuids = new UUID[1000];
ArrayExtension.Fill(uuids);

What string formats are supported?

var uuid = new UUID();

// Standard format (default)
Console.WriteLine(uuid.ToString());
// "0123456789abcdef0123456789abcdef"

// Base32 (URL-safe)
Console.WriteLine(uuid.ToBase32());
// "028T5CY4TQKFF028T5CY4TQKFF"

// Base64
Console.WriteLine(uuid.ToBase64());
// "782riWdFIwHvzauJZ0UjAQ=="

How do I convert between different formats?

var uuid = new UUID();

// Convert to Base64
string base64 = uuid.ToBase64();
UUID fromBase64 = UUID.FromBase64(base64);

// Convert to byte array
byte[] bytes = uuid.ToByteArray();
UUID fromBytes = UUID.FromByteArray(bytes);

// Convert to/from Guid (implicit)
Guid guid = uuid;
UUID fromGuid = guid;

UUID supports various conversion methods with both standard and safe parsing options (Try* methods).

Which string format should I use?

• Standard format: Best for human readability and debugging
• Base32: Best for URLs and file names (URL-safe, no special characters)
• Base64: Best for storage efficiency (shortest representation)

How do I handle conversion errors?

// Safe Base64 parsing
if (UUID.TryFromBase64(base64String, out UUID uuid))
{
    // Success
    Console.WriteLine($"Parsed UUID: {uuid}");
}
else
{
    // Handle invalid input
    Console.WriteLine("Invalid Base64 string");
}

// Safe byte array parsing
if (UUID.TryFromByteArray(bytes, out UUID fromBytes))
{
    // Success
    Console.WriteLine($"Parsed UUID: {fromBytes}");
}
else
{
    // Handle invalid input
    Console.WriteLine("Invalid byte array");

Always use Try* methods when parsing untrusted input to handle errors gracefully.

How do I use UUIDs with Entity Framework?

public class User
{
    public UUID Id { get; set; }
    public string Name { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<User>()
        .Property(e => e.Id)
        .HasConversion(
            v => v.ToByteArray(),
            v => new UUID(v));
}

How many UUIDs can be generated per second?

On a modern system:

• Single thread: ~20.5M UUIDs/second
• Multi-thread (4 cores): ~78.2M UUIDs/second
• Multi-thread (8 cores): ~152.3M UUIDs/second

How can I improve UUID generation performance?

For best performance:

• Use bulk generation methods for multiple UUIDs
• Reuse UUID instances when possible
• Use TryParse instead of Parse
• Store UUIDs in binary format

Why am I getting a FormatException?

FormatException occurs when parsing invalid UUID strings. Common issues:

• Incorrect string format
• Missing or extra hyphens
• Invalid characters

Solution: Use TryParse for safer parsing:

if (UUID.TryParse(input, out var uuid))
{
    // Valid UUID
}
else
{
    // Invalid format
}

How do I migrate from Guid?

UUID provides implicit conversion operators:

// From Guid to UUID
Guid guid = Guid.NewGuid();
UUID uuid = guid;  // Implicit conversion

// From UUID to Guid
UUID uuid = new UUID();
Guid guid = uuid;  // Implicit conversion