Exploring the CQRS Pattern in Web APIs with .NET Core

Introduction to the CQRS Pattern

The Command Query Responsibility Segregation (CQRS) pattern is an architectural approach that separates read and write operations in an application. This separation allows each operation to be optimized independently, leading to better scalability and performance. Instead of having a unified data model, CQRS proposes that write operations (commands) and read operations (queries) be handled in distinct ways (RICHTER, 2024).

CQRS is especially useful in complex and large-scale applications where business logic can be intensive and read operations can be optimized differently from write operations (RIBEIRO, 2024). In this article, we will explore how to implement CQRS in Web APIs using .NET Core, addressing concepts, components, and practical examples to facilitate the understanding of the implementation.

Origin of CQRS

CQRS is a pattern that emerged as an extension of the microservices architectural pattern, aiming to solve some of the challenges that arise when trying to scale applications that perform both read and write operations (AL FANSHA et al., 2021). The central idea of CQRS is to divide the responsibilities of reading and writing, allowing each to be optimized independently (RIBEIRO, 2024).

This approach promotes better organization of the code, as the parts of the system that deal with reading data do not need to worry about write logic, and vice versa. Additionally, CQRS allows different technologies to be used for reading and writing, leveraging the best practices and tools available for each operation.

CQRS is particularly advantageous in scenarios where the application needs to handle high volumes of data and a large number of simultaneous users (CHERIF et al., 2024). The separation of commands and queries not only improves performance but also facilitates maintenance and evolution of the system over time.

Basic Components of CQRS

In a CQRS architecture, we typically deal with three main components: commands, queries, and events. Let's detail each of them:

• Commands: These are operations that change the state of the application. Each command should be handled asynchronously to ensure that the application can continue to respond to other requests while waiting for the operation to complete.
• Queries: These are requests that retrieve data from the system without changing its state. Queries can be optimized to provide fast and efficient results.
• Events: These represent changes that have occurred in the system and can be used to notify other components or systems. Events are fundamental for implementing communication between different parts of the system and can facilitate integration with other external services.

Structure of a .NET Core Project with CQRS

To illustrate the operation of the CQRS pattern, let's consider a basic project in .NET Core. We will use the ASP.NET Core Web API. The implementation design will look like this:

+-----------------------------------------------------+
|                                                     |
|                     MyCQRSApp                       |
|                                                     |
+------+---------------------------------------+------+
       |                                       |
       |                                       |
+------v------+                         +------v------+
|  Command    |                         |  Get        |
|  Actions    |                         |  Actions    |
+------+------+                         +------+------+ 
       |                                       |
       |                                       |
+------v------+     +-------------+     +------v------+ 
|  Command    |     |  [Producer] |     |  Query      |
|    Bus      +----->  Async      |     | (IQueryable)|
|             |     |  Messages   |     |             |
+-------------+     +-------------+     +------+------+ 
       |                                       |
       |                                       |
+------v------+                     +----------v------+ 
|  Write DB   |                     |  Read DB        |
|  (Event     |                     |  (Projection/   |
|  Sourcing)  |                     |  Read Database) |
+-------------+                     +-----------------+ 

Below is the project structure:

MyCQRSApp
¦
+-- Application
¦   +-- Commands
¦   ¦   +-- CreateProductCommand.cs
¦   ¦   +-- CommandHandlers
¦   ¦       +-- CreateProductCommandHandler.cs
¦   +-- Queries
¦   ¦   +-- GetProductQuery.cs
¦   ¦   +-- QueryHandlers
¦   ¦       +-- GetProductQueryHandler.cs
¦   +-- Events
¦       +-- ProductCreatedEvent.cs
¦
+-- Infrastructure
¦   +-- Bus
¦   ¦   +-- CommandBus.cs
¦   ¦   +-- EventBus.cs
¦   +-- Persistence
¦   ¦   +-- ProductService.cs
¦   ¦   +-- ProductRepository.cs
¦   +-- Messaging
¦       +-- IEventBus.cs
¦       +-- ICommandBus.cs
¦       +-- InMemoryEventBus.cs
¦
+-- API
¦   +-- Controllers
¦       +-- ProductsController.cs
¦
+-- Domain
    +-- Models
        +-- Product.cs

Implementing Commands

The CQRS (Command Query Responsibility Segregation) pattern suggests separating read operations (queries) from write operations (commands). Let's start by implementing commands, which represent actions or state changes we want to perform in our system. Each command is a request to perform an action, such as creating or updating a resource. In the following example, we will create a command to add a product:

public class CreateProductCommand
{
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int Quantity { get; set; }
}

The CreateProductCommand command contains the properties necessary to create a product, such as name, price, and quantity. Now, we need a command handler, which will be responsible for processing this command and executing the associated business logic.

The command handler will be responsible for instantiating the product, adding it to the database, and then firing an event to notify that the product has been created. See how this works:

public class CreateProductCommandHandler : ICommandHandler
{
    private readonly ProductService _productService;
    private readonly IEventBus _eventBus; // Event bus to publish events

    public CreateProductCommandHandler(ProductService productService, IEventBus eventBus)
    {
        _productService = productService;
        _eventBus = eventBus;
    }

    public async Task Handle(CreateProductCommand command)
    {
        var product = new Product 
        {
            Name = command.Name,
            Price = command.Price,
            Quantity = command.Quantity
        };

        await _productService.AddProductAsync(product);

        // Publishes the event after the product is created
        var productCreatedEvent = new ProductCreatedEvent(product.Id, product.Name);
        await _eventBus.PublishAsync(productCreatedEvent);
    }
}

The CreateProductCommandHandler receives the command, creates a new Product object, and adds it to the database using the ProductService. After creation, an event called ProductCreatedEvent is fired, notifying other parts of the system that the product has been created.

The ProductCreatedEvent carries the information needed to notify the system that a product has been successfully created. This event can be subscribed to by other components of the system to perform subsequent actions, such as updating caches, sending notifications, or logging.

Implementing Queries

The next step is to implement queries. Unlike commands, which change the state of the system, queries are responsible for retrieving data. Let's create an example of a query to obtain the information of a specific product based on its ID.

public class GetProductQuery
{
    public int ProductId { get; set; }

    public GetProductQuery(int productId)
    {
        ProductId = productId;
    }
}

The GetProductQuery command contains the ID of the product we are looking for. Now we need a query handler, which will be responsible for fetching the product information.

public class GetProductQueryHandler
{
    private readonly ProductService _productService;

    public GetProductQueryHandler(ProductService productService)
    {
        _productService = productService;
    }

    public async Task Handle(GetProductQuery query)
    {
        return await _productService.GetProductByIdAsync(query.ProductId);
    }
}

The GetProductQueryHandler receives the query command and uses the ProductService to retrieve the product corresponding to the provided ID. This query can be optimized with techniques like caching, depending on the needs of the system.

API Controllers

With the commands and queries implemented, the next step is to create API controllers to expose these operations via HTTP. Below is a controller for products, with endpoints to create and retrieve products.

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly ICommandBus _commandBus;  // Command bus
    private readonly IQueryHandler _getProductHandler;

    public ProductsController(ICommandBus commandBus, IQueryHandler getProductHandler)
    {
        _commandBus = commandBus;
        _getProductHandler = getProductHandler;
    }

    [HttpPost]
    public async Task CreateProduct([FromBody] CreateProductCommand command)
    {
        // Sends the command to the command bus
        await _commandBus.SendAsync(command);
        return Ok();
    }

    [HttpGet("{id}")]
    public async Task GetProduct(int id)
    {
        var query = new GetProductQuery(id);
        var product = await _getProductHandler.Handle(query);
        return Ok(product);
    }
}

The ProductsController exposes two endpoints: one for creating products with the POST method and another for querying products with the GET method. The controller interacts with the command and query buses to delegate the appropriate operations.

Event Management

CQRS is also often used in conjunction with events, where the execution of a command triggers a corresponding event. These events can be used to notify other parts of the system about state changes. In the example below, we will create a ProductCreatedEvent that will be triggered after a product is created.

public class ProductCreatedEvent
{
    public int ProductId { get; private set; }
    public string Name { get; private set; }

    public ProductCreatedEvent(int productId, string name)
    {
        ProductId = productId;
        Name = name;
    }
}

This event contains information about the created product, such as its ID and name. After the product is created, the event will be published so that other components of the system can react to this state change, such as updating caches, sending notifications, or performing other integration actions.

The publication and subscription of events can be managed using libraries like MediatR, RabbitMQ, Azure Service Bus, or other messaging-based solutions. The use of events improves the scalability of the system, allowing it to react more dynamically and flexibly to changes in the state of the system.

Challenges and Considerations When Implementing CQRS

Despite the advantages of CQRS, it is important to be aware of some challenges that may arise when implementing it. The additional complexity that CQRS brings can be a hurdle, especially in smaller projects or in teams with less experience with the approach. Managing states and synchronizing between read and write components can become complicated, requiring good planning and a well-defined architecture.

Clear communication among team members is essential to ensure that everyone understands the responsibilities and how each component interacts with the others. Additionally, it is advisable to have good monitoring and logging in production to quickly detect issues.

Conclusion

The CQRS pattern offers a powerful way to structure complex applications by separating the concerns of reading and writing. By implementing CQRS in a .NET Core application, you can create more scalable, flexible, and high-performance APIs. Although implementing CQRS can add complexity, the benefits in large-scale applications often outweigh these challenges.

In the end, adopting CQRS should be an informed decision based on the specific needs of your project. With the right practice and experience, you can make the most of this pattern and build applications that meet the growing demands of today's market.