341 lines
8.4 KiB
Markdown
341 lines
8.4 KiB
Markdown
# 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
|