Migration Guide

🔄 Migration Guide

This guide helps you migrate from other UUID/Guid implementations to our UUID library.

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();

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();

Database Migration

Entity Framework

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

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 handler
SqlMapper.AddTypeHandler(new UUIDTypeHandler());

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=="

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();
    }
}

Breaking Changes

Version 1.0.1

• Requires .NET SDK 9.0 or newer
• Visual Studio 2022 or newer for development

Common Migration Patterns

Repository Pattern

// Before
public class Repository
{
    public async Task<Entity> GetById(Guid id)
    {
        // ...
    }
}

// After
public class Repository
{
    public async Task<Entity> GetById(UUID id)
    {
        // ...
    }
}

API Controllers

// Before
[HttpGet("{id:guid}")]
public IActionResult Get(Guid id)
{
    // ...
}

// After
[HttpGet("{id}")]
public IActionResult Get(UUID id)
{
    // ...
}

Model Changes

// Before
public class Entity
{
    public Guid Id { get; set; }
}

// After
public class Entity
{
    public UUID Id { get; set; }
}

Best Practices

1. Gradual Migration

   • Start with new features
   • Migrate existing features incrementally
   • Use conversion methods for compatibility

2. Performance Considerations

   • Use bulk operations where possible
   • Implement buffer pooling for string operations
   • Take advantage of thread-safe features

3. Testing

   • Update unit tests to use UUID
   • Test database operations thoroughly
   • Verify string format compatibility