Dapper.CQRS 3.1.0

.NET Standard 2.1
dotnet add package Dapper.CQRS --version 3.1.0
NuGet\Install-Package Dapper.CQRS -Version 3.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Dapper.CQRS" Version="3.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Dapper.CQRS --version 3.1.0
#r "nuget: Dapper.CQRS, 3.1.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Dapper.CQRS as a Cake Addin
#addin nuget:?package=Dapper.CQRS&version=3.1.0

// Install Dapper.CQRS as a Cake Tool
#tool nuget:?package=Dapper.CQRS&version=3.1.0

Description

Dapper.CQRS is a CQRS pattern wrapper for Dapper (micro-orm). It provides you with a basic set of classes and interfaces to write complex queries structured according to the CQRS pattern. This helps you to maintain a clean code architecture for small and very large applications alike.

WTF is Dapper?

Dapper is a lightweight micro-ORM developed by Stack-Overflow as an alternative to entity framework. A developer at stack overflow built it to solve the issue they were having with Entity Frameworks bulky slow queries. Dapper solves that by being almost as fast as ADO.NET but easier to use and map objects against each other. Dapper gives the developer more control by offering the ability to map objects against native SQL queries.

WTF is CQRS?

CQRS stands for Command Query Responsibility Segregation. The idea behind it is to be able to separate your commands (DML) and your queries (DQL). CQRS is a great pattern to follow for small or large systems and offers the flexibility to keep all your database interactions very structured and orderly as the app scales. It is quite similar to the repository pattern, however instead of using interfaces as abstractions we are abstracting every database transaction as a class instead of the context-based model that is used in EF.

Getting Started

Get Dapper.CQRS nuget lives here: https://www.nuget.org/packages/Dapper.CQRS

You can also skip that and just install directly into your project of choice.

dotnet add package Dapper.CQRS --version 2.0.2

Register in your service container

Some basic setup of the Query and Command Executor is all that is required.

container.AddTransient<ICommandExecutor, CommandExecutor>();
container.AddTransient<IQueryExecutor, QueryExecutor>();
// Note: You can use the database provider of your own choosing...
container.AddTransient<IDbConnection, MySqlConnection>(_ => new MySqlDatabaseConnection(GetConnectionString()));

Examples

Our basic models

public class User
{
    [Key]
    public int Id { get; set; }
    public string Name { get; set; }
    public string Surname { get; set; }
    public string Email { get; set; }
    public virtual UserDetails UserDetails { get; set; }
}

public class UserDetails
{
    [Key]
    public int Id { get; set; }
    public string? IdNumber { get; set; }
    
    public int UserId { get; set; }
}

Queries

Define your queries as such. As you see in this example a query is being executed within a query. If the use case fits that problem you are free to do so.

Most queries you write will probably not be nested within each other. However, this is just to illustrate is can be done easily even though it might not always be the right solution.

Note how clear this is and how easy it is to figure out what is being done without a lot of additional context required.

public class FetchUserById : Query<User?>
{
    private readonly int _userId;
    
    public FetchUserById(int userId) {
        _userId = userId;
    }
    
    public override User? Execute()
    {
        var userDetails = QueryExecutor.Execute(new FetchUserDetailsByUserId(_userId));
        var user = QueryFirst<User>("select * from users where id = @Id", new {Id = _userId});
        user.UserDetails = userDetails;
        return user;
    }
}

If we need to bind these two queries within a transaction scope we can easily do that as well.

public class FetchUserById : Query<User?>
{
    private readonly int _userId;
    
    public FetchUserById(int userId) {
        _userId = userId;
    }
    
    public override User? Execute()
    {
        using var scope = new TransactionScope();
        var userDetails = QueryExecutor.Execute(new FetchUserDetailsByUserId(_userId));
        var user = QueryFirst<User>("select * from users where id = @Id", new {Id = _userId});
        user.UserDetails = userDetails;
        scope.Complete();
        return user;
    }
}

Commands

Now you are ready to get started using the CQRS setup within the project. All you have to do now is to start creating your command and query classes and plug them into your controllers.

Dependency resolution example

Making use of your queries and commands is very straight forward. All you have to do is inject them into your desired service of choice and get on with it.

public class HomeController : ControllerBase
{
	public ICommandExecutor CommandExecutor { get; }
	public IQueryExecutor QueryExecutor { get; }
	
	public HomeController(
	    ICommandExecutor commandExecutor, 
	    IQueryExecutor queryExecutor)
	{
	    CommandExecutor = commandExecutor;
	    QueryExecutor = queryExecutor;
	}
	
	publid User Foo(int id) {
	    return QueryExecutor.Execute(new FetchUserById(id));
	}
}

Typical project structure

This is typically what a CQRS based project would be structured like. This is very beautiful and clear. The responsibility of every query and command is very clear and this scales very well as the project grows larger. No messy interfaces and that gooby mess that happens with the UnitOfWork/Repository pattern. All reponsibilities should be clearly defined.

├───Data
│   └───Queries
│   │   └───User
│   │       ├───FetchUserById.cs
│   │       ├───FetchUserByEmail.cs
│   │       └───FetchUserByGuid.cs   
│   │
│   └───Commands
│       └───User
│           └───FetchUserByGuid.cs   

Package dependencies

The Dapper.CQRS Core library is built with .NET Standard 2.1. There are some other dependencies on .NET 6 which include...

  • Dapper (2.0.123)
  • Microsoft.Extensions.DependencyInjection.Abstractions (6.0.0)
  • Microsoft.Extensions.Logging.Abstractions (6.0.3)

Database Support

This is really up to you. All database connections should inherit from IDbConnection. As long as this is the case it will be supported. That is the advantage of Dapper and Dapper.CQRS isn't any different.

Feature List

  • CommandExecutor execution interface
  • QueryExecutor execution interface
  • BaseSqlExecutor with virtual members for easy unit testing
  • Commands which inherit from BaseSqlExecutor
  • Queries which inherit from BaseSqlExecutor

Pull Requests

If you would like to contribute to this package you are welcome to do so.

Testing Coverage

Testing coverage currently covers:

  • QueryExecutor with return type
  • CommandExecutor with return type
  • CommandExecutor without return type
  • Queries
  • Commands with return types
  • Commands without return types
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.1
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Dapper.CQRS:

Package Downloads
Ntk8

Auth-Ntk8 (authenticate) is a basic authentication package that could assist you to setup auth within your project a lot quicker. Use the provided base classes and services to quickly setup authentication within your project.

Dapper.CQRS.QueryBuilders

Dapper.CQRS.QueryBuilders is a wrapper for Dapper.CQRS to build up sql queries dynamically.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.1.0 157 12/28/2022
3.0.0 100 12/27/2022
2.0.3 139 11/27/2022
2.0.2 131 11/27/2022
2.0.1-beta 58 11/25/2022
2.0.0-beta 55 11/25/2022
1.3.3 220 8/15/2022
1.3.2 230 6/20/2022
1.3.1 443 6/10/2022
1.3.0 237 6/10/2022
1.2.7 228 6/9/2022
1.2.6 232 6/9/2022
1.2.5 234 6/9/2022
1.2.4 235 6/9/2022
1.2.3 904 5/5/2022
1.2.2 1,718 11/13/2021
1.2.1 227 10/14/2021
1.2.0 190 10/14/2021
1.1.1 246 7/29/2021
1.1.0 896 7/15/2021
1.0.0 237 6/8/2021

Make the command executor void method a task to support async calls internally