Foundatio.CommandQuery

A powerful Command Query Responsibility Segregation (CQRS) framework built on the mediator pattern. This library provides core abstractions and implementations for building scalable, maintainable applications using CQRS principles.

Features

• Clean CQRS Implementation - Separate read and write operations with clear command/query patterns
• Mediator Pattern - Built on Foundatio.Mediator for decoupled messaging
• Multiple Data Stores - Support for Entity Framework Core and MongoDB out of the box
• ASP.NET Core Integration - Minimal API endpoints for exposing commands and queries via HTTP
• Caching Support - Built-in caching abstractions for query optimization
• Dynamic Queries - Powerful filtering, sorting, and pagination with LINQ support
• Multi-Targeting - Supports .NET 8, .NET 9, and .NET 10

Packages

Package	Description	NuGet
Foundatio.CommandQuery	Core abstractions and base classes for implementing CQRS patterns using the mediator pattern
Foundatio.CommandQuery.Dispatcher	Dispatcher implementation providing centralized command and query handling with caching support
Foundatio.CommandQuery.Endpoints	ASP.NET Core Minimal API endpoints for HTTP-based command and query execution
Foundatio.CommandQuery.EntityFramework	Entity Framework Core integration providing database query and persistence handlers with dynamic LINQ support
Foundatio.CommandQuery.MongoDB	MongoDB integration providing NoSQL database query and persistence handlers with dynamic LINQ support

Installation

Using .NET CLI

# Core package
dotnet add package Foundatio.CommandQuery
# Entity Framework integration
dotnet add package Foundatio.CommandQuery.EntityFramework
# MongoDB integration
dotnet add package Foundatio.CommandQuery.MongoDB
# ASP.NET Core endpoints
dotnet add package Foundatio.CommandQuery.Endpoints
# Dispatcher for Blazor 
dotnet add package Foundatio.CommandQuery.Dispatcher

Using Package Manager Console

Install-Package Foundatio.CommandQuery
Install-Package Foundatio.CommandQuery.EntityFramework
Install-Package Foundatio.CommandQuery.MongoDB
Install-Package Foundatio.CommandQuery.Endpoints
Install-Package Foundatio.CommandQuery.Dispatcher

Quick Start

1. Define Your Models

// Entity modelpublicclassTask:IHaveIdentifier<int>{publicintId{get;set;}publicstringTitle{get;set;}publicstringDescription{get;set;}publicDateTimeCreated{get;set;}publicstringCreatedBy{get;set;}}// Read modelpublicclassTaskReadModel:EntityReadModel<int>{publicstringTitle{get;set;}publicstringDescription{get;set;}}// Create modelpublicclassTaskCreateModel:EntityCreateModel<int>{publicstringTitle{get;set;}publicstringDescription{get;set;}}// Update modelpublicclassTaskUpdateModel:EntityUpdateModel{publicstringTitle{get;set;}publicstringDescription{get;set;}}

2. Create Command and Query Handlers

usingFoundatio.CommandQuery.EntityFramework;publicclassTaskCommandHandler:EntityCommandHandler<AppDbContext,Task,int,TaskReadModel,TaskCreateModel,TaskUpdateModel>{publicTaskCommandHandler(AppDbContextcontext,IMappermapper):base(context,mapper){}}publicclassTaskQueryHandler:EntityQueryHandler<AppDbContext,Task,int,TaskReadModel>{publicTaskQueryHandler(AppDbContextcontext,IMappermapper):base(context,mapper){}}

3. Register Services

varbuilder=WebApplication.CreateBuilder(args);// Add mediator with assemblies containing handlersbuilder.Services.AddMediator(options =>options.AddAssembly(typeof(Program).Assembly));// Add your DbContextbuilder.Services.AddDbContext<AppDbContext>(options =>options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));// Add endpoint routesbuilder.Services.AddEndpointRoutes();

4. Configure Minimal API Endpoints

publicclassTaskEndpoint:EntityCommandEndpointBase<int,TaskListModel,TaskReadModel,TaskCreateModel,TaskUpdateModel>{publicTaskEndpoint(ILoggerFactoryloggerFactory):base(loggerFactory,"tasks","api/tasks"){}}varapp=builder.Build();// Map endpoint routesapp.MapEndpointRoutes();app.Run();

This automatically creates the following endpoints:

• GET /api/tasks/{id} - Get a task by ID
• GET /api/tasks - Query tasks with pagination and sorting
• POST /api/tasks/query - Query tasks with advanced filtering
• GET /api/tasks/{id}/update - Get task update model
• POST /api/tasks - Create a new task
• PUT /api/tasks/{id} - Update a task
• DELETE /api/tasks/{id} - Delete a task

Advanced Usage

Using Commands Directly

publicclassTaskService{privatereadonlyIMediator_mediator;publicTaskService(IMediatormediator){_mediator=mediator;}publicasyncTask<Result<TaskReadModel>>CreateTaskAsync(TaskCreateModelmodel,ClaimsPrincipaluser){varcommand=newCreateEntity<TaskCreateModel,TaskReadModel>(user,model);returnawait_mediator.InvokeAsync<Result<TaskReadModel>>(command);}publicasyncTask<Result<TaskReadModel>>GetTaskAsync(intid,ClaimsPrincipaluser){varquery=newGetEntity<int,TaskReadModel>(user,id);returnawait_mediator.InvokeAsync<Result<TaskReadModel>>(query);}publicasyncTask<Result<QueryResult<TaskReadModel>>>QueryTasksAsync(QueryDefinitionquery,ClaimsPrincipaluser){varcommand=newQueryEntities<TaskReadModel>(user,query);returnawait_mediator.InvokeAsync<Result<QueryResult<TaskReadModel>>>(command);}}

Advanced Querying

// Query with filtering, sorting, and paginationvarqueryDefinition=newQueryDefinition{Filter=newQueryFilter{Logic=FilterLogic.And,Filters=newList<QueryFilter>{new(){Field="Status",Operator=FilterOperator.Equal,Value="Active"},new(){Field="Priority",Operator=FilterOperator.GreaterThan,Value=3}}},Sorts=newList<QuerySort>{new(){Name="Priority",Descending=true},new(){Name="Created",Descending=false}},Page=1,PageSize=20};varquery=newQueryEntities<TaskReadModel>(user,queryDefinition);varresult=await_mediator.InvokeAsync<Result<QueryResult<TaskReadModel>>>(query);

MongoDB Usage

usingFoundatio.CommandQuery.MongoDB;publicclassTaskCommandHandler:EntityCommandHandler<Task,int,TaskReadModel,TaskCreateModel,TaskUpdateModel>{publicTaskCommandHandler(IMongoDatabasedatabase,IMappermapper):base(database,mapper){}}publicclassTaskQueryHandler:EntityQueryHandler<Task,int,TaskReadModel>{publicTaskQueryHandler(IMongoDatabasedatabase,IMappermapper):base(database,mapper){}}

Custom Command Handlers

publicrecordProcessTaskCommand:PrincipalCommand<CompleteModel>{publicProcessTaskCommand(ClaimsPrincipal?principal,stringaction):base(principal){Action=action;}publicstringAction{get;}}publicclassProcessTaskHandler:IRequestHandler<ProcessTaskCommand,CompleteModel>{publicasyncValueTask<CompleteModel>HandleAsync(ProcessTaskCommandrequest,CancellationTokencancellationToken=default){// Custom processing logicreturnCompleteModel.Success($"Processed: {request.Action}");}}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.