# Installation

Set up your development environment and install the Svrnty.CQRS packages.

## Prerequisites

Before you begin, ensure you have:

- ✅ **.NET 10 SDK** or later ([Download](https://dotnet.microsoft.com/download/dotnet/10.0))
- ✅ **IDE:** Visual Studio 2024, Rider 2024.3+, or VS Code with C# extension
- ✅ **Package Manager:** NuGet (included with .NET SDK)

Verify your installation:

```bash
dotnet --version
# Should output: 10.0.0 or later
```

## Create a New Project

### Option 1: Web API (Recommended)

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

### Option 2: Empty Web App

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

### Option 3: Worker Service (for background processing)

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

## Install Core Packages

### Required Packages

Every Svrnty.CQRS application needs these core packages:

```bash
# Core framework
dotnet add package Svrnty.CQRS
dotnet add package Svrnty.CQRS.Abstractions

# Command and query discovery
# (These are typically included via integration packages)
```

**Package Descriptions:**

| Package | Purpose |
|---------|---------|
| `Svrnty.CQRS` | Core discovery and registration logic |
| `Svrnty.CQRS.Abstractions` | Core interfaces (ICommandHandler, IQueryHandler) |

## Choose Your Integration

You need at least one integration package to expose your commands and queries.

### HTTP Integration (Minimal API)

**Best for:** Web applications, REST APIs, browser clients, public APIs

```bash
dotnet add package Svrnty.CQRS.MinimalApi
```

**Features:**
- ✅ Automatic HTTP endpoint generation
- ✅ Swagger/OpenAPI support
- ✅ Both POST and GET for queries
- ✅ RFC 7807 Problem Details for validation errors

### gRPC Integration

**Best for:** Microservices, internal APIs, high-performance scenarios

```bash
dotnet add package Svrnty.CQRS.Grpc
dotnet add package Svrnty.CQRS.Grpc.Generators
```

**Features:**
- ✅ High-performance binary protocol
- ✅ Source generator for service implementations
- ✅ Google Rich Error Model for validation
- ✅ gRPC reflection support

### Both (Dual Protocol)

For maximum flexibility, install both:

```bash
dotnet add package Svrnty.CQRS.MinimalApi
dotnet add package Svrnty.CQRS.Grpc
dotnet add package Svrnty.CQRS.Grpc.Generators
```

## Optional Packages

### Validation

Add FluentValidation support:

```bash
dotnet add package Svrnty.CQRS.FluentValidation
dotnet add package FluentValidation
```

### Dynamic Queries

Add OData-like filtering, sorting, and aggregation:

```bash
dotnet add package Svrnty.CQRS.DynamicQuery
dotnet add package Svrnty.CQRS.DynamicQuery.Abstractions
dotnet add package Svrnty.CQRS.DynamicQuery.MinimalApi  # For HTTP
```

### Event Streaming

Add event sourcing and message queuing:

```bash
# Core event streaming
dotnet add package Svrnty.CQRS.Events
dotnet add package Svrnty.CQRS.Events.Abstractions

# Storage (choose one)
dotnet add package Svrnty.CQRS.Events.PostgreSQL        # Production
# OR in-memory storage (development only, included in Svrnty.CQRS.Events)

# Optional features
dotnet add package Svrnty.CQRS.Events.ConsumerGroups    # Consumer groups
dotnet add package Svrnty.CQRS.Events.Grpc              # gRPC streaming
```

## Package Overview Table

| Package | Required | Purpose |
|---------|----------|---------|
| **Core** |
| Svrnty.CQRS | ✅ Yes | Core discovery and registration |
| Svrnty.CQRS.Abstractions | ✅ Yes | Core interfaces |
| **Integration** (choose at least one) |
| Svrnty.CQRS.MinimalApi | One | HTTP/Minimal API integration |
| Svrnty.CQRS.Grpc | One | gRPC runtime support |
| Svrnty.CQRS.Grpc.Generators | w/ gRPC | Source generators for gRPC |
| **Validation** |
| Svrnty.CQRS.FluentValidation | Optional | FluentValidation integration |
| FluentValidation | w/ above | FluentValidation library |
| **Dynamic Queries** |
| Svrnty.CQRS.DynamicQuery | Optional | Dynamic query handlers |
| Svrnty.CQRS.DynamicQuery.Abstractions | w/ above | Dynamic query interfaces |
| Svrnty.CQRS.DynamicQuery.MinimalApi | Optional | HTTP endpoints for dynamic queries |
| **Event Streaming** |
| Svrnty.CQRS.Events | Optional | Core event streaming |
| Svrnty.CQRS.Events.Abstractions | w/ above | Event streaming interfaces |
| Svrnty.CQRS.Events.PostgreSQL | Optional | PostgreSQL event storage |
| Svrnty.CQRS.Events.ConsumerGroups | Optional | Consumer group coordination |
| Svrnty.CQRS.Events.Grpc | Optional | gRPC event streaming |

## Common Installation Scenarios

### Scenario 1: Simple REST API

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

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

### Scenario 2: gRPC Microservice

```bash
dotnet new grpc -n MyService
cd MyService

dotnet add package Svrnty.CQRS
dotnet add package Svrnty.CQRS.Abstractions
dotnet add package Svrnty.CQRS.Grpc
dotnet add package Svrnty.CQRS.Grpc.Generators
dotnet add package Svrnty.CQRS.FluentValidation
dotnet add package FluentValidation
```

### Scenario 3: Dual Protocol API

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

dotnet add package Svrnty.CQRS
dotnet add package Svrnty.CQRS.Abstractions
dotnet add package Svrnty.CQRS.MinimalApi
dotnet add package Svrnty.CQRS.Grpc
dotnet add package Svrnty.CQRS.Grpc.Generators
dotnet add package Svrnty.CQRS.FluentValidation
dotnet add package FluentValidation
```

### Scenario 4: Event-Sourced Application

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

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

# Event streaming
dotnet add package Svrnty.CQRS.Events
dotnet add package Svrnty.CQRS.Events.Abstractions
dotnet add package Svrnty.CQRS.Events.PostgreSQL
dotnet add package Svrnty.CQRS.Events.ConsumerGroups
```

## Project Structure

After installation, organize your project like this:

```
MyApp/
├── Commands/               # Command definitions and handlers
│   ├── CreateUserCommand.cs
│   └── CreateUserCommandHandler.cs
├── Queries/                # Query definitions and handlers
│   ├── GetUserQuery.cs
│   └── GetUserQueryHandler.cs
├── Validators/             # FluentValidation validators (optional)
│   └── CreateUserCommandValidator.cs
├── Models/                 # Domain models and DTOs
│   └── User.cs
├── Program.cs              # Application entry point
└── appsettings.json        # Configuration
```

## Verify Installation

Create a simple `Program.cs` to verify everything is working:

```csharp
using Svrnty.CQRS.Abstractions;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

// Map CQRS endpoints
app.UseSvrntyCqrs();

app.MapGet("/", () => "Svrnty.CQRS is running!");

app.Run();
```

Run the application:

```bash
dotnet run
```

Visit `http://localhost:5000` - you should see "Svrnty.CQRS is running!"

## Troubleshooting

### Package Restore Fails

```bash
# Clear NuGet cache
dotnet nuget locals all --clear

# Restore packages
dotnet restore
```

### Version Conflicts

Ensure all Svrnty.CQRS packages are the same version:

```bash
dotnet list package | grep Svrnty
```

Update all packages to the latest version:

```bash
dotnet add package Svrnty.CQRS --version <latest>
dotnet add package Svrnty.CQRS.Abstractions --version <latest>
# ... repeat for other packages
```

### IDE Not Recognizing Packages

**Visual Studio:**
- Tools → NuGet Package Manager → Clear All NuGet Cache(s)
- Restart Visual Studio

**Rider:**
- File → Invalidate Caches / Restart
- Choose "Invalidate and Restart"

**VS Code:**
- Reload window (Ctrl+Shift+P → "Reload Window")
- Restart OmniSharp (.NET language server)

## What's Next?

Now that you have Svrnty.CQRS installed, let's create your first command handler!

**Continue to [Your First Command](03-first-command.md) →**

## See Also

- [Architecture: Modular Solution Structure](../architecture/modular-solution-structure.md) - Best practices for organizing larger projects
- [Troubleshooting: Common Errors](../troubleshooting/common-errors.md) - Solutions to common installation issues
- [NuGet Package Listing](https://www.nuget.org/packages?q=Svrnty.CQRS) - Browse all available packages