dotnet-cqrs/docs/getting-started/README.md

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 →