186 lines
4.7 KiB
Markdown
186 lines
4.7 KiB
Markdown
# 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)** →
|