FAQ

❓ Frequently Asked Questions

General Questions

What is UUID?

UUID is a modern and efficient unique identifier generator for the .NET ecosystem, designed for high performance and enhanced security in distributed systems.

What .NET versions are supported?

UUID requires .NET SDK 9.0 or newer. It supports:

• .NET and .NET Core
• .NET Framework 4.8+
• Mono 5.4+
• Xamarin.iOS 10.14+

Is UUID thread-safe?

Yes, UUID is completely thread-safe. All operations can be safely used across multiple threads without external synchronization.

Technical Questions

How does UUID generation work?

UUID combines a timestamp with cryptographically secure random numbers to generate unique identifiers. This approach ensures:

• Uniqueness across distributed systems
• Time-based ordering capabilities
• Enhanced security through cryptographic randomness

What's the difference between UUID and GUID?

While both provide unique identifiers:

• UUID offers enhanced performance
• Includes time-based ordering
• Provides multiple string format options
• Optimized for modern distributed systems

How do I ensure optimal performance?

// Use bulk generation for multiple UUIDs
var uuids = Enumerable.Range(0, 1000)
    .Select(_ => new UUID())
    .ToArray();

// Reuse string buffers for conversions
var buffer = new char[32];
uuid.TryWriteStringify(buffer);

What string formats are supported?

• Hexadecimal (default)
• Base32 (URL-safe)
• Base64

String Format Questions

Which string format should I use?

• Standard format (32 characters): Best for human readability and debugging

  string standard = uuid.ToString(); // "0123456789abcdef0123456789abcdef"

• Base32 format (26 characters): Best for URLs and file names

  string base32 = uuid.ToBase32(); // "028T5CY4TQKFF028T5CY4TQKFF"

• Base64 format (24 characters): Best for storage efficiency

  string base64 = uuid.ToBase64(); // "782riWdFIwHvzauJZ0UjAQ=="

How do I convert between different formats?

// Create a UUID
var uuid = new UUID();

// Convert to different formats
string base64 = uuid.ToBase64();
string base32 = uuid.ToBase32();
string standard = uuid.ToString();

// Convert back from Base64
UUID fromBase64 = UUID.FromBase64(base64);

// Safe parsing from Base64
if (UUID.TryFromBase64(base64, out UUID parsed))
{
    Console.WriteLine($"Successfully parsed: {parsed}");
}

How do I handle conversion errors?

Always use Try* methods when parsing untrusted input:

// 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");
}

Byte Array Operations

How do I work with byte arrays?

var uuid = new UUID();

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

// Convert back from bytes
UUID fromBytes = UUID.FromByteArray(bytes);

// Write directly to a pre-allocated buffer
byte[] buffer = new byte[16];
if (uuid.TryWriteBytes(buffer))
{
    // Use buffer
}

// Use Span<byte> for better performance
Span<byte> span = stackalloc byte[16];
if (uuid.TryWriteBytes(span))
{
    // Use span
}

Guid Conversions

How do I convert between UUID and Guid?

UUID provides implicit conversion operators for seamless integration:

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

// From Guid to UUID
Guid systemGuid = Guid.NewGuid();
UUID fromGuid = systemGuid; // Implicit conversion

// Explicit methods if needed
Guid guidExplicit = uuid.ToGuid();
UUID uuidExplicit = UUID.FromGuid(guidExplicit);

Performance Questions

What's the generation speed?

On modern hardware:

• Single UUID: ~50ns
• Bulk generation: ~30ns per UUID
• String conversion: ~100ns

How does memory usage compare to Guid?

UUID is optimized for minimal memory usage:

• Same size as Guid (16 bytes)
• Zero-allocation operations available
• Efficient string conversion

How do I handle high-throughput scenarios?

// Use parallel generation
Parallel.For(0, 1000000, _ => {
    var id = new UUID();
    // Process ID
});

// Use bulk generation
var ids = new UUID[1000000];
for (int i = 0; i < ids.Length; i++)
{
    ids[i] = new UUID();
}

Security Questions

Is UUID cryptographically secure?

Yes, UUID uses cryptographically secure random number generation for its random component.

Can UUIDs be predicted?

No, the random component uses cryptographic randomness, making prediction practically impossible.

Is it safe to use UUIDs in URLs?

Yes, use the Base32 format for URL-safe UUIDs:

string urlSafeId = uuid.ToBase32();

Troubleshooting

Common Issues

1. Performance Issues

   // Bad: Creating new buffer each time
   uuid.ToString();
   
   // Good: Reuse buffer
   var buffer = new char[32];
   uuid.TryWriteStringify(buffer);

2. Memory Issues

   // Bad: Creating many small arrays
   var bytes = uuid.ToByteArray();
   
   // Good: Reuse buffer
   var buffer = new byte[16];
   uuid.TryWriteBytes(buffer);

Best Practices

1. String Operations

   • Use TryWriteStringify for efficient string conversion
   • Choose appropriate format (Hex/Base32/Base64) based on needs
   • Reuse buffers for bulk operations

2. Thread Safety

   • No external synchronization needed
   • Safe for parallel operations
   • Use bulk generation for multiple UUIDs