DEV Community: Darjan Bogdan

Command & Query: Domain - Validation

Darjan Bogdan — Tue, 18 Aug 2020 06:15:47 +0000

The story is a part of the series about software architecture powered by command-query separation principle and aspect-oriented programming.

Data validation

With the request handler mediator explained and implemented in the previous post, all the prerequisites are in place to start building reusable generic components. Such components, that model specific cross-cutting concerns, fit nicely into the architecture this series is talking about.

Even though modeling cross-cutting concerns in OO languages is challenging and may lead to tightly-coupling, the request handler abstraction provides necessary tooling to make it simple and right.

Implementing cross-cutting concerns using a Decorator design pattern around the generic interface IRequestHandler<TRequest, TResponse> along with generic type constraints, enables non-intrusive, conditional, and dynamical addition of certain behavior to an individual handler instance. The complete solution is, reasonably, powered by a dependency injection container, which covers responsibility for the creation and management of such instances.

Validator — definition and model

It’s natural to start with the data validation, as the first concern to implement around the mentioned interface. Dealing with corrupt data and ensuring data input correctness is a known topic and can be achieved in many ways; starting from in-lined conditional statements to dedicated methods to specialized objects with, sometimes, complex hierarchies.

In this case, the validation logic will be enclosed into an object with a single responsibility to validate data. Objects responsible for validation are going to implement a simple generic interface with a single method that takes some data as input and returns a result of the validation:

public interface IValidator<in T> 
{
    ValueTask<Result<bool>> ValidateAsync(T data, CancellationToken ct);
}

This simple abstraction covers a large variety of cases and validation needs. It has certain characteristics and design decisions worth explaining:

No generic type constraints — gives room to validate any type of data in C# (except pointer types).
A contravariant generic type parameter in T — enables reusability if T is a derived type, and there are already validators for its base (less derived) type. This is especially helpful for chaining validators in collections, such as IEnumerable<IValidator<T>>.
Asynchronous method returns ValueTask<T>, instead of Task<T> — removes allocation overhead when an asynchronous method returns synchronously, which is often a case for data validation logic. Additionally, it removes the need to have two distinct validation methods (Validate and ValidateAsync) to achieve the same possibilities.
Async ceremony on the side, the validation method returns Result<T> data structure — provides more predictable method behavior and easier error data propagation. The method doesn’t throw an exception when validation fails, and error data is always stored in the Error instance, retrievable by Match<T> method.

Validation decorator — model

With the basic validator abstraction defined, it’s straightforward to implement the generic validation decorator around request handlers. It will internally use and orchestrate validators to process them in the sequence. Therefore, the order of instances in a validator collection does matter.

Use the dependency injection container which guarantees the order of supplied registered types in a collection of types.

It’s clear that the given validation interface doesn’t suit all the needs in the field, the same way the proposed decorator won’t cover all the validation scenarios some business logic or existing code could dictate. Still, the great thing about this architecture is the possibility to create different validation decorators with their own rules and behavior (e.g. concurrent processing), and easily use them side by side or even exclusively.

Implementation could look something like this:

It’s important to notice how ValidationDecorator has only one generic type constraint (TRequest: IRequest<TResponse>) dictated by the interface it implements. When added to the composition root, this kind of decorator will always be applied to any IRequest<TResponse> object. Since that’s the base interface, each TRequest instance sent to its handler is going to be validated by this logic.

When determining how certain behavior is going to be applied, there are usually three approaches:

Required (always-on): behavior is applied to every request handled by a corresponding handler. There is no possibility to exclude a decorator dynamically. Excluding decorators from the DI composition is the only way to avoid them. No additional coding, easy to implement.
Required (opt-out): behavior is applied to every request handled by a corresponding handler. There is a possibility to exclude decorator statically or dynamically. Requires custom coding, complex to implement if seeking for an all-round good solution.
Optional (opt-in): behavior is applied only to requests which implement a specific flag interface. The interface is used as a decorator’s additional type constraint imposing a requirement for request types to fulfill in order to be processed.

Personally, I recommend the opt-in approach as a rule of thumb, even if it leads to a higher number of interfaces to deal with. It’s simply easier to work with a set of behaviors and pick only the suitable ones to use for a given request. Also, the opt-out approach isn’t easily implemented and may lead to the coupling or hard-coding (e.g. request type checks inside decorator to skip part of the logic). The only always-on behavior which is going to be covered in the whole series is validation due to its nature. Working with a valid request instance is a must, thus validation decorator is mandatory. That’s the only reason why the proposed solution doesn’t use a custom-tailored flag interface as a constraint.

If that’s not preferable, a simple IValidatedRequest empty flag interface can be introduced and added as a decorator’s type constraint. That enables the opt-in approach for the request validation as well. Simply, a custom TRequest type can optionally implement a specific interface to activate a decorator that handles IValidatedRequest types.

Last thing worth pointing out is an implicit conversion which makes it possible to directly return Error instance instead of Result<TResult>. Once the result is calculated by ValidateAsync method, error can be extracted using Match<T> method and, finally, returned.

Essentially, on top of two additional types, ValidationDecorator<TRequest, TResponse> and IValidator<T>, it is possible to build custom validators for any TRequest. The decorator will make sure to invoke it before execution reaches the handler for specific TRequest — it’s that simple!

DataAnnotations Validator — model

There is still a need to implement validators for each request. That can be a tedious process, especially implementing validation logic which is repeatable like null or empty checks or max length checks. Basically, any input validation logic is monotonous to deal with.

For that matter, DataAnnotations library comes as a solution quite naturally. It’s just needed to implement a generic validator that will use DataAnnotations to validate objects. Afterward, simply decorate the objects’ properties with validation attributes, and thing happens:

This simple example serves the purpose and is capable to validate any object (e.g. CreateUserCommand) passed into it. It will either return Error with appropriate data about validation failure or true if the validation is successful. Note that nested properties validation is missing, but it can be added by extending base attributes from DataAnnotations library.

FluentValidation Validator — model

Often simple input validation isn’t enough to ensure the data correctness on a domain level. Sometimes it’s necessary to (asynchronously) fetch additional data from a remote source like a database, or validation logic is composed of smaller, more specialized components (dependencies). In such scenarios, validation via attributes is simply not powerful enough, System.Attribute type specifics make it inconvenient to use in more complex cases.

FluentValidation library is a good choice when it comes to more complex, domain validation logic. It supports asynchronous processing, has rich feature-set and intuitive API to use.

To fit it, it’s necessary to create an adapter which derives from the base AbstractValidator<T> class and implements the new IValidator<T> interface:

AbstractFluentValidator<TRequest> is deliberately an abstract class to retain the same API interaction as the original library requires. It’s still needed to inherit the class to define validation rules inside the constructor, but the new class also makes derived validator compatible with the ValidationDecorator:

While FluentValidation library offers the possibility to write a fully custom code via dedicated methods, there might be cases in which there is no need to introduce a new library (or not an option) due to the existing validators and other validation components.

To reuse them along with other validators, each legacy validator needs to have its own adapter that implements IValidator<T> interface. Since only one method needs to be added, implementation is usually straightforward.

With all three validation approaches in place, the data validation responsibility can be completely moved away from the central handler logic. That makes the handler clean and more readable as the validation clutter is relocated elsewhere.

A higher level of encapsulation and clearer responsibility separation naturally raise performance concerns which shouldn’t be neglected. They can be tackled in many different ways; from multi-level and hybrid caching to contextual data propagation and exchange. To give an example, optimizing interaction with remote sources (database, web API, …) leveraging caching, reduces the number of expensive (slow) and volatile network roundtrips. Even if the approach can give a significant/positive impact on a general performance, it comes with the cost and must be carefully weighed.

Pipeline composition example with SimpleInjector

The last thing to cover is the object graph composition with the help of SimpleInjector DI container. The setup shown below gives a sort of pipeline-like composition in which every request goes through the validation component first, continuing as a validated request to the corresponding handler:

Due to SimpleInjector’s powerful support for open generic types registration, it is possible to define the order of instances in a collection of types resolved by the container. In other words, IEnumerable<IValidator<T>> is always resolved into collection of ordered validators which are able to handle some type T.

In the case of CreateUserCommand, validation will be done in the following order:

DataValidationValidator — validates input data; ensures that both property values are set, Name not longer than 25 characters and Email valid.
CreateUserEmailValidator — validates domain requirements; ensures that Email is not used.
CreateUserNameValidator — validates domain requirements using “legacy” logic; ensures that Name is allowed to use.

In the case of another arbitrary UpdateUserCommand, validation order would start with DataValidationValidator, continuing with reusable and/or dedicated validators for that type in the guaranteed order as well.

To conclude, with data validation components in place and flexible composition, it’s matter of creating a request and handler to handle some domain logic, possibly creating additional classes to cover specific validation behavior and run the code. There is no need to change or adapt anything else (Open-closed principle), especially not composition root, which should be the ultimate goal when working with DI containers.

In the next chapter, new cross-cutting concern and decorator will be covered, stay tuned to find out which one.

All the gists, examples or solutions will be done in C# using the latest .Net Core/Standard versions and hosted on Github.

Command & Query: Domain - Mediator

Darjan Bogdan — Tue, 18 Aug 2020 06:15:28 +0000

The story is a part of the series about software architecture powered by command-query separation principle and aspect-oriented programming.

Example powered by requests and handlers

In the preceding chapter, the base model, which represents commands, queries, and their handlers, was explained and implemented as an abstract model in C#. Since the model consists of essentially two interfaces, it’s possible to provide a large variety of implementations making it suitable to model many business domains.

Simple user management will be taken as an example of one. Using the mentioned model as a backbone, many different actions on the user object will be implemented. To keep it clean and simple, only the user’s unique identifier and name are properties in focus. The class itself could be easily expanded or completely changed based on the business domain’s needs.

public class User
{
    public Guid Id { get; set; }
    public string Name { get; set; }
}

To implement the logic for getting a single User using its identifier, it’s necessary to implement two interfaces in separate classes. An instance of one class holds the data needed to perform a task, an instance of another holds the business logic to perform a task.

GetUserQuery class implements IRequest<User> and carries the user identifier needed to get the user successfully. GetUserQueryHandler class, on the other hand, implements IRequestHandler<GetUserQuery, User> interface and has a method that performs the logic to get the user from some source. Simply, the method gets GetUserQuery object, passes UserId to the GetUserFromSource method to fetch the user and returns the retrieved User object. Data fetching and materialization are not in the focus at the moment, so GetUserFromSource could be virtually anything.

Following the example, the other actions on User object could be implemented similarly, using the same pair of generic interfaces or their derivatives such as IRequest and IRequestHandler<TRequest>.

Having all the handler implementations in place, with the help of a dependency injection container, each handler instance can be injected into another class. A typical Web API controller would look something like this:

What immediately comes to attention is the constructor over-injection smell, and as such should be avoided or reduced to a minimum, especially if it would appear regularly.

Mediator — definition and model

Instead of individually injecting instances of closed generic interfaces, a single non-generic interface with a generic method shall be used instead. Implementation of such interface serves as a mediator between any caller and any request handler, effectively decoupling them from each other and completely removing the initial code-smell.

Although IRequestHandlerMediator seems like a reasonable choice to name such interface, I prefer to use IBus only because the base model can be furtherly expanded using various handler decorators to form a pipeline and/or in-process bus.

The initial version of the interface and class implementation could look like this:

As mentioned earlier, Bus implementation serves as a mediator, with the responsibility to invoke Handle method on a correct handler instance. Handler instantiation is usually managed by a dependency injection container, so instanceFactory function delegate is passed into the constructor as the only dependency of the implementation. It simply takes Type argument and returns an instance of that type as an object.

While looking simple and straightforward, to invoke SendAsync method both type parameters must be explicitly defined, which makes the usage inconvenient:

var query = new GetUserQuery();
var user = await bus.SendAsync<GetUserQuery, User>(query, default);

For a reason C#’s type inference doesn’t take return types into account, as a matter of fact, it fails immediately per specification:

If the supplied number of arguments is different than the number of parameters in the method, then inference immediately fails. — C# Language Specification, Version 5.0, § 7.5.2 Type Inference

Still, explicitly defined type parameters look noisy, especially when used frequently, with long descriptive type names. Considering that both query and response types are known at compile-time, writing simple clean code with type safety in place should be achievable:

var query = new GetUserQuery();
var user = await bus.SendAsync(query, default);

To make the usage more pleasant, redundant data needs to be avoided meaning the SendAsync method signature needs to be adapted:

TRequest type parameter removed — to match the number of method parameters and arguments
Type of request argument changed to IRequest<TResponse> — to keep the same type constraint

With the constraints in place, implementation draft looks like the following:

Conforming to type inference rules leads to more complex implementation because the concrete type of request argument is unknown at the compile time. The absence of the type makes it impossible to construct the closed generic handler type which is required to get the correct handler instance via instanceFactory delegate.

There are different ways to solve the problem. For example, in MediatR library internal generic handler wrappers are used to solve the same issue.

In this case, only Delegates and Reflection are used to fill the gap. To have a reasonable solution, a few requirements and limitations must be met:

Simple enough to be easily maintainable
Performance in-line with existing solutions to be usable
No handler instance caching to avoid captive dependencies

For simplicity, a naive implementation is shown, while a more comprehensive and optimized solution with safety checks and error handling in place can be found in Pype repository:

The simplest way to solve the problem is to reintroduce the initially implemented SendAsync<TRequest, TResponse> method with the small, but important difference. The type of request argument is object, not TRequest anymore.

The side-effect of casting back to TRequest is neglectable to the benefits of using closed instance delegate — to achieve fast and type-safe invocation via SendAsyncDelegate<TResponse> delegate. It wouldn’t be possible to use it if the argument’s type remained TRequest.

Mediator — implementation benchmarking

There are many different ways to invoke SendAsync<TRequest, TResponse> function without knowing type parameters at compile time, some are:

MethodInfo.Invoke (src) — type unsafe method invocation via reflection
Delegate.DynamicInvoke (src) — late-bound method invocation
dynamic Invoke (src) — non-statically typed method invocation
delegate Invoke (src) — type-safe encapsulated method invocation
Func Invoke (src) — invocation of Func delegate type
Expression Invoke (src) — constructing and invoking lambda expression via expression trees

Using dedicated delegate type (as shown in the example) which represents the reference to the SendAsync<TRequest, TResponse> method is the most performant one. Based on a simple benchmarking using dummy PingRequest and PingResponse:

Besides the mentioned approaches, Generic invoke presents the benchmarking of the initial version — the one with inconvenient API. It serves as a reference point to evaluate whether the trade-off between performance and convenience pays off.

Data sets (series) in the diagram are representing:

Simple — a naive implementation for different method invocation approaches. As expected, each is slower by order of magnitude in comparison to the direct method invocation. In the case of expression trees, it’s even worse.
Optimized — a reasonable implementation using caching where possible to avoid usually expensive interaction with System.Reflection namespace. The instantiation of methods, delegates, expressions or lamdas is completely mitigated by caching, invocation itself is almost the only thing that counts.

Although the best approach is still more than 2 times slower than the reference point, in absolute terms it’s only ~70ns slower which is negligible in most of the cases. Based on that and the benchmarking comparison with the other libraries, it’s safe to conclude that this kind of solution is efficient enough to be used on a daily basis.

To conclude, it’s always nice to see that extra effort to make a more convenient API paid off eventually:

Handler instances don’t have to be injected into their consumers, which makes their constructors slim-fit.
Handlers are completely decoupled from each other and the rest of the system which makes it more maintainable.
Handler invocation through IBus mediator comes with proper type inference support which makes the usage simple and code clean.

Finally, the fun part is reached, with the base model and mediator in place, it’s possible to expand the whole concept with many different cross-cutting aspects which will naturally fit into the whole picture. One of them, data validation, is covered in the next chapter.

All the gists, examples or solutions will be done in C# using the latest .Net Core/Standard versions and hosted on Github.

Command & Query: Domain - Abstract Model

Darjan Bogdan — Tue, 18 Aug 2020 06:15:01 +0000

The story is part of the series about software architecture powered by command-query separation principle and aspect-oriented programming.

Abstract model in software — where, when and why?

Software problems which share common characteristics could be represented and associated with an abstract model, as a backbone for building generic, reusable solutions. It definitely is challenging to discover such abstractions as a basis to build a usable software model — it requires a lot of effort, time and experience.

Abstraction is the amplification of the essential and the elimination of the irrelevant. — Robert C. Martin, Agile Principles, Patterns, and Practices in C#

There are many fields in mathematics which are typically a good foundation to form an abstract model and finally build a generic solution for a particular or more general problem space. As an example, graph theory is usually the basis for any valid graph representation, structure or model in software. Validity comes from the fact that theoretical definitions are embedded in abstract software models to guard a defined set of laws and provide a predictable interface to a consumer. Ultimately, a well-implemented model can serve as a generic solution for the same problems in the technical domains belonging to different business domains, such as data storage, social networking or communication networks.

Another, more advanced example is the influence of the category theory in functional programming. The theory itself focuses on identification and formalization of a category as a mathematical structure. A category is a graph which represents abstractions of other mathematical concepts and consists of objects (nodes) and their morphisms (arrows). Even though the theoretical concept is quite broad and abstract, some functional programming languages, like Haskell, took advantage of such high-level abstractions, embedded their rules into core language features, and adopted terminology.

How will individual abstraction be truly accomplished in the context of programming language or particular framework is solely up to abstract models’ implementation characteristics. Since source code implementation is opinionated, it’s not surprising that theoretical model realization could vary a lot. It is influenced by many things — to give a brief idea, some are:

Language paradigm — object-oriented, functional, event-driven …
Language features — type system, generics, pattern matching …
Framework features — concurrency, collections, garbage collection …

Determining the right implementation direction is quite challenging, but most importantly it’s rewarding since it’ll make a certain theoretical concept easy to apply and intuitive to use in every-day development.

To support the statement, a good example would be the async/await feature’s advancement in C#. Asynchrony, as a theoretical concept is a well known and hot topic in computer programming. However, every language or framework which supports async programming has own way of achieving it. In other words, each has a different way to implement and expose a meaningful and intuitive API for the developer. In fact, C#/.NET supports 3 different approaches.

It is known that asynchronous programming in .NET gained tremendous popularity once async/await was incorporated into C#, powered by the already existing TPL. The reason is that developers eventually managed to form a software model based on the complex theoretical concept, with intuitive API — to use seamlessly within the context of language and framework.

Just remember how adventurous, hard to maintain and error-prone was asynchronous programming in C# without first-class compiler support, or even before, without first-class library support. Pursuing “asynchronous all the way” principle using earlier patterns (models) was much more complex and rare due to the lack of intuitive API.

It’s fair to mention that such a powerful generalization comes with the cost, and definitely, in essentially complex domains it might be needed to “fallback” to the lower-level models which usually expose a certain degree of implementation details to expose necessary extensibility and configurability (e.g. TaskFactory.StartNew, Task.Run methods, BeginX/EndX pattern).

In conclusion, it was quite challenging to accomplish the current state of the first-class async support in .NET, since it was gradually developed over the years. At the same time, it was rewarding because of the widespread acceptance of the “new/old” async feature in the .NET realm. Besides, it became a de facto standard when dealing with asynchronous domains like HTTP servers.

Command and Query — definition and model

Unlike the complexity of async domain space, CQS principle can be quite simply, yet powerfully modeled to provide a succinct, meaningful and intuitive API to work with.

To begin with the definition, Command is a method that performs an action which mutates the domain’s state or has any kind of side-effect. In addition to that, it doesn’t return anything. On the other hand, Query is a method that performs an action which queries the domain’s state, doesn’t produce side-effects and returns data.

In both cases, there is a given set of rules (characteristics) which any method should adhere to, in order to be classified as one or the other. Moreover, there is a possibility to define the base abstract model which would guard the rules and embed characteristics into the source code, providing a necessary tool in hands to start taking the real advantage of a theoretical principle.

Fair to say, it’s not mandatory to build a software library which supports the concept to start applying it daily. In many cases, even following the rules would be beneficial.

But, having a reusable library built to support a certain principle gives additional room for improvements and a natural upgrade of the whole concept. As described in the introductory article, commands, queries, and their handlers could be represented using only a few generic interfaces, but they can serve as a base ground for the architecture which effortlessly supports building the software components following SOLID principles and AOP paradigm.

Contrary to the mentioned abstract model which includes separate interface pairs for commands and queries, I find it more useful to unify them into a single pair. One interface to represent both (command and query), commonly called request, and another to represent the corresponding request handler.

I’m not the greatest fan of the term either. Firstly, it deviates from the terminology coined by CQS principle. Secondly, due to the possible association with the completely different concepts in other domains (e.g. HTTP request). Nevertheless, I finally came to terms with it by simply moving the name distinction to the classes which implement before-mentioned interfaces (e.g. CreateUserCommand : IRequest<TResult> and CreateUserCommandHandler : IRequestHandler<CreateUserCommand, TResult>). After all, the whole abstraction is about commands, queries and their distinction — it’s worth to incorporate it somewhere.

So, the main goal is to have only two base interfaces on top of which other elements will be built, something like:

interface IRequest<TResult> 
{
}

interface IRequestHandler<TRequest, TResult> 
    where TRequest : IRequest<TResult>
{
    Task<TResult> HandleAsync(TRequest request, CancellationToken ct);
}

One could immediately say that this abstract model violates, not only the terminology but also the rules (command has a return value!) defined by the abstract principle — and one would be right. However, I’m completely fine with that deviation, I’m seeing it as a reasonable theoretical model approximation caused by several (technical) limitations:

async/await feature requires a method to return Task/Task<T> objects to be awaitable — async void Handle(){} isn’t awaitable and exceptions can’t be handled in the same execution context.
void (System.Void) can’t be used as a generic type parameter nor can be passed to a method — Task<void> isn’t allowed.
Variance is supported by generic interface and generic delegate types only — class HandlerDecorator<in TRequest, out TResult> isn’t valid.

Despite some limitations, it’s still quite important to support asynchronous programming using widely adopted TAP pattern. That effectively means that interface methods must return Task and/or Task<T>.

Although, it seems that Task HandleAsync(T command) method would be appropriate to use for commands in asynchronous domains, it still involves violation of the principle rules. The method returns an instance of a Task type, which holds the information about the method’s execution (status, exception, identifier…) and doesn’t make it truly fire-and-forget anymore. Furthermore, it would hurt reusability because it’d still be needed to have two separate interfaces for command and query handlers.

To keep the possibility to represent a method which doesn’t “return” anything when having Task<T> as a return type, the special Unit structure must be implemented. That type indicates the absence of a specific value and often is a built-in type in functional languages, like F#.

Having that in place, it’s straightforward to implement any handler which represents command or query, using the same IRequestHandler<TRequest, TResult> interface:

The main benefit of the singular approach lies in the possibility to reuse the same (cross-cutting) components in both cases, considering that commands and queries could share the same characteristics. Like the way of validating or authorizing them before execution, or maybe the way of preserving audit trails, or rate-limiting, and so on.

Consider the following example, to implement a generic validation component for handlers, it is just necessary to build a decorator around a single IRequestHandler<TRequest, TResult> interface. Otherwise, it requires practically two of them, one for ICommandHandler<TCommand> and another for IQueryHandler<TQuery, TResult>.

Similarly, any other aspect could be implemented (e.g. authorization, caching, …) as a single place in the code which handles the particular cross-cutting matter.

It’s not only possible to chain or compose multiple decorators to technically form a request pipeline, but also to conditionally apply them (generic type constraints, attributes), and automatically resolve them using inversion of control techniques.

Result — definition and model

The last thing which I find important to address and (optionally) incorporate into a base model is exception handling or plainly error data propagation.

While it’s not mandatory to have it in place, I think it is important, especially in cases when structured error data (e.g. validation failure reasons) need to be communicated back to an API consumer.

Due to the fact that it’s not possible to have more than one return type in method signatures in C#, and because there is no first-class support for discriminated unions, the easiest and the most straightforward way is to use and extend built-in exception types. So, if there is a need to return some heterogeneous data from a method, one part can be simply propagated within (custom) exception types and just thrown from a method.

Still, structured error data should be treated as part of a domain, and as such should not be included inside a regular exception handling process. Besides, it’s not recommended to throw exceptions in non-exceptional scenarios (e.g. wrong input, token expiry), it makes error handling vexing since exceptions must be handled all the time.

It’s possible to avoid using custom Exception as a carrier of the domain-related data, by “borrowing” and implementing generic Result structure, usually found in functional-first languages.

There are many different ways to implement structure alike in C#, as it is usually based on Church-encoded Either abstraction, which is represented with a single interface method:

interface IEither<TLeft, TRight>
{
    T Match<T>(Func<TLeft, T> left, Func<TRight, T> right);
}

For the sake of clarity and intuitiveness, instead of using highly abstract Either term, Result will be used. The name more closely describes the intent and is more fitting in every-day conversation.

If incorporated as-is into the request handler interface, three generic type parameters must be exposed (i.e. IRequestHandler<TRequest, TResponse, TError>) which adds additional complexity to the model. Also, the whole interface looks quite tedious to work with.

Most of the times, such a degree of model extensibility isn’t required at all and unification of all errors under common type is recommended — there is rarely a need to work with different error types. In that case TError generic type parameter can be omitted and suitable non-generic Error type used instead — making the generic Result class simpler and final version of handler interface cleaner:

interface IRequestHandler<TRequest, TResponse> 
    where TRequest : IRequest<TResponse>
{    
    Task<Result<TResponse>> HandleAsync(
        TRequest request, 
        CancellationToken cancellationToken
    );
}

There are many quality-of-life details which could be added to the abstract model to furtherly enhance every-day usage, such as implicit conversion into Result<T>, set of various helper methods, more derived interfaces, etc.

All these details can be seen in the more comprehensive and complete model shown in Pype repository. The repository will be gradually expanded with the components which will be covered throughout the article series.

Besides that, it’s worth mentioning MediatR and Microbus libraries which are modeling the same principle, both providing similar generic interfaces, but each has some specifics and additional features.

In the next chapter, request handler mediator and request pipeline composition will be covered!

All the gists, examples or solutions will be done in C# using the latest .Net Core/Standard versions and hosted on Github.

Command & Query: Domain - Introduction

Darjan Bogdan — Tue, 18 Aug 2020 06:13:48 +0000

The story is a part of the series about software architecture powered by command-query separation principle and aspect-oriented programming.

Introduction and motivation

Reading through discussion threads about CQRS pattern, I often get the feeling that the general impression about the topic could be summarized into the following:

The whole concept seems pretty reasonable, and the idea behind it solid, but it looks like overkill for non-enterprise projects, I’d rather stick to…

Although I do understand such reasoning, I still think that initial skepticism is rooted in the fact that there is no clear way of taking advantage of a higher abstraction which sits behind the pattern. It simply feels that the implementation effort is too great and doesn’t pay off in “smaller” code bases. However, I strongly disagree with that.

Particularly, I think the size of a project shouldn’t be a determining factor to choose a certain approach, but rather its domain flexibility and compatibility. While it’s pretty much clear that there is no single architectural pattern (principle, abstraction) which would perfectly fit any domain, in a plethora of cases, CQS principle could be adapted and fairly successfully applied.

At first, I was suspicious to use the pattern in a production world, especially since the Domain model or classical N-layered approaches felt much closer and overall friendlier.

At that time, I simply didn’t know that Command and Query Separation principle, as an abstraction, could be modeled quite powerfully. The whole concept could be represented using a few interfaces in C#, for example :

Examining such model, thoroughly described in the Meanwhile… on the command/query side of my architecture posts, Chapter 10 of the Dependency Injection Principles, Practices, and Patterns book and others, it quickly becomes apparent how adaptable and flexible it is. In addition, carefully designed interfaces restrict the developer from abusing such a general principle and give core building blocks to accomplish greater and more complex architectures.

Developers have all the freedom to tailor a software solution to its domain’s needs. Practically, no other factors dictate that it must be a fully-fledged CQRS solution with distributed persistence stores and messaging bus in between. Therefore, there is no single reason not to (try) to apply a CQS principle in a project which is not of “enterprise” size, once the concept becomes clear enough.

It’s obvious that the implementation complexity of a certain theoretical pattern is influenced by the developer. When needed it’s acceptable to do a trade-off between the purity of theoretical concept and practical implementation. Especially, if it would enhance maintainability and reduce the overall complexity of the code base.

The whole series will be focused on showing and exploring practical implementation of CQS principle, built around a generic model which doesn’t fully follow the theoretical concept. The most surprising thing is that you could be perfectly fine if the Command returns a result, however under certain rules and discipline.

Many topics will be addressed along the way. Essential parts first — to get a general understanding of the approach, and then, gradually, other building blocks will be incorporated into the whole picture.

Series should act as a hands-on guide to the world of commands and queries. Starting from the base model introduction and later extending it with many cross-cutting aspects, molding it into a data processing pipeline.

The goal is to understand how to assemble a typical API server using the following building blocks:

Command and Query
Cross-cutting Aspects
Pipeline and Context
Messaging and Eventing

For each concept, feasible models will be presented and described, including their pros and cons. Even though the implementation is usually opinionated, I’ll try to keep the spotlight on the parts which are more or less universal and only explain important details of the underlying technologies and/or libraries.

Ultimately, the whole code base should adhere to SOLID principles practically out of the box which again leads to many great things like modularity, maintainability, reusability and many more.

In the next chapter Command and Query’s abstraction will be examined and the base model described, on top of which other parts will be built.

All the gists, examples, or solutions will be done in C# using the latest .Net Core/Standard versions and hosted on Github.