dotnet-cqrs/docs/migration-guides/README.md

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

Migrate from MediatR to Svrnty.CQRS:

• Mapping MediatR patterns to CQRS patterns
• Handler registration differences
• Pipeline behavior equivalents
• Validation integration

From NServiceBus

Migrate from NServiceBus to Svrnty.CQRS:

• Message handler mapping
• Saga pattern translation
• Event subscription patterns
• Transaction handling

Upgrading Versions

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:

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:

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
• Architecture
• Best Practices