Migration Guide

Migrating from Guid

Basic Migration

// Before (Guid)
Guid guid = Guid.NewGuid();
string guidString = guid.ToString();

// After (UUID)
UUID uuid = new UUID();
string uuidString = uuid.ToString();

The UUID library provides a modern, high-performance alternative to System.Guid with additional features and better performance.

Converting Existing Guids

// Convert from Guid to UUID
Guid existingGuid = Guid.NewGuid();
UUID uuid = UUID.FromGuid(existingGuid);

// Convert back to Guid if needed
Guid convertedBack = uuid.ToGuid();

// Using implicit operators
UUID fromGuid = existingGuid;  // Implicit conversion
Guid toGuid = uuid;           // Implicit conversion

UUID provides both explicit conversion methods and implicit operators for seamless integration with existing Guid-based code.

Database Migration

// Entity Framework Configuration
public class MyDbContext : DbContext
{
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<MyEntity>()
            .Property(e => e.Id)
            .HasConversion(
                uuid => uuid.ToString(),
                str => UUID.Parse(str)
            );
    }
}

// Dapper Type Handler
public class UUIDTypeHandler : SqlMapper.TypeHandler<UUID>
{
    public override UUID Parse(object value)
    {
        return UUID.Parse((string)value);
    }

    public override void SetValue(IDbDataParameter parameter, UUID value)
    {
        parameter.Value = value.ToString();
    }
}

// Register the Dapper handler
SqlMapper.AddTypeHandler(new UUIDTypeHandler());

The UUID library integrates seamlessly with popular ORMs and data access libraries.

Migrating from Other UUID Libraries

String Format Conversion

// Common string formats supported
UUID uuid = new UUID();

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

// URL-safe format
string urlSafe = uuid.ToBase32();   // "028T5CY4TQKFF028T5CY4TQKFF"

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

UUID supports multiple string formats for different use cases, making it easy to migrate from other UUID implementations.

Performance Optimization

// Reusable buffers for high-performance scenarios
public class UUIDConverter
{
    private readonly char[] _buffer = new char[32];
    
    public string FastConvert(UUID uuid)
    {
        if (uuid.TryWriteStringify(_buffer))
        {
            return new string(_buffer);
        }
        return uuid.ToString();
    }
}

// Using Span for better performance
public class UUIDByteConverter
{
    public byte[] ToBytes(UUID uuid)
    {
        Span buffer = stackalloc byte[16];
        if (uuid.TryWriteBytes(buffer))
        {
            return buffer.ToArray();
        }
        return uuid.ToByteArray();
    }
}

UUID provides high-performance methods and modern C# features like Span<T> for optimal performance.

Migration Checklist

Before Migration

Identify all Guid/UUID usages in your codebase
Review string format requirements
Check database schema compatibility
Test performance with your typical workload

During Migration

Update model properties from Guid to UUID
Configure ORM mappings
Update API contracts if necessary
Implement conversion logic for external systems

After Migration

Verify all UUID operations work as expected
Confirm database operations are successful
Run performance tests
Update documentation