The CQRS pattern is one of the most interesting architectural patterns. It stands for Command Query Responsibility Segregation, and in this video, I'm going to explain what CQRS is and how you can start implementing it in your project. This is a high-level diagram of how an API

request would flow through your application when you are using CQRS. So here you have an API request coming into your application, and let's say that this request is a command. A command is a type of request that updates the database, and in this case, I have a separate

database for commands, which is called the write database. Then I've got a way to project these changes into the read database, which is used to serve queries. Now, queries are API requests that are responsible for reading data only, and this is essentially what CQRS does; it

splits the flows for writing the data from the flow for reading the data. So we end up having the commands on the right side and the queries on the read side. Before the CQRS pattern was invented, there was the CQS pattern or principle. It stands for Command Query Separation,

and it focuses on individual methods on an object by distinguishing them into commands, which are methods that can change the state of a system but don't return a value, and queries, which are methods that return a value and don't change the state of a system. In other

words, queries do not have side effects. This definition is useful in the context of CQRS and it's the basis for the CQRS pattern. However, I don't consider it a definitive rule, especially when it says that commands can't return a value. This

is a rule that I will often break when I want to return an ID or some status code from a command, which is perfectly acceptable in my opinion. In the previous diagram, I showed you an example that was using multiple databases to implement CQRS. However, you don't have to do this.

You can start with just one database and implement CQRS on the logical level in your application. This is what that would look like on a high level. So, let's say we are splitting our application to commands and queries. On the query side, I could accept an API request, turn that

into a query object which will be handled by my query handler. I want the least amount of indirection as possible inside of my query handler, which is why something like Dapper fits really nicely if you are using a SQL database. So, let's say we just send SQL to the database and

return back the result from our API. So, notice how the flow is purposefully simple to focus on performance, which is the most important aspect for queries. You want them to be fast. And on the command side, we have a significantly more complex flow. We turn the API request

into a command which is handled by a particular command handler. Most of the time, I'm going to implement this using domain-driven design and the rich domain model along with NHibernate framework, which is my ORM of choice. NHibernate framework is going to use a repository or I can use EF

directly to hit the database and get back my domain entities which are going to execute the domain logic, and then I'm going to use any framework to persist all of these changes into the database. The benefits of logically splitting your application into commands and queries is

to promote the separation of concerns commands and queries have different requirements and you can focus on solving these requirements inside of the respective handlers secondly you can improve the security by controlling how much access commands and queries have to the database this also gives you the

ability to scale the read and write side of your application separately and this will often be the case because most applications are read heavy and very few applications are write heavy and now that you have a general idea of what CQRS is let's see how you can apply it

on a .NET project I'm going to show you how to implement CQRS in the application project of my Run Tracker solution and I'm going to start by creating my custom messaging abstractions which are going to be my commands and queries so I'll

create an abstractions folder and inside of it I'm going to create a messaging folder so let's start off by defining an interface which I will call ICommand so this is just going to be a marker interface that's going to define a command I'm going to use this interface

to represent a command that doesn't return a value and I also want to have an ICommand interface definition that does return a value so let's say that this is a TResponse and this is also going to be a marker interface in most implementations I will also add an I

BaseCommand interface and the reason for this is so that I can implement this interface with the remaining two interfaces and now I have a way to define generic constraints that can target both of the implementations of the IBaseCommand this is very practical if you're using something like mediator

to implement your commands and queries at runtime and you want to implement a generic constraint on mediators pipeline behaviors this is how you can achieve this for all of your commands by referencing the I base command interface and this will take care of handling the

two I command interfaces that I have here now that I have my commands I also want to implement interfaces for the respective command handlers so let's go ahead and define another interface this will be the I command handler and this interface is going to be a generic

interface accepting a T command argument and it's going to have one method inside so this will be an asynchronous method returning a task and I will call it handle it's going to have one argument which is going to be the command that this handler is handling and I'm also

going to accept a cancellation token because this is an asynchronous method an interface like this is a great opportunity to make all of my commands have a uniform return type and what I like to do is make them return the result I need to reference the shared

kernel project to be able to access my result class and now all of my command handlers have to return a result to specify if the command was handled successfully or return back an error if the command wasn't handled successfully I'm also getting a warning from Visual

Studio suggesting that I should make the T command argument to be contravariant I can achieve this by specifying in in my generic argument definition this isn't all too practical but what it allows me to do is to use this argument which accepts a T command and assign it

to a delegate that is expecting a more derived type of the command and one more thing that I want to do in the ICommandHandler interface is add a generic constraint that the T command should be an implementation of the ICommand interface so this takes care of one of

the two ICommand interfaces that I have and I'll add the ICommandHandler for the other ICommand interface which is the one returning a response I'll also make this contravariant in the generic argument I'll add a generic constraint that T command is an ICommand and I

want to be able to specify the T response of this command so I have to add that as another generic argument so let's say this is the response and I'll add that here and now I can specify the handle method so I'm going to reuse this

one here and what I'm going to do is make this handle method return a result of the response so I'm using the generic result variant as the return type of the handle method and this will allow me to tackle both types of commands once that

return just a result and once that sometimes need to return a specific value which is denoted with the T response generic argument so this covers our commands let's also take care of our queries so I'm going to add an IQuery interface this will be a generic

interface just defining what response this query is returning so it only has a T response generic argument and I'm also going to define an IQueryHandler it's going to take in a T query generic argument and the T response which is the one that is defined on my query let's

add a generic constraint that TQuery has to be an IQuery of T response and I can define the Handle method inside which is going to return a result of type T response. It will be called Handle, it will have the query argument and the cancellation token. So this is very

similar to what I had on the command handler, and of course I'm going to move the query handler into its own file. So what these interfaces allow me to do is to have a specific contract for defining my queries and my commands in the application. And I also have a

specific way how I'm handling the commands and the queries. And now let's implement an example use case which is going to be a command. I'm going to add a feature folder for my followers and I want to implement the use case which I'm going to add inside of another folder

which will be the start following use case. This use case is a command because it updates the database. So I'm going to add another class inside which is going to be the StartFollowingCommand. My personal preference is implementing commands using records because they are immutable and I can just define my

record using the primary constructor, and what I need to implement the StartFollowingCommand is the user identifier and the followed user ID. I also need to make this implement the ICommand interface that I just defined. The next thing that I will need is a respective command handler. So let's

implement this as a class. So StartFollowingCommand, I'm going to reuse the name, and then Handler. So this is a naming convention that I like to use. I can also implement an architecture test that's going to enforce this naming convention. This will implement the I

command handler interface and I can specify my command and I'm ready to implement the handle method on our interface which is going to hold my use cases logic so now what I want to do is to fetch the two users defined in my command the user that's trying to follow

the followed user and for this I'm going to define an interface for an I user repository because I don't have this definition in my domain project and I just want to expose one method on this repository that's going to return back a user instance so I'll have to reference

the domain project this will be a nullable user and I'll call it the get by ID async method it's going to accept just the identifier of this user and I can use this in my command handler so let's inject the repository from the constructor I'll inject the I user

repository and now I can use it in my handle method to fetch the user from the database I don't have to worry about the implementation of this interface because it's going to be provided to me at runtime so let's fetch the user it could be null and I'm going to call user

repository get by ID async I can use my command to provide the user identifier and also the cancellation token instance now I see that I forgot to add the cancellation token definition in my repository so let's go ahead and define it and I can even make this an optional

dependency on this method if I don't want to use it for whatever reason so the next thing is I need to check if this user is null by any chance so if the user is null I need to be able to return a result back from this command

Handler, and in this case I want to return a failure result, so I'm going to create a public static class that's going to hold my user errors. And how I'm going to implement the error instance in this particular case is by defining a static method that's going to be called

not found. It will accept a user identifier and it's going to return back a new error instance. So let's give it the error code of users not found, and the description will be an interpolated string saying that the user with the ID equal to the user ID

argument was not found. So this is enough to implement my user error, and now I can go ahead and say user errors not found, calling my static method, and I can provide it the user identifier. The reason I'm able to just return the error directly in my command handler without

referencing the result class is because I have an implicit operator on the error class converting this error instance into a respective failure result. So if I head back to my command handler, I need to implement the second step, which is fetching the followed user. So I'll say

await user repository get by ID, passing it the followed user ID, and I need to do the same check. So if the followed user is null, I'll return a user errors not found and pass it the followed user ID. The next step is to

implement the business logic for starting to follow a user in the system. This is taken care of in the follower service, which is a domain service, and it encapsulates all of the business logic required to implement this use case. So I can just reference this in my command

Handler by injecting the follower service so let's do that I'll add the follower service as a dependency and inject it from the constructor so now I'm depending on the user repository and the follower service and my handle method now needs to call this domain service so let's call follower service

start following async and we can provide it the user the followed user and the cancellation token it's going to return back a result and I can check if this is a failure result in which case I want to return back the error I got back from

this method so there are multiple ways how I can do this I can just return the existing result instance back I can return the error on this result instance which will be converted implicitly into a new result instance I just showed you how that works and I can also call

result failure the static factory method and provide it the error instance so let's say I want to go with this approach now I need a way to commit this entire business transaction and for this I will typically create an interface representing a unit of work so I'm going

to add a data folder here and add a new interface inside which will be an IUnitOfWork and it's going to have a very specific method inside that will be called save changes async now the reason I'm defining this method like so is so

that it matches the method on an EF core database context because I want to be implementing a unit of work using EF core and if I go back to my command handler I can add another dependency to my unit of work interface so let's reference the unit of work and I need to

inject it from the constructor, and now I can go back to my handle method and after making sure that this is not a failure result, I can commit this entire use case to the database by calling save changes, and finally I can return a success result to specify that this

command was handled successfully. Notice that I'm not referencing mediator or any external library here, and I can freely configure my command handler with dependency injection and then connect it to my command instance and find a way to execute them at runtime. The reason I prefer using mediator is because it

simplifies this entire process of connecting my commands and the command handlers, and it also has the request pipeline which I can use to implement pipeline behaviors, which is essentially an implementation of the middleware pattern allowing me to extend the behavior of my application when it comes

to queries and query handlers. There are multiple ways how you can implement them. The straightforward approach and the one I discussed in the diagram at the start of the video was using Dapper and writing a raw SQL query. You could also reference EF Core directly and write a

link query with a projection to return back your DTO. The difference is in commands, I'm going through my domain model and repositories so that I have more control over implementing the business logic. I'm also encapsulating business logic inside of my domain services and my domain entities, and I'm

relying on my ORM, which is EF Core, to process these changes to the database. Notice how this implementation is really testable. I can take my command handler class, mock these dependencies using Moq or NSubstitute, and quickly verify that my business logic is implemented correctly, and we can already start

validating the use cases without even having a running project. If you want to finish this CQRS implementation, take a look at this video here where I'm explaining how to implement CQRS with the Mediator Library. Thanks for watching this video and until next time,

How to Implement the CQRS Pattern in Clean Architecture (from scratch)

Hi there, my name is Milan, and welcome to my YouTube channel! 👋
My goal with this channel is to share my .NET and C# knowledge with you. I make videos about software engineering and software architecture, distributed systems, Domain-Driven Design, and any software-related topic I find interesting.

Milan Jovanović

아키텍처 패턴으로 설명되는 CQRS(명령 쿼리 책임 분리)입니다.

명령은 데이터베이스를 업데이트합니다(데이터베이스 쓰기).

쿼리는 데이터 읽기 전용(데이터베이스 읽기)입니다.

CQS(명령 쿼리 분리) 패턴과 비교.

시스템 상태 및 반환 값에 미치는 영향으로 구분되는 명령 및 쿼리입니다.

CQRS 구현 옵션: 여러 데이터베이스 또는 단일 데이터베이스(논리적 분리).

단일 데이터베이스로 논리적 CQRS 구현

쿼리 측면: 성능을 위한 간단한 흐름, Dapper와 같은 도구를 사용합니다.

명령 측면: 도메인 중심 설계, 풍부한 도메인 모델, NHibernate 또는 EF Core와 같은 ORM을 사용하는 보다 복잡한 흐름.

이점: 우려 사항 분리, 보안 강화, 읽기 및 쓰기 측의 독립적인 확장.

.NET 프로젝트에서 CQRS 구현하기

사용자 지정 메시징 추상화(명령 및 쿼리) 만들기.

반환값이 있든 없든 ICommand 인터페이스 정의하기.

매개자와 함께 일반 제약 조건에 IBaseCommand를 사용합니다.

반환 값 유무에 관계없이 ICommandHandler 인터페이스 정의하기.

IQuery 및 IQueryHandler 인터페이스 정의하기.

예시: StartFollowingCommand 사용 사례

시작 팔로잉 명령을 레코드로 구현합니다.

시작 팔로잉 명령 핸들러 구현.

IUserRepository를 사용하여 사용자 가져오기.

UserErrors를 사용하여 널 사용자를 처리하고 실패 결과를 반환합니다.

팔로워 서비스를 사용하여 비즈니스 로직 구현하기.

데이터베이스 트랜잭션에 IUnitOfWork 사용.

명령 및 쿼리 처리를 간소화하기 위해 매개자를 사용합니다.

미들웨어 패턴을 사용하여 파이프라인 동작 구현하기.

쿼리 핸들러 구현 접근 방식: Dapper, 투영 기능이 있는 EF Core.

모킹을 사용하여 구현을 테스트할 수 있습니다.