# Migration Guides

Guides for migrating to Svrnty.CQRS from other frameworks or upgrading between versions.

## Overview

This section provides step-by-step migration guides for moving to Svrnty.CQRS from other popular .NET frameworks.

## Available Guides

### [From MediatR](from-mediatr.md)

Migrate from MediatR to Svrnty.CQRS:
- Mapping MediatR patterns to CQRS patterns
- Handler registration differences
- Pipeline behavior equivalents
- Validation integration

### [From NServiceBus](from-nservicebus.md)

Migrate from NServiceBus to Svrnty.CQRS:
- Message handler mapping
- Saga pattern translation
- Event subscription patterns
- Transaction handling

### [Upgrading Versions](upgrading-versions.md)

Upgrade between Svrnty.CQRS versions:
- Breaking changes by version
- Migration steps
- Deprecated features
- New features

## Migration Strategy

### 1. Assessment Phase

- Identify all commands and queries
- Map handlers to new pattern
- Identify dependencies
- Plan migration order

### 2. Incremental Migration

- Migrate one bounded context at a time
- Run both frameworks side-by-side
- Gradually move traffic
- Monitor and validate

### 3. Cutover

- Complete migration
- Remove old framework
- Update documentation
- Train team

## Quick Comparison

### MediatR vs Svrnty.CQRS

| Feature | MediatR | Svrnty.CQRS |
|---------|---------|-------------|
| **Commands** | `IRequest<T>` | `ICommandHandler<TCommand, TResult>` |
| **Queries** | `IRequest<T>` | `IQueryHandler<TQuery, TResult>` |
| **Registration** | Assembly scanning | Explicit + discovery |
| **HTTP** | Manual controllers | Automatic endpoints |
| **gRPC** | Manual | Source-generated |
| **Validation** | Pipeline behavior | Built-in + FluentValidation |
| **Events** | `INotification` | Event streaming |

### Code Comparison

**MediatR:**
```csharp
public record CreateOrderCommand : IRequest<int>
{
    public int CustomerId { get; init; }
}

public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, int>
{
    public async Task<int> Handle(CreateOrderCommand request, CancellationToken ct)
    {
        // Handle
    }
}

// Registration
services.AddMediatR(typeof(Program));

// Usage
var result = await _mediator.Send(new CreateOrderCommand { CustomerId = 1 });
```

**Svrnty.CQRS:**
```csharp
public record CreateOrderCommand
{
    public int CustomerId { get; init; }
}

public class CreateOrderHandler : ICommandHandler<CreateOrderCommand, int>
{
    public async Task<int> HandleAsync(CreateOrderCommand command, CancellationToken ct)
    {
        // Handle
    }
}

// Registration
services.AddCommand<CreateOrderCommand, int, CreateOrderHandler>();

// Usage (via HTTP/gRPC - automatic)
POST /api/command/createOrder
{ "customerId": 1 }
```

## Benefits of Migration

### From MediatR

- ✅ Automatic HTTP/gRPC endpoints
- ✅ Built-in validation
- ✅ Event streaming support
- ✅ Source-generated gRPC services
- ✅ Metadata-driven discovery (AOT-friendly)

### From NServiceBus

- ✅ Simpler setup (no separate broker needed for single instance)
- ✅ Built-in HTTP/gRPC endpoints
- ✅ Lower infrastructure costs
- ✅ Event sourcing support
- ✅ Integrated observability

## See Also

- [Getting Started](../getting-started/README.md)
- [Architecture](../architecture/README.md)
- [Best Practices](../best-practices/README.md)