DEV Community: David Pereira

A simple template for Onion Architecture with .NET 5

David Pereira — Thu, 04 Feb 2021 11:00:31 +0000

Just wanted to share a simple approach for Onion Architecture that has saved me a lot of time engaging productivity for everyone on my team.

Quick Reminder

If you couldn’t check my series about Clean Architecture feel free to take a look at them (sorry for the spam):

My simple template for Onion Architecture with .NET 5

Clean architectures are awesome, I don’t have any doubt about that. Highly scalable, fully testable, easy to evolve, easy to adapt to new requirements, etc etc etc.

But unfortunately, I must say that they are not for everyone. If you start adding Input Ports, Use Cases, Output Ports, Presenters, and also adding a DDD approach together with CQRS and Event Sourcing you are adding a kind of steep learning curve for newcomers or people without deep knowledge about good practices, clean code, and related stuff.

And that’s completely fine when you work in a team you need to work as a team, understanding everyone’s point of view and trying to grow all together.

So, how did I try to solve this? How did I promote the usage of good practices in terms of architecture especially when building microservices or serverless functions without overwhelming with a ton of new concepts?

I created this template:

pereiren / dotnet-template-onion

Onion Architecture with .NET 6/.NET Core and CQRS/Event Sourcing following a DDD approach

dotnet-template-onion

A .NET/.NET Core template to use Onion Architecture and DDD (Domain Driven Design) with CQRS and ES with a simple example on how to use all this architecture together from the Controller until the Repository class using Domain objects and different patterns.

Documentation

You can find information about this template in:

Prerequisites

.NET 6

Ensure you have the correct dotnet-core SDK installed for your system:

https://dotnet.microsoft.com/download/dotnet/6.0

This is just the version used by the template, if you need to use a newer or older one, you can do it manually after.

Usage

Clone this repository
To allow the api to be created you will need to install the template from nuget:

dotnet new -i {{Path_where_you_cloned_the_repository}}

Example:

dotnet new -i C:\GitLocal\dotnet-template-onion

To check that the template has been installed successfully:

dotnet new -l

There should now be a new template dotnet_template_onion

…

View on GitHub

It’s just a simple Onion Architecture with CQRS and Event Sourcing. You can use it as you want, you can create a GitHub repository using the template from there or just doing a fork/clone and creating the template from the dotnet CLI.

Just to understand it better I created this diagram which tries to explain everything that can happen in the code:

High Res: https://raw.githubusercontent.com/pereiren/dotnet-template-onion/master/images/dotnet-onion-ddd-cqrs-es.jpg

This is the structure tree of the repository:

C:.
│   .gitignore
│   Dotnet.Onion.Template.sln
│   README.md
│
├───docs
│       ARCHITECTURE.md
│       CQRS-ES.md
│       DDD.md
│       HEXAGONAL.md
│       SOLID.md
│
├───images
│       dotnet-onion-ddd-cqrs-es.jpg
│
├───src
│   ├───Dotnet.Onion.Template.API
│   │   │   .dockerignore
│   │   │   Dockerfile
│   │   │   Dotnet.Onion.Template.API.csproj
│   │   │   Program.cs
│   │   │   Startup.cs
│   │   │
│   │   ├───Bindings
│   │   ├───Config
│   │   │       appsettings-dev.json
│   │   │       appsettings-int.json
│   │   │       appsettings-prod.json
│   │   │       appsettings-stag.json
│   │   │
│   │   ├───Controllers
│   │   │       TasksController.cs
│   │   │
│   │   ├───Extensions
│   │   │   └───Middleware
│   │   │           ErrorDetails.cs
│   │   │           ExceptionMiddleware.cs
│   │   │
│   │   └───Properties
│   │           launchSettings.json
│   │
│   ├───Dotnet.Onion.Template.Application
│   │   │   Dotnet.Onion.Template.Application.csproj
│   │   │
│   │   ├───Handlers
│   │   │       TaskCommandHandler.cs
│   │   │       TaskEventHandler.cs
│   │   │
│   │   ├───Mappers
│   │   │       TaskViewModelMapper.cs
│   │   │
│   │   ├───Services
│   │   │       ITaskService.cs
│   │   │       TaskService.cs
│   │   │
│   │   └───ViewModels
│   │           TaskViewModel.cs
│   │
│   ├───Dotnet.Onion.Template.Domain
│   │   │   Dotnet.Onion.Template.Domain.csproj
│   │   │   IAggregateRoot.cs
│   │   │   IRepository.cs
│   │   │
│   │   └───Tasks
│   │       │   ITaskFactory.cs
│   │       │   ITaskRepository.cs
│   │       │   Task.cs
│   │       │
│   │       ├───Commands
│   │       │       CreateNewTaskCommand.cs
│   │       │       DeleteTaskCommand.cs
│   │       │       TaskCommand.cs
│   │       │
│   │       ├───Events
│   │       │       TaskCreatedEvent.cs
│   │       │       TaskDeletedEvent.cs
│   │       │       TaskEvent.cs
│   │       │
│   │       └───ValueObjects
│   │               Description.cs
│   │               Summary.cs
│   │               TaskId.cs
│   │
│   └───Dotnet.Onion.Template.Infrastructure
│       │   Dotnet.Onion.Template.Infrastructure.csproj
│       │
│       ├───Factories
│       │       EntityFactory.cs
│       │       TaskFactory.cs
│       │
│       └───Repositories
│               TaskRepository.cs
│
└───tests
    └───Dotnet.Onion.Template.Tests
        │   Dotnet.Onion.Template.Tests.csproj
        │
        └───UnitTests
            ├───Application
            │   └───Services
            │           TaskServiceTests.cs
            │
            └───Helpers
                    HttpContextHelper.cs
                    TaskHelper.cs
                    TaskViewModelHelper.cs

As you can see, it has the shape of an onion and it has three common layers:

Application layer: where all the business logic is implemented
Domain layer: where our domain is modeled (Task aggregate domain model for example) and some patterns about DDD are there like Repository Pattern (only interfaces, not implementation)
Infrastructure layer: where we implement the code that needs to go outside our application, like for example data access implementation

There can be external layers which are called presentation layers or testing layers. For example, in a common API, the external layer is RestAPI which has the dependencies to handle APIs with ASP.NET Core but in a Cron Job we don’t have APIs, so this external layer is a Console application layer that handles all that we need to start the application and the definition of the workflow to process some data.

I didn’t add any library like AutoMapper or similar because I wanted to remain agnostic about that. If you want to use AutoMapper or any similar NuGet package feel free. The same thing with FluentMediator, I find it really useful and I wanted to handle my Mediator Bus with that package but if you would like to use MediatR you can do it without any problem, you just need to modify the code related to IMediator implementations and definitions.

Going back to the diagram, if you did read my previous articles you will be familiar with The Dependency Rule. It is the most important thing when building a Clean Architecture and summarizing this rule says that the concentric circles represent different areas of software. In general, the further in you go, the higher level the software becomes. The outer circles are mechanisms. The inner circles are policies.

What does that mean?

Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in an inner circle. That includes functions, classes. variables, or any other named software entity.

CQRS and Event Sourcing

This is another thing I wanted to promote with my team (and also more teams). When designing a distributed architecture I think that CQRS (Command Query Responsibility Segregation) and ES (Event Sourcing) can help a lot. Of course, they are not a Silver Bullet, they are just patterns that you can follow if your microservice needs it or not.

And that’s why I included it inside my template because it can be useful for anyone. Also, I didn’t want to introduce CQRS and Event Sourcing with difficult examples with different databases and propagating changes from the Write DB to the Read DB. It is just a simple “DataBase” (there is no database access, just creating mocked data inside the Repository implementation).

If you are a little bit familiar with CQRS you know that there are two flows (models):

Reading (Queries): It is going to use Dependency Injection to the Repository class that it needs to go to the Database or any kind of data source system. The definition of that repository class is an interface, a contract, inside our Domain Layer (you can see that in the upper right corner of the diagram which is an image from the original post about Onion Architecture in 2008). The implementation as I mentioned before, should be outside the Domain Layer, in fact, it is inside the Infrastructure Layer. Why? Because if you are building the Repository implementation in the domain you are coupling the domain to the data source access and also you are breaking The Dependency Rule.
Writing (Commands): If you are modifying the Aggregate state **(for example Tasks Aggregate) you need to specify that **creating a Domain Command **in the code to use CQRS properly. So from this point, if you want to use Domain Commands and CQRS in a way to get the best performance you just need to use a message bus. **In our case, we chose to use the Mediator pattern which creates an internal bus and it is the one managing or handling the Domain Commands to use Handlers. These handlers are going to be called by a different thread any time, and if the thread pool is locked, the Domain Command is going to be in the Mediator bus waiting for a thread to be released and execute the rest of the code. This is everything C# magic and we just need to use the Mediator library to use this pattern. Once the code arrives at the specific Handler for any Command with a different thread, it is going to perform the changes in the data source (can be a database, API, etc) using the Repository pattern. But as I mentioned before using Dependency Injection to get a fully testable code following the dependency rule and SOLID principles applied in the architecture.

And in that way, if you need it, once the Handler calls the Repository to perform the changes, you may raise an event that can go to any event store (a queue) and propagate the data to other microservices consuming information from that event store. For example, a Notification microservice that sends an email or something like that.

And that’s it! I tried to keep it simple as much as I could but providing a nice starting point for everyone as I mentioned at the beginning. If you and your team have the skills to implement more complete architectures definitely you should go that way. If not, you can try with simpler solutions and start understanding all concepts, seeing the benefits and the cons of everything, and grow as a software engineer.

If you have any question, feel free to send me a message on LinkedIn, here or my email, I will happily reply.

And last but not least, feel free to check the documentation in the repository, fork it, debug it, and if you like it, clicking on the star!

pereiren / dotnet-template-onion

Onion Architecture with .NET 6/.NET Core and CQRS/Event Sourcing following a DDD approach

dotnet-template-onion

Documentation

You can find information about this template in:

Prerequisites

.NET 6

Ensure you have the correct dotnet-core SDK installed for your system:

https://dotnet.microsoft.com/download/dotnet/6.0

This is just the version used by the template, if you need to use a newer or older one, you can do it manually after.

Usage

Clone this repository
To allow the api to be created you will need to install the template from nuget:

dotnet new -i {{Path_where_you_cloned_the_repository}}

Example:

dotnet new -i C:\GitLocal\dotnet-template-onion

To check that the template has been installed successfully:

dotnet new -l

There should now be a new template dotnet_template_onion

…

View on GitHub

I hope you enjoyed it and it was clear what I wanted to do.

Thanks for reading!

Clean architecture series — Part 3

David Pereira — Mon, 20 Apr 2020 07:11:40 +0000

“ Anxiety arises from not being able to see the whole picture. If you feel anxious but you are not sure why, try putting your things in order.” — Marie Kondo

The Clean Architecture 🧹

We have seen what Hexagonal and Onion Architectures are , so the next step is to review what Clean Architecture means.

You can check the first two articles about Hexagonal and Onion architectures here:

What is Clean Architecture?

Architecture pattern promoted by Robert C. Martin (Uncle Bob) in 2012 trying to do one more step in architecture patterns when thinking about isolated, maintainable, testable, scalable, evolutive and well-written code. Following similar principles to Hexagonal and Onion, Uncle Bob presented his architecture together with this diagram:

https://blog.cleancoder.com/uncle-bob/images/2012-08-13-the-clean-architecture/CleanArchitecture.jpg

The main goal of this architecture is the separation of concerns. Uncle Bob mentioned that he didn’t want to create another new and totally different architecture from Hexagonal and Onion. In fact, he did want to integrate all of these great architectures into a single actionable idea.

The key principles of this architecture are:

It’s really about the Separation of Concerns
Should be independent of frameworks
They should be testable
They should be independent of a UI
They should be independent of a database
The Clean Architecture Diagram — Innermost : “Enterprise / Critical Business Rules” ( Entities ) — Next out : “Application business rules” ( Use Cases ) — Next out : “Interface adapters” ( Gateways, Controllers, Presenters ) — Outer : “Frameworks and drivers” ( Devices, Web, UI, External Interfaces, DB )
The innermost circle is the most general/ highest level
Inner circles are policies
Outer circles are mechanisms
Inner circles cannot depend on outer circles
Outer circles cannot influence inner circles

So yes, these principles are coming from Hexagonal and Onion architectures as you must be wondering right now.

Also, all of these principles are following the same rule, which is…

The Dependency Rule

The concentric circles represent different areas of software. In general, the further in you go, the higher level the software becomes. The outer circles are mechanisms. The inner circles are policies.

What does that mean?

Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in an inner circle. That includes functions, classes. variables, or any other named software entity.

For example:

Elements located in the Entities circle (the enterprise business rules) should not refer to any elements outside of it (such as application business rules, interface adapters, frameworks, and drivers).

Data formats used in an outer circle should never be used by an inner circle , especially if they are generated by a framework in an outer circle. The Clean Architecture prevents anything in an outer circle to impact the inner circles as shown in the following diagram:

With that in mind already, let’s take a look at the defined circles in the diagram

Circles of the Clean Architecture

https://www.codingblocks.net/wp-content/uploads/2018/02/The-Clean-Architecture-Cone.jpg

Entities

Entities encapsulate Enterprise-wide business rules.
An entity can be an object with methods, or it can be a set of data structures and functions. It doesn’t matter so long as the entities could be used by many different applications in the enterprise.
If you don’t have an enterprise and are just writing a single application, then these entities are the business objects of the application. They encapsulate the most general and high-level rules.

Use Cases

Use cases are application-specific business rules. Changes should not impact the Entities. Changes should not be impacted by infrastructure such as a database
The use cases orchestrate the flow of data in/out of the Entities and direct the Entities to use their Critical Business Rules to achieve the use case.

Interface Adapters

Converts data from data layers to use case or entity layers. Presenters, views, and controllers belong here.
No code further in (use cases, entities) should have any knowledge of the database.

Frameworks and Drivers

These are the glue that hooks the various layers up.
The infrastructure details live here.
You’re not writing much of this code, i.e. we use SQL Server driver, but we don’t write it.

You can add as many circles as you need. These are schematic. As Uncle Bob mentioned, you can have all the circles/layers you need but following always The Dependency Rule.

So the thing is, we have these circles and we follow The Dependency Rule, but how am I supposed to cross these circles boundaries?

How to cross Circle Boundaries?

This little screenshot which is part of the original diagram proposed by Uncle Bob shows an example of how the Controllers and Presenters communicate with the Use Case in the next circle/layer.

The flow of control begins at the controller, moves through the use case, and then winds up executing the presenter.

So if you remember well, The Dependency Rule says that no name in an outer circle can be mentioned by an inner circle. And following the Flow of Control, the Use Case needs to call the presenter. And how do we solve that without violating The Dependency Rule? Two ways to handle it

By using the Dependency Inversion Principle from SOLID principles , where we can define a port (an interface) in the inner circle and implement it in the outer circle.
By using a great design pattern, Mediator. By using it we can define an object that encapsulates how a set of objects interact.

From my point of view, I prefer to use the Mediator pattern. It has two great benefits that fit really well with the Clean Architecture:

Objects delegate their interaction to a mediator object instead of interacting with each other directly.
It should be possible to change the interaction between a set of objects independently.

Presenters

This is another concept we can see in the Flow of Control diagram. The purpose of the presenter is to decouple the use cases from the format of the UI.

They were created to decouple the interactor and the view, so if we use them we can follow the Dependency Rule. If we were returning the response model for the API from the interactor we would be coupling an inner layer to the outer one and we wouldn’t be following the Dependency Rule.

Clean + Hexagonal + Onion Architecture

In the previous example on how to handle communication between Controllers and Use Cases we have seen how the Clean Architecture uses Ports and Adapters pattern. Also remembering if we bring back the key principles of the Onion Architecture we must remember that it is an architecture driven by use cases. So with these Use Cases we are introducing the usage of Onion Architecture principles.

This is double confirming what I mentioned at the beginning of this article. Clean, Hexagonal and Onion architectures are not competing with each other to see which one is cooler or better. All of them try to find a way to separate concerns , and Clean Architecture is focused on combining principles from previous architectures patterns and more principles (like the Stable Dependencies Principe , Stable Abstractions Principle , SOLID, etc )

So, how should I structure my code following all of this?

First of all, this is not a dogma. Benefits are known and it should be a 100% fit for a lot of enterprise projects where business rules change continuously and also we are adding more and more features. But maybe you don’t need to do this for a simple background process service or serverless function. It’s up to you.

But if you definitely want to try it, go for it. Try to put everything in place understanding all the concepts and why you should put something in that circle/layer. And once you’ve tried it, compare your boilerplate with other clean architectures projects out there on GitHub or wherever.

Next chapter will be focused on building an API following this architecture, but right now I would like to share the boilerplate of that API:

This a simple version of the layers and folders structure for an API, sometimes you need to use more architecture patterns, sometimes less. The important thing about this kind of stuff is understanding the rules and growing every day learning new things.

Conclusion

I think that every day more and more developers try to understand how to create quality code following best practices to add more features, to get good code coverage in the tests, to scale it up easily and to maintain the code free of bugs and bad spaghetti code smells.

I have seen dozens of legacy projects almost impossible to maintain, with a lot of bugs and bad practices generating performance issues, never-ending feature developments, and developers burnouts.

https://static.makeuseof.com/wp-content/uploads/2015/02/programming-burnout-670x335.jpg

Clean Architecture pattern has become more popular in Android development during the past few years and I do really wish that it become more popular in backend architectures or even in the frontend.

Imagine the satisfaction of building something great each day, creating well-engineered solutions for complex business scenarios and making sure that you can add new features without losing huge amounts of time and mental health.

Of course, some developers won’t like this thinking of creating clean code/architectures or they will say something like “meh this looks over-engineered”.

I don’t like to reply to that kind of comment. But Marie Kondo does:

There are two reasons we can’t let go: an attachment to the past or a fear for the future.

Remember to tidy up your code, she is watching you.

The next article in the series will be more practical, building a simple API with .NET Core and accessing real data.

Also, if you enjoyed this article, feel free to share it and to give some love!

If you have read all of this, thank you very much. Feel free to connect with me on Linkedin!

Repositories following the Clean Architecture

References

UrbanNoise, my open source project

David Pereira — Sat, 18 Apr 2020 09:48:41 +0000

I have been thinking about this during a while, and I finally decided to go open source for this personal project.

I would love to start this project as open source in order to keep growing with latest technologies. Also I want to start it because I’d enjoy how this application could get our life easier when looking for an apartment.

Imagine yourself after having an appointment to check if you like that apartment you saw on Internet. You probably liked it, but now you have a big question:

“Will it be quiet during the night?”

So, if you can draw yourself in this situation I hope you support this project as much as I do!

To resolve this circumstance an application will be built where you will be able to check the noise history for any area in your city using classified and analyzed data, showing you something similar like the traffic map from Google similar to this (no final UI design yet on my mind, I am a back-end guy :) )

Heat map for Google Maps and Google Earth

And also you could use this app not only for checking data, you could collaborate providing data through your mobile phone and microphone , covering areas where there aren’t noise-meters! And don’t worry at all, I won’t listen anything you say like Alexa or Instagram do to sell you the best offer gadgets (I swear). I only want people to measure the noise level after calibrating your device!

And if you are still hungry for more, in the future the application could predict the noise is going to be in any area you want after analyzing the acquired data, weather, events, traffic, etc (yeesss AI)

This project will start collecting data from Barcelona city and if everything goes as expected it would grow acquired data from another cities around the world!

And now, leaving behind the product definition let’s move to the techie section. Because you will be reading this asking yourself how I am planning to do this (I do really hope you are asking yourself that right now).

Project name : UrbanNoise (decided with the best girlfriend of the world like 3 years ago)
Technologies stack : .NET Core 3.0, Azure, CosmosDB, Serverless, DDD, hexagonal architectures, SOLID, DRY, KISS principles, xUnit, Selenium, etc. And trust me, this is for real. Every commit will be analyzed by SonarQube and during the code review process opening Pull Requests. Of course, testing and code coverage will be mandatory.
Data import process from the noise-meter devices from Barcelona SmartCity webapp (please do not tell this to Ada Colau, it is for a good cause): Azure Functions with Time Triggers (15 minutes cron jobs), saving all the data in CosmosDB.
API : Using CQRS and Mediator patterns to split the data from be read or written when an user interacts with the application. And also using serverless Azure Functions with HTTP Triggers (it would be cheaper for me for a first phase of this open source project). We could use Azure API Management as a gateway as well.
Predictor : To be decided, but I would enjoy using ML.NET together with Spark loading the CosmosDB data. The reason I didn’t decided totally this part of the project is my wallet. I am not sure if I could use the cloud services without spending too much money.
GIT repositories: All code will be located here https://github.com/urbannoise (avoid current repositories as they were created when I was thinking to create everything with microservices and Kubernetes). I am owner of that open source organization.
CI/CD: Azure Dev Ops Pipelines. I still have to set up everything here, but at least I created the space to start with here: https://dev.azure.com/davidpereiracostoya/UrbanNoise
UI/Mobile : Wow, this my weak pain point. I would like to discuss this wieh someone, I was thinking about something like VueJS and Flutter, but I am interested in listening more experienced people.
Planning/Documentation : Azure Dev Ops will be use mainly for this to have only one place where everything can be checked, but of course some Medium articles will be written to share the effort and possible challenges during the development of the project.

And after reading all this text, maybe you are asking yourself, Why Open-Source?

Well, after thinking about it during a long time I have decided to do it in this way because:

It is a great opportunity to learn from the community.
I couldn’t do it alone (you know, office hours drain my energy battery)
But overall, to share our knowledge and our beautiful work.

And that’s all. So if you like the idea and you want to collaborate feel free to leave a comment here or send me a message to my LinkedIn. And if you can share this article I owe you a coffee!

EXTRA BONUS: We are looking for someone with UX experience in Mobile. If you like the idea and you want to collaborate, feel free to leave a comment or send me a message! Thanks!

Clean architecture series — Part 2

David Pereira — Mon, 30 Mar 2020 11:59:05 +0000

Everyone has tasted onions. In pizzas, hamburgers, salads, etc. But have you ever tasted Onion architecture in your code?

The Onion Architecture 🧅

After the Hexagonal Architecture article, now it’s time to talk about Onion Architecture.

You can check the first article of this series here about Hexagonal architectures

Clean architecture series— Part 1

What is the Onion Architecture?

So, this architecture pattern was promoted by Jeffrey Palermo in 2008 trying to solve common problems when maintaining applications and also emphasizing the separation of concerns throughout the system. It was presented as an alternative to the well known Tradition Architecture :

https://i0.wp.com/jeffreypalermo.com/wp-content/uploads/2018/06/image257b0257d255b61255d1.png?resize=357%2C253&ssl=1

The problems with this kind of architecture are all over the place but as Jeffrey Palermo says it starts wrong when each subsequent layer depends on the layers beneath it, and then every layer normally will depend on some common infrastructure and utility services.

That problem would be represented in something like this:

So what Jeffrey Palermo proposed is a new approach to architecture.

https://cdn-images-1.medium.com/max/1200/1*EmndhaXK7k11HwnY7MfUQQ.png

He mentioned:

Honestly, it’s not completely new, but I’m proposing it as a named, architectural pattern. Patterns are useful because it gives software professionals a common vocabulary with which to communicate. There are a lot of aspects to the Onion Architecture, and if we have a common term to describe this approach, we can communicate more effectively.

The main premise of this architecture is that it controls coupling. The fundamental rule is that all code can depend on layers more central, but code cannot depend on layers further out from the core. In other words, all coupling is toward the center.

So imagine the prior diagram example where Foo and Bar classes were coupled to each other even they are living in different layers. Following that main premise, you would need to control coupling in a similar way to this:

https://cdn-images-1.medium.com/max/1200/1*tmx3ULMnFSyUtoNWWsD_JQ.png

Remember that main rule when talking about Onion Architecture.

Benefits of Onion Architecture

Sustainability / Timelessness: by decoupling our application-business code from the tools we are using (i.e. the libraries and frameworks), we make it less vulnerable to the erosion of time and IT fads
Testability: We are decoupling everything between different layers, so everything can be tested.
Adaptability / Time to market: adding a new way to interact with your application is very easy.
Understandability: Rather than having a solution where use cases are completely lost or mixed within all the technical stuff, this architecture style states the emergence of an applicative-use-case-layer
Use case driven: Indeed, with this architecture style, we design our applications with our use cases in mind; not the number of persistence technologies or binding types we will need to support

Disadvantages of Onion Architecture

Interface soup : lots of interfaces for interaction with the core which can make navigating a project tougher.
Core heavy: lots of logic and movement in the core, any changes made inside the core could affect behavior outwards. But if this didn’t happen it would be a miracle.

Let’s take a look now at the layers of our onions 🧅🧅🧅

Layers of the Onion Architecture following DDD

In the very center , we see the Domain Model , which represents the state and behavior combination that models truth for the organization. Around the Domain Model, there are other layers with more behavior. The number of layers in the application core will vary , but remember that the Domain Model is the very center , and since all coupling is toward the center, the Domain Model is only coupled to itself.

The first layer around the Domain Model is typically where we would find interfaces that provide object saving and retrieving behavior, called Repository Interfaces.

If you are thinking about DDD after reading that you are right. Repository Pattern belongs to Domain Driven Design and can be described as :

Pattern that mediates between the domain (aggregate roots) and data mapping layers using a collection-like interface for accessing domain objects.

You may think where the implementation of that Repository Interface may reside. Jeffrey Palermo mentioned that out on the edges we see UI, Infrastructure, and Tests. The outer layer is reserved for things that change often. These things should be intentionally isolated from the application core.

So our implementation of that repository interface should live in the infrastructure layer , isolating everything from the core. If one day we need to use MongoDB instead of MySQL when accessing data we don’t need to worry about the application core or business logic. We only need to focus our effort on the implementations of the Infrastructure layer. Because those as far as you are not changing anything about in the business rules, you don’t need to modify the Repository Interfaces or the Domain Model.

A couple of pictures are worth than thousand words. So here you can find the places where the Repository Interfaces and Implementations reside in the Onion Diagram and as well in the UML diagram.

https://cdn-images-1.medium.com/max/1200/1*W5JIMKJ5T_05J1VhZCZJUw.png

https://cdn-images-1.medium.com/max/1200/1*vAKOPgFeEmlMlW_Q6hygZA.png

At this point, someone may be asking if the very center is the Domain Model or the Database.

I just want to emphasize that the database is external. Some people are used to think applications where the center is a database running triggers, stored procedures or jobs. If you follow this Onion Architecture there are no possible database applications. Most of the applications might use a database as a storage service but only though some external infrastructure code that implements an interface that makes sense to the application core. Decoupling the application from the database, file system, etc, lowers the cost of maintenance for the life of the application.

So… where the hell is my business logic?

Let’s get this straight.

Around the Domain Model, we can see two layers. Domain Services and Application Services.

Application Services: Typically used to orchestrate how the outside world interacts with your application. For example, AuthenticationService would be an Application Service that co-ordinates how a user should be authenticated. In other words, they are like the use cases of our application.
Domain Services: When a significant process or transformation in the domain is not a natural responsibility of an ENTITY or VALUE OBJECT, add an operation to the model as a standalone interface declared as a SERVICE. Define the interface in terms of the language of the model and make sure the operation name is part of the UBIQUITOUS LANGUAGE. Make the SERVICE stateless. For example, you might have a RegisterUserService that co-ordinates how a user is registered within your application.

To explain the difference between these two concepts and understand when and how to use them I am going to take an example from this great repository about DDD : https://github.com/zkavtaskin/Domain-Driven-Design-Example

This code created by Zan Kavtaskin ( http://www.zankavtaskin.com/) is a great example of how to apply DDD within an Onion Architecture.

The entry point of the application is an API (Presentation layer), and after that reaches an application service to go deeper to the center, the domain model , like following below diagram (just imagine a Presentation Layer outside the Application Layer)

So, let’s take a look at the CartController.cs

When the API reaches this route in this controller we are using the CartService which allows users to interact with the Cart in this e-commerce application ( Application Service living in the Application Layer )

Here is the code for CartService.csApplication Service:

In that CheckOut function , it is easy to see how this Application Service is being used to interact with external users and coordinate the use cases of our business rules ( business logic ). Like trying to verify if a customer has already created a cart and verifying that that cart is linked to the same customer, if they can do a checkout or not and whether they can create a purchase or not.

And in some cases, that CheckOut function is making use of the CheckOut Domain Service (checkOutDomainService) to add the checkout operation to the model and create a Purchase. Let’s take a look at this specific Domain Service:

First of all, let’s review the definition of Domain Service again:

When a significant process or transformation in the domain is not a natural responsibility of an ENTITY or VALUE OBJECT

We can understand how this is being used in the application to follow DDD. This Domain Service is a process (checkout) which is not the responsibility of the domain model itself and it is adding an operation to the model (Purchase Aggregate Root).

In other words, we are handling the domain logic here.

And that’s how you manage the business logic and the domain logic using Application Services and Domain Services in Onion Architectures and DDD.

If it’s the first time you are reading something like this, I know how you feel right now

But everything will be in place once you just try to use these concepts in your code. The practice is always the key to master 🔨🔨🔨

Let’s get a summary of what was covered until this point (I know it’s a heavy and long article):

What is the Onion Architecture?
Benefits
Disadvantages
Layers
Domain Services and Application Services

So there is only one thing left, and that is….

Onion Architectures vs Hexagonal Architectures

I have seen a lot of people talking about this like a new Marvel movie , they tell you to choose, Onion team or Hexagonal team.

I try to be a guy that does not see everything in black and white. I like to learn, explore and understand but always taking into account the benefits of any new trend, principle or whatever. That’s the reason why I am not going to explain software architectures as a war, trying to convince you which one is the best and why you should use it alone. I am not going to do that.

Instead, I am going to focus this on how to use different architectures in a combined way, trying to show the benefits of it and when I would use them.

Remember to read Part 1 of this series where I collected a lot of information about Hexagonal (Ports and Adapters) Architecture

Clean architecture series— Part 1

To summarize Hexagonal Architecture, let’s bring back quickly a self-explanatory diagram:

Ports and Adapters in the diagram ( https://softwarecampament.wordpress.com/portsadapters/#tc1)

The Hexagon — the application
Driver Port — API offered by the application
Driven Ports — required by the application
Actors — environment devices that interact with the application
Drivers — application users (either humans or hardware/software devices)
Driven Actors — provide services required by the application
Adapters — to adapt specific technology to the application
Driver Adapters — use the drivers’ ports
Driven Adapters — implement the driven ports

So, Hexagonal Architecture talks about Primary and Secondary Actors, Ports, Adapters and the Application. As I mentioned in Part 1, Alistair Cockburn didn’t mention anything about how you should do your code. Let’s quote this again:

The Ports and Adapters original article doesn’t mention anything at all and how code must be structured inside the Hexagon/Application ( http://web.archive.org/web/20180422210157/http://alistair.cockburn.us/Hexagonal+Architecture). I have seen a lot of articles talking about DDD or application layers but Alistair Cockburn didn’t write on how you should do your code, he only promoted the idea of ports and adapters

In other words, we can architect our application code with anything we want to. And given that this is the Onion Architecture + DDD article this is how I want to draw my architecture diagram at this point:

https://josecuellar.net/wp-content/uploads/hexagonalarchitecture.PNG

We now have ports, adapters and the Onion Architecture. And the key tenets are clear as well :

The application is built around an independent object model.
Inner layers define interfaces. Outer layers implement interfaces.
The direction of coupling is toward the center.
All application core code can be compiled and run separately from infrastructure.

Also, Hexagonal and Onion look for the same goal as Jeffrey Palermo mentioned in his first article about Onion Architecture:

Hexagonal architecture and Onion Architecture share the following premise: Externalize infrastructure and write adapter code so that the infrastructure does not become tightly coupled.

And I like to see it in this way. In tons of StackOverflow answers, tech blogs or even GitHub code samples a lot of people try to stick to one of these architecture patterns without having in mind that these patterns can work together.

And personally I would use them together for every application I need to be scalable, maintainable, highly covered by tests, evolvable and understandable.

Here some repositories with great examples of what I mentioned in this short article:

And…

In the next article, we are going to see how this Hexagonal+Onion Architecture works with the Clean Architecture pattern promoted by Uncle Bob.

Because…

If you have read all of this, thank you very much. Feel free to connect with me on Linkedin!

References

Clean architecture series - Part 1

David Pereira — Thu, 26 Mar 2020 08:21:18 +0000

I have been hearing this too long and I always wondered what hexagonal, onion and clean architectures really mean. I learnt a lot these last months and I want to share it.

I am sure that most of the software developers know the words of clean code, SOLID, clean architecture, hexagonal architectures, onion architectures, etc; but I suspect that most of them don’t know the truth about these amazing topics in software development. If you know them or you want to know more, please feel free to be at my side for this article series about everything I learnt on Clean Architecture.

I will try to explain what I learnt in different articles , following more or less this structure:

Hexagonal Architecture (Alistair Cockburn)
Onion Architecture + DDD (Jeffrey Palermo)
Clean Architecture (Uncle Bob)
What, Why, When
How to follow a Clean Architecture in .NET Core APIs
Bonus track: Clean Architecture + GraphQL in .NET Core (HotChocolate)

Hexagonal Architecture

So let get’s started with Hexagonal Architecture , also known as Port and Adapters pattern (which I prefer). Even you didn’t know what this pattern means you probably used in your code.

https://pixabay.com/illustrations/network-control-block-chain-hexagon-4478145/

Promoted by Alistair Cockburn in 2005 in one of his articles. Regarding the age of this pattern I would like to quote Juan Manuel Garrido de Paz , who mentions this in his awesomearticle about Ports and Adapters:

If you are thinking… “Isn’t the article too old? How is it that it is still worth it nowadays, being software development a discipline in continous evolution where new technologies and frameworks arise every day and kill the one we used yesterday?” Well the answer is in the question. Ports & Adapters is a pattern that promotes decoupling from technology and frameworks. So no, it isn’t too old. Good things are timeless. They are like wine, they get better as time passes by.

After this brief introduction, let’s move forward and take a look at the famous hexagonal diagram:

Following this diagram, we can see three important elements for the Ports and Adapters Pattern

Application : Represented as a hexagon (it has this shape because it is easier to draw elements around it), it contains all the business logic that our application needs to execute the business rules defined in the requirements. The Ports and Adapters original article doesn’t mention anything at all and how code must be structured inside the Hexagon/Application ( http://web.archive.org/web/20180422210157/http://alistair.cockburn.us/Hexagonal+Architecture). I have seen a lot of articles talking about DDD or application layers but Alistair Cockburn didn’t write on how you should do your code, he only promoted the idea of ports and adapters which I am going to try to explain later on.
Drivers (Primary Actors): External actors that interact with the application to get a response or to execute commands. In other words, the users of our application.
Driven Actors (Secondary Actors): These actors are being triggered by our application. There are two types of driven actors: repositories (the application may obtain data from it, for example, a database) and recipients (the application only sends information to it, like an SMTP server)

The difference between a primary and secondary actor lies only in who initiates the conversation

So... where the hell are those ports and adapters?

Ports

Ports live between the actors and the application core. They are part of the application, living on the edge of the hexagon and they handle the interactions with a given purpose. They are the application boundaries, or in other words, they are the interfaces that the application needs to communicate with external actors.

Driver Ports are the API of the application. This means that they provide the programmatic way of accessing a service to achieve a certain behaviour or output. Imagine in APIs, an interface type which is being called from the controller; that could be a driver port.

In the other hand, Driven Ports are the SPI (Service Provider Interface) of the application. SPI is the description of classes, interfaces, methods, etc that you extend and implement to achieve a goal. It is the way to extend or alter the behaviour of a software application. Trying to explain it with other words, imagine that one of our APIs sends notifications, the Driven Port is the interface type we created with that method to send the notifications.

Diagram showing API and SPI in Ports and Adapters patter ( https://beyondxscratch.com/2017/08/19/decoupling-your-technical-code-from-your-business-logic-with-the-hexagonal-architecture-hexarch/)

Remember, ports are technology agnostic, they don’t know if for example this notification is being sent correctly or you are spamming your boss. The driven adapter will implement this driven port and will take care of this.

Adapters

An adapter is a software component that allows a particular technology to interact with a port of the hexagon. Adapters are outside ports level. Some people say they are outside, others say that they are like in an upper parent hexagon outside the ports so I would say they are outside ports. That’s it.

A Driver Adapter uses a Driver Port Interface, converting a specific technology request into a technology-agnostic request to a driver port. In an API, the controller is a driver adapter, receiving requests from the UI and calling methods of the driver port.

A Driven Adapter implements a Driven Port Interface, converting technology-agnostic methods of the port into specific technology methods. For example, remembering our driven port to send notifications, our Driven Adapter would implement it and using email libraries depending on our programming language will send the email.

This pattern gives you the flexibility of mocking everything and even more important, you can switch from one technology to another. For example, if you are using as a Database Driven Adapter the SQL Server libraries and you need to switch to Mongo, it shouldn’t be too hard. Ports and Adapters pattern will force you in some way to follow SOLID principles in your architecture and code, with all the benefits of using them.

Ports and Adapters in the diagram ( https://softwarecampament.wordpress.com/portsadapters/#tc1)

Summary

I am going to quote everything from Juan Manuel Garrido de Paz article about Ports and Adapters because it is just perfect.

The Hexagon — the application
Driver Port — API offered by the application
Driven Ports — required by the application
Actors — environment devices that interact with the application
Drivers — application users (either humans or hardware/software devices)
Driven Actors — provide services required by the application
Adapters — to adapt specific technology to the application
Driver Adapters — use the drivers' ports
Driven Adapters — implement the driven ports

Also, I want to clarify one thing about the hexagon itself. Some people in other articles mentioned it and some misunderstood what Alistair Cockburn did with the Hexagon shape.

In the original article, Alistair says that the hexagon is just as it is because it is easy to highlight the inside-outside asymmetry and the nature of the ports. The term Hexagonal Architecture comes from this visual effect and it is not related to any kind of shape.

Benefits

Testability. All code must be isolated if you are following correctly this pattern, so everything can be mocked.
Maintainability. We talked about it before, but if you need to extend an adapter it can be easily done because of all that great isolation we achieve the following Ports and Adapters. Same if we require to switch an adapter implementation to use another technology (aka database, SMTP or queues)
Identify Tech Debt. Tech debt will be there, but following this approach, you will be able to identify code smells and measure the tech debt in terms of effort and time.

Cons

Complexity. For me, it is the only real issue here. Everyone in a team needs to be aligned to make this kind of architecture work. If that doesn’t happen the code and the architecture will become a mess without the possibility of getting any of the previously mentioned benefits.

Example repositories

With this article series I am trying to get a clean architecture and I will provide code samples once we review all this boring theory, but if you want to check how some people use Hexagonal Architecture here you have some Github repositories:

I hope that I explained myself good enough to understand what hexagonal architectures are and I wish you are not reacting to this article like this right now :

See you soon in the next article about Onion Architecture and DDD!

And if you enjoyed this article, feel free to share it and to give some likes!