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](01-introduction.md)

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](02-installation.md)

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](03-first-command.md)

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](04-first-query.md)

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](05-adding-validation.md)

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](06-choosing-http-or-grpc.md)

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](https://dotnet.microsoft.com/download/dotnet/10.0))
- ✅ **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

```bash
dotnet new webapi -n MyApp
cd MyApp
```

### 2. Install Packages

```bash
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

```csharp
// 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

```csharp
// 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!

```bash
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](../architecture/README.md)** - Understand the framework's design
- **[Core Features](../core-features/README.md)** - Dive deeper into commands, queries, and dynamic queries
- **[Tutorials](../tutorials/README.md)** - Learn through comprehensive examples
- **[Event Streaming](../event-streaming/README.md)** - Build event-sourced applications

## Need Help?

- 📖 Check the [Troubleshooting Guide](../troubleshooting/README.md)
- 💬 Ask questions in [GitHub Discussions](https://github.com/svrnty/dotnet-cqrs/discussions)
- 🐛 Report bugs in [GitHub Issues](https://github.com/svrnty/dotnet-cqrs/issues)

---

Ready to start? Continue to **[Introduction to CQRS](01-introduction.md)** →