dotnet-cqrs/docs/getting-started

Getting Started with Svrnty.CQRS

Welcome! This guide will help you build your first Svrnty.CQRS application from scratch.

What You'll Learn

By the end of this guide, you'll be able to:

• ✅ Understand what CQRS is and when to use it
• ✅ Install the necessary NuGet packages
• ✅ Create command and query handlers
• ✅ Add validation with FluentValidation
• ✅ Expose endpoints via HTTP or gRPC
• ✅ Make informed decisions about your application architecture

Learning Path

Follow these guides in order:

1. Introduction to CQRS

Learn what CQRS is, why you'd use it, and how Svrnty.CQRS implements the pattern.

Topics covered:

• What is CQRS?
• Benefits and trade-offs
• When to use CQRS
• How Svrnty.CQRS works

2. Installation

Set up your project and install the required NuGet packages.

Topics covered:

• Creating a new ASP.NET Core project
• Installing core packages
• Choosing integration packages (HTTP vs gRPC)
• Project structure recommendations

3. Your First Command

Build your first command handler step-by-step.

Topics covered:

• Defining a command
• Implementing a command handler
• Registering the handler
• Testing your command

4. Your First Query

Build your first query handler step-by-step.

Topics covered:

• Defining a query
• Implementing a query handler
• Registering the handler
• Testing your query

5. Adding Validation

Add input validation using FluentValidation.

Topics covered:

• Setting up FluentValidation
• Creating validators
• HTTP validation (RFC 7807)
• gRPC validation (Google Rich Error Model)

6. Choosing HTTP vs gRPC

Understand when to use HTTP, gRPC, or both.

Topics covered:

• HTTP (Minimal API) pros and cons
• gRPC pros and cons
• Comparison table
• Dual-protocol setup

Prerequisites

Before you begin, make sure you have:

• ✅ .NET 10 SDK or later (Download)
• ✅ Visual Studio 2024, Rider 2024.3+, or VS Code with C# extension
• ✅ Basic knowledge of C# and ASP.NET Core
• ✅ Understanding of dependency injection (helpful but not required)

Quick Start

If you want to jump straight in, here's a minimal working example:

1. Create Project

dotnet new webapi -n MyApp
cd MyApp

2. Install Packages

dotnet add package Svrnty.CQRS
dotnet add package Svrnty.CQRS.Abstractions
dotnet add package Svrnty.CQRS.MinimalApi
dotnet add package Svrnty.CQRS.FluentValidation

3. Create a Command

// Commands/CreateUserCommand.cs
public record CreateUserCommand
{
    public string Name { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
}

public class CreateUserCommandHandler : ICommandHandler<CreateUserCommand, int>
{
    public Task<int> HandleAsync(CreateUserCommand command, CancellationToken cancellationToken)
    {
        // Your logic here
        var userId = new Random().Next(1, 1000);
        return Task.FromResult(userId);
    }
}

public class CreateUserCommandValidator : AbstractValidator<CreateUserCommand>
{
    public CreateUserCommandValidator()
    {
        RuleFor(x => x.Name).NotEmpty();
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
    }
}

4. Register and Map

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Register CQRS services
builder.Services.AddSvrntyCQRS();
builder.Services.AddDefaultCommandDiscovery();

// Register command with validator
builder.Services.AddCommand<CreateUserCommand, int, CreateUserCommandHandler, CreateUserCommandValidator>();

var app = builder.Build();

// Map endpoints
app.UseSvrntyCqrs();

app.Run();

5. Test It!

curl -X POST http://localhost:5000/api/command/createUser \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

What's Next?

After completing the Getting Started guides, explore:

• Architecture - Understand the framework's design
• Core Features - Dive deeper into commands, queries, and dynamic queries
• Tutorials - Learn through comprehensive examples
• Event Streaming - Build event-sourced applications

Need Help?

• 📖 Check the Troubleshooting Guide
• 💬 Ask questions in GitHub Discussions
• 🐛 Report bugs in GitHub Issues

---

Ready to start? Continue to Introduction to CQRS →