svrnty/dotnet-cqrs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
5c497f8923
dotnet-cqrs/docs/getting-started/02-installation.md

8.4 KiB
Raw Blame History

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)
  • ✅ IDE: Visual Studio 2024, Rider 2024.3+, or VS Code with C# extension
  • ✅ Package Manager: NuGet (included with .NET SDK)

Verify your installation:

dotnet --version
# Should output: 10.0.0 or later

Create a New Project

Option 1: Web API (Recommended)

dotnet new webapi -n MyApp
cd MyApp

Option 2: Empty Web App

dotnet new web -n MyApp
cd MyApp

Option 3: Worker Service (for background processing)

dotnet new worker -n MyApp
cd MyApp

Install Core Packages

Required Packages

Every Svrnty.CQRS application needs these core packages:

# 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

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

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:

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:

dotnet add package Svrnty.CQRS.FluentValidation
dotnet add package FluentValidation

Dynamic Queries

Add OData-like filtering, sorting, and aggregation:

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:

# 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

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

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

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

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:

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:

dotnet run

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

Troubleshooting

Package Restore Fails

# Clear NuGet cache
dotnet nuget locals all --clear

# Restore packages
dotnet restore

Version Conflicts

Ensure all Svrnty.CQRS packages are the same version:

dotnet list package | grep Svrnty

Update all packages to the latest version:

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 →

See Also