search

baratgabor / MyWarehouse

Clean Architecture and Domain Driven Design sample project based on C# 10 / .NET 6 / ASP.NET Core 6 / EF Core 6 & Angular 11 with Bootstrap.
MIT License
243 stars 69 forks source link
angular11 asp-net-core asp-net-core-6 bootstrap clean-architecture ddd domain-driven-design efcore efcore6 vertical-slice-architecture

readme

MyWarehouse – A Clean Architecture, Vertical Slicing, DDD sample in ASP.NET Core

Backend CI Backend CD Frontend CD App Core Coverage Status


This is a sample project consisting of an ASP.NET Core web API backend service and an Angular frontend with Bootstrap.

I have finally decided it's time to have something public on my GitHub account that is actually relevant to my professional focus on ASP.NET Core, retiring those god-awfully written old classical ASP.NET projects I had on BitBucket.

The following, rather informatively written documentation page has a two-fold purpose:

  1. To be – hopefully – useful for others who wish to explore a similar direction in development.
  2. To provide a summary of my current approach to working with ASP.NET Core, and my current level of understanding thereof, so anyone who was interested in my skillset could easily review it in a single place.

Live Demo

See here. You'll have to sign in with the credentials shown on the picture below, or with your Google account*. The backend is hosted in an Azure App Service, connecting to an Azure SQL database. The frontend is hosted right here, at the excellent GitHub Pages. Apologies if the first request times out – Azure is spinning the services down if there is no traffic.

Feel free to alter the data, as the solution has an automatic sample generation module that I can run any time to reset it. What it doesn't have is a profanity filter. But I trust your maturity. 😅

With respect to deployment, the backend and the frontend are both automatically deployed by the corresponding GitHub CD pipeline when a push happens in the master branch. So the build you see should always reflect the state of the master branch.

*Google login privacy concerns: The app doesn't store any personally identifying data. The only data of yours that can end up being saved in database is your name (as LastModifiedBy) when you modify an entity. But no email address or Google profile ID is saved.

Screenshots

Contents:

Motivation

This experimental/sample project is the product of my experiences and pains with traditional n-tier, anemic model, file type folder based ASP.NET Web APIs. The ones where you have a Controllers, Models, Services top-level segregation, sometimes as separate assemblies, and your models are essentially simple DTOs, massaged by countless "services", "handlers", "managers", "validators", etc. All of which lead to a code base which is relatively hard to navigate, hard to reason about what touches what, brittle, and generally prone to bugs.

Also, oh my, the Startup.cs madness, where you just put everything in, and a few months later you have a monster Startup where you have no idea anymore what is required for what, and it often feels anything you touch breaks something else.

I'm not saying I never want to work on a more classical project, since there are realities we have to cope with, but I wanted to push my skillset and understanding into a new direction.

Origin/disclaimer:

This project had an older version I originally developed for a job application, with functionality they specifically asked to implement. I actually know very little of warehouses as a business domain, and I have no contact with any business experts from this domain, so the domain aspect (perhaps confusingly) is not intended to model a real warehouse. What I explored doing, with respect to the domain, is introducing validation and logic in entities, locking them down by not exposing mutable properties, and using value objects like Money and Mass (instead of primitive obsession) in the context of EF Core (i.e. owned types).

Technologies

C# 10 ◊ .NET 6 ◊ ASP.NET Core 6 ◊ Entity Framework Core 5 ◊ Angular 11 ◊ Bootstrap ◊ MediatR ◊ AutoMapper ◊ FluentValidation ◊ NUnit ◊ Moq ◊ FluentAssertions ◊ Respawn ◊ Swagger

Backend Design Paradigms

The backend system uses the following design paradigms (besides the fundamentals not worth mentioning). You can find plenty of dry materials pertaining to these subjects, so I mostly focused on providing a pragmatic narration that could perhaps help you to 'get the point' if you had difficulties extracting that value from other sources.

Clean Architecture

Uncle Bob's Clean Architecture is one of the most well-known modern architectural paradigms, which focuses on creating an application core that is devoid of infrastructural implementation concerns, pushing those out to an infrastructure layer (including the persistence mechanism, which is quite famously argued to be just a 'detail').

Similarly to the onion architecture, the dependencies between layers are strictly pointing inwards, so you end up with a domain and application layer that is self-contained and decoupled from higher level, less stable components of the system. Application layer dependencies are declared locally as interfaces, implemented by concrete services in the infrastructure layer. This is in contrast to the classical n-tier design where you have horizontal layers on top of a database communication layer, often tightly coupling the business logic to infrastructural and external concerns, arguably leading to maintenance headaches down the road.

The basis of my project structure comes from Jason Taylor's excellent Clean Architecture template, inspired by his relevant conference talk. But, even though this is still just a small sample project, I vastly expanded on that template, implementing many structurally significant decisions; the most significant being the integration of DDD concerns in the Domain.

Vertical Slicing

Vertical slicing is the concept and technique of structuring your solution into more-or-less self-contained feature slices instead of using a bunch of generalized services from layers upon layers.

The inspiration comes from the experience of brittleness that a highly service-oriented architecture can exhibit. E.g. when you try to implement a new feature or modify an existing, so you change the service it depends on, only to realize that you broke another feature that depended on the same service, because you didn't take into account all use cases of the given service component. Then you go and fix it, only to see that you broke another feature in a component far away which was relying on a second service that was relying on some validator used by a fourth service... Let's be honest: this is the day-to-day reality of many developers.

And there comes the realization that DRY – don't repeat yourself – can be recipe for spaghetti code, unless you take something very-very seriously:

What matters is not whether code in two or more places look similar in form, but whether you can guarantee that they have the same – preferably single – reason to change. (Sorry, not an actual quote, just wanted to highlight it.)

Vertical slicing also challenges our heavily ingrained modern-day compulsion to extract everything into reusable horizontal service components. Because the truth is that even if a piece of code is used in a single place, today we very often still do place that in some generalized service, partially because that's simply how we do things, and also because without vertical slices we often don't have a good place to put such code.

Vertical slicing leads to a design where each feature, or operation, or use case is more substantial than just a few calls on a bunch of generalized services, and actually encapsulates proper business logic in a structurally segregated manner.

Obviously this is an oversimplification, and in any complex system you'll undoubtedly still end up with plenty of generalized components that implement actually general/cross-cutting concerns. It's just that you can focus your design process around vertical slices, feel comfortable putting business logic into them in a prima facie fashion, and when you see the need you can then push those down to the domain entities (to implement DDD), or into general components.

Another great thing about vertical slicing that it aligns well to SCREAMING ARCHITECTURE, where you look at a solution, and what you see are not meaningless generic tech terms like models, services, dtos, validators... but you see what the system actually does, what features it has. Which arguably makes it easier to comprehend and work with a system.

One great, modern take on vertical slicing comes from Jimmy Bogard, developer of the widely used AutoMapper package, and it uses another of his projects, MediatR. Here is an excellent talk from him on vertical slice architecture (notice how he is not calling it "CQRS").

In my humble, but perhaps cheeky, opinion, there are two key things to understand about MediatR:

  1. MediatR is not a mediator:

    It's just not. I think pretty much everybody who knows their object-oriented design patterns are bound to see this. It indeed couples two objects with an intermediary, decoupling the direct connection between the two, but that alone doesn't make it into a mediator; a bunch of behavioral design patterns do that.

    One classical example of the mediator pattern is chat rooms, where you have multiple people wanting to broadcast messages. And instead of making their object representation know about and send messages to each one of them back and forth, you use an intermediary – a mediator – to facilitate distributed two-way communication between them. Another example is a taxi service where the dispatcher mediates between the taxis, instead of all of them having to know about all others. So, usually it refers to longer-term, more complex communication between more than two participators.

    But, there is another pattern, called commanding, where you encapsulate an operation into an object, and execute that object with a handler. Which is exactly what MediatR does. And how do you select the handler with MediatR? Through a service locator, a.k.a. the service locator anti-pattern.

    TL;DR;: It's commanding with a service locator on top. Duh. But no matter how we call it, it's a pretty cool piece of code, and the service locator is arguably not that big of a deal here (although it does obfuscate what handler will actually execute). By the way, I didn't direct this against the developer of MediatR in any way; I'm 100% sure that Jimmy Bogard knows design patterns twenty times better than me, and it's just that name selection often has little to do with semantics, not to mention that projects can change in scope and direction.

  2. MediatR has little to do with CQRS:

    This really has become one of my pet-peeves. For some reason 90% of people on the internet today seem to associate MediatR with CQRS, and they refer to "doing CRQS with MediatR", while their solution shows no concern or need to actually segregate queries from commands, and what they're doing is just vertical slicing in a command-driven fashion. Because simply naming some of your request handlers as commands and others as queries is emphatically not CQRS. CQRS is this, and as Martin Fowler notes, one should be very cautious about using it because of the added complexity.

    CQRS, or command-query responsibility segregation, is an orthogonal pattern. You can do CQRS with MediatR, or you can decide not to do CQRS with MediatR. Just as you can do CQRS without MediatR, or decide not to do CQRS without MediatR. But yes, arguably it's easier to implement CQRS (and a lot of other things) if you have a vertical slice architecture.

    In fact, I felt that in my sample project creating an additional level of Commands and Queries folders (like in Jason Taylor's Clean Architecture template) don't add any value to my design, and even distracts from the goals of screaming architecture, so I simply placed all operations for a given aggregate in the same folder.

    Here is an article from someone who gets it: No, MediatR Didn't Run Over My Dog.

Huh, this was a long section. 😅

Domain Driven Design

The alternative to those empty 'entities' that solely consist of public { get; set; } properties – doing proper OOP in our entities. I learned proper OOP design a good while ago, and honestly, it was damn difficult back then, because when I started to program I wrote procedural code in Commodore BASIC, then in QBasic, then in Turbo Pascal, then in PHP, and I was strongly conditioned to think in procedural terms.

Though, by banging my head against the proverbial wall I did succeed in rewiring my neural pathways to think in terms of interconnected objects which were responsible for their own valid state, exposing operations that were their concern to execute on their own state, and using other objects to execute other operations. And I have seen immense value in my designs when I started to be able to properly implement these principles (which admittedly took years, to get through the initial super-convoluted designs that added plenty of complexity without much value, which I believe are actually the reason so many people are questioning the worth of OOP (plus the inheritance madness we were doing, leading to rigid systems, but that's another long topic)).

But, when I started to work with ASP.NET, for some reason I swiftly abandoned everything I learned about object-oriented design, and I adapted to using a bunch of properties as my "model". That seemed to be the ASP.NET way of doing things, and I was a newcomer to this strange and wonderful land. Not to mention being thoroughly terrified of what would happen to the ORM (EF) if I added anything else than properties to the entities. But you can add. You can add a lot. At least with the current versions of EF Core.

Okay, this was quite abstract, with plenty of babbling. For some details of the actual implementation, see the relevant section below.

Project structure

The most important takeaway is that the application is separated both from the presentation (in this case the web API) and the infrastructural concerns. This way you have a highly flexible application core that you could run in multiple ways, and under various, replaceable infrastructural conditions.

Furthermore, the domain driven design (in contrast to anemic domain) helps to ensure that only valid operations are executed on the domain entities. This makes implementing application features less error-prone, especially for newer members of a team.

The vertical slice architecture of the application layer also helps to easily comprehend the behavior of the system, alleviating the usual 'what the hell is going on here' guesswork when someone new starts to work on a system.

(The visualization of the Infrastructure layer in Clean Architecture varies. Sometimes it's shown to be on the same level as the outermost representation layer, but I think this doesn't align with the perspective of an external observer. From that perspective the presentation (in this case, the API) is the sole outermost layer.)

Diversions from and extensions to the Clean Architecture Template

As I mentioned earlier, the structural basis of this sample project, and many of its good ideas, come from Jason Taylor's excellent Clean Architecture Template, which has been gaining some traction in the ASP.NET community in recent years. He also has some great conference talks on this subject.

But we all have to discover our own ways, based on our own experiences, following our own lead; arguably there is not much value in just mindlessly copying someone. So here is a list of my diversions and extensions. Part of them simply stem from the fact that this is not just a template, but instead a broader sample project with significantly more features. Another, smaller part are conscious disagreements.

DDD in Domain:

Paging, ordering and filtering:

Infrastructure layer modularization:

Improved integration/unit testing:

Support structure for strongly typed configuration:

API versioning:

Repository layer:

Logging extensions:

No Identity Server integration:

Deemphasizing CQRS:

.Net 5 (C# 9) features:

​ These are really minor things, I'm just trying to spread the good word about the new features, so more people tried them.

More feature-rich Angular frontend:

Potential improvements

How to set up to run locally

It you wish to clone this repository and use it (for whatever purpose you see fit), you'll have to take care of the following:

In conclusion

Thank you for your interest in this project and/or in this lengthy documentation page. I recognize that my style of writing readmes is different from what people usually do on GitHub, but since I don't publish on any platform I usually have plenty of things bottled up, so it just feels nice to write about them in a context where they are at least relevant.

I'm always open to improving my designs, and, as I mentioned, this was pretty much my first foray into DDD, so feel free to suggest improvements if you'd like to.

.NET 6.0 update improvements

With plenty of delay, the project was finally updated to .NET 6 (which we were using at my workplace pretty much from release day). The sections below will introduce you to the notable improvements that have occurred in the scope of this update.

● IOptions pattern improvements

If I'm not mistaken, 6.0 is the version when we got the new ValidateDataAnnotations() and ValidateOnStart() methods on OptionsBuilder, both of which come very handy in strongly typed options validation. So I took the opportunity to update my options registration extension helper method in the following way:

public static void RegisterMyOptions<T>(this IServiceCollection services, bool requiredToExistInConfiguration = true) where T : class
{
    var optionsBuilder = services.AddOptions<T>()
        .BindConfiguration(typeof(T).Name)
        .ValidateDataAnnotations() // <- Note
        .ValidateOnStart(); // <- Note

    // Note this hack too :)
    // You can pass a validation lambda to Validate() that will check if the section actually exists in configuration.
    // This check runs on startup if ValidateOnStart() is called.
    if (requiredToExistInConfiguration)
        optionsBuilder.Validate<IConfiguration>((_, configuration)
            => configuration.GetSection(typeof(T).Name).Exists(), string.Format(ConfigMissingErrorMessage, typeof(T).Name));

    services.AddSingleton(resolver => resolver.GetRequiredService<IOptions<T>>().Value);
}

● EF 6 "ConfigureConventions" – Centralized decimal precision config

There is a new feature in EF 6 that makes it much easier to configure entity properties in a cross-cutting manner. Previously you had to call modelBuilder.Entity<entity>().Property(e => e.PropertyName) to set configuration on a per-property basis, even if you wanted those constraints to apply to all properties of a given type, for example all strings to have the same maximum length, or all decimals to have the same precision. This lead to awkward solutions like the one below to have at least some sort of cross-cutting control (directly copied from this codebase before the .NET 6 update):

// Before .NET 6

/// <summary>
/// Set all decimal properties to a custom uniform precision.
/// </summary>
private static void ConfigureDecimalPrecision(ModelBuilder builder)
{
    foreach (var entityType in builder.Model.GetEntityTypes())
    {
        foreach (var decimalProperty in entityType.GetProperties()
            .Where(x => x.ClrType == typeof(decimal)))
        {
            decimalProperty.SetPrecision(18);
            decimalProperty.SetScale(4);
        }
    }
}

Now, after EF 6, we can do:

// After .NET 6

protected override void ConfigureConventions(ModelConfigurationBuilder configBuilder)
{
    configBuilder.Properties<decimal>()
        .HavePrecision(precision: 18, scale: 4);
}   }

Bam! 👌

● EF 6 "ConfigureConventions" – Centralized conversion config

Similarly to the section above, configuring conversions for all properties of a given type is much easier now as well. Consider that the following code was present in the codebase before the .NET 6 update:

// Before .NET 6
// Notice that conversion had to be set individually for each property of a given type.
// I had to resort to creating some local functions to reduce code repetition.

    // Store and restore mass unit as symbol.
    builder.Entity<Product>().OwnsOne(p => p.Mass, StoreMassUnitAsSymbol);

    // Store and restore currency as currency code.
    builder.Entity<Product>().OwnsOne(p => p.Price, StoreCurrencyAsCode);
    builder.Entity<Transaction>().OwnsOne(p => p.Total, StoreCurrencyAsCode);
    builder.Entity<TransactionLine>().OwnsOne(p => p.UnitPrice, StoreCurrencyAsCode);

    static void StoreCurrencyAsCode<T>(OwnedNavigationBuilder<T, Money> onb) where T : class
        => onb.Property(m => m.Currency)
        .HasConversion(
            c => c.Code,
            c => Currency.FromCode(c))
        .HasMaxLength(3);

    static void StoreMassUnitAsSymbol<T>(OwnedNavigationBuilder<T, Mass> onb) where T : class
        => onb.Property(m => m.Unit)
        .HasConversion(
            u => u.Symbol,
            s => MassUnit.FromSymbol(s))
        .HasMaxLength(3);

Now after .NET 6 this has become:

    protected override void ConfigureConventions(ModelConfigurationBuilder configBuilder)
    {
        configBuilder.Properties<Currency>()
            .HaveConversion<CurrencyConverter>() // Notice how we're setting a converter for all props of this type.
            .HaveMaxLength(3);

        configBuilder.Properties<MassUnit>()
            .HaveConversion<MassUnitConverter>()
            .HaveMaxLength(3);
    }

The only downside is that we're forced to write converter classes (e.g. CurrencyConverter above), which is arguably a bit too much ceremony for very simple conversions where a short lambda would suffice.