Instead of having Core depend on data access and other infrastructure concerns, we invert these dependencies, therefore Infrastructure and Presentation depend on Core. This is achieved by adding abstractions, such as interfaces or abstract base classes, to the Application layer. Layers outside of Core, such as Infrastructure and Persistence, then implement these abstractions.

A good example is the implementation of the Repository pattern. Within this design, we would first add an IRepository interface to the Application layer. Next, we would implement this interface within Persistence by creating a Repository class using our preferred data access technology. Finally, within Core the logic we write will only use the IRepository interface, so Core will remain independent of data access concerns.

With this design, all dependencies must flow inwards. Core has no dependencies on any outside layers. Infrastructure, Persistence, and Presentation depend on Core, but not on one another.

This results in an architecture and design that is:

• Independent of Frameworks - Core should not be dependent on external frameworks such as Entity Framework
• Testable -The logic within Core can be tested independently of anything external, such as UI, databases, servers. Without external dependencies, the tests are very simple to write.
• Independent of UI - It is easy to swap out the Web UI for a Console UI, or Angular for Vue. Logic is contained within Core, so changing the UI will not impact logic.
• Independent of Database - Initially you might choose SQL Server or Oracle, but soon we will all be switching to Cosmos DB
• Independent of anything agency - Core simply doesn't know anything about the outside world

While the design in the above​ figure only includes three circles, you may need more - just think of this as a starting point.

​References​

• The Clean Architecture
• Clean architecture
  

​Then, check out these books:

This book by Robert C. Martin (aka ‘Uncle Bob’) should be anyone’s starting point for reading further.

Figure: Clean Architecture: A Craftsman's Guide to Software Structure and Design

This resource by Steve Smith is available as an online e-book and contains up-to-date specific examples for ASP.NET Core and Azure.​

​​​

Figure: Architecting Modern Web Applications with ASP.NET Core and Microsoft Azure

Figure: The Clean Architecture Solution Template by @JasonTaylorDev

​The template is designed for creating a Single Page App (SPA) with Angular and ASP.NET Core, but it can easily be used for other .NET Core applications. Create a new project based on this template by visiting https://github.com/jasontaylordev/CleanArchitecture/ and clicking Use this template or by installing the .NET Core Project Template package. To do so, follow these steps:

1. Install the latest .NET Core SDK
2. Install the latest Node.js LTS
3. Run dotnet new --install Clean.Architecture.Solution.Template to install the project template
4. Create a folder for your solution and cd into it (the template will use it as project name)
5. Run dotnet new ca-sln to create a new project
6. Navigate to src/WebUI and run dotnet run to launch the project

If you would like to learn more, review the following blog post: Clean Architecture with .NET Core: Getting Started.

​

Bad Example: Domain is cluttered with data annotations

As you can see in the above example, the domain is cluttered with data annotations. If the data access technology changes, we will likely need to change all entities as all entities will have data annotations. In the following example, we will remove the data annotations from the entity and instead use a special configuration type:

Good Example: Domain is lean, configuration for entity is contained within a separate configuration type

This is a big improvement! Now the customer entity is lean, and the configuration can be added to the persistence layer, completely separate of the domain. Now the domain is independent of data access concerns.

Learn more about this approach by reading about self-contained configuration for code first.​

Figure: ​Database implementation is a Infrastructure concern not a Domain concern. ​​

​

Figure: Bad example - Although this application clearly has repository and business logic layers, the logic that orchestrates these dependencies is in the ASP.NET Controller and is difficult to reuse

The logic in the above controller cannot be reused, for example, by a new console application. This might be fine for trivial or small systems but would be a mistake for enterprise systems. It is important to ensure that logic such as this is independent of the UI so that the system will be easy to maintain now and well into the future. A great approach to solving this problem is to use the mediator pattern with CQRS.

CQRS stands for Command Query Responsibility Segregation. It's a pattern that I first heard described by Greg Young. At its heart is the notion that you can use a different model to update information than the model you use to read information
...
There's room for considerable variation here. The in-memory models may share the same database, in which case the database acts as the communication between the two models. However they may also use separate databases, effectively making the query-side's database into a real-time reporting database.
Martin Fowler - https://martinfowler.com/bliki/CQRS.html ​

 
CQRS means clear separation between Commands (Write operations) and Queries (Read operations).
CQRS can be used with complex architectures such as Event Sourcing but the concepts can also be applied to simpler applications with a single database.​

​MediatR is an open source .NET library by Jimmy Bogard that provides an elegant and powerful approach for writing CQRS, making it easier to write clean code.

For every command or query, you create a specific request class that explicitly defines the “input” required to invoke the operation.​

Figure: (from MediatR docs) A Simple Request class

Then the implementation of that command or query is implemented in a handler class. The handler class is instantiated by a Dependency Injection container – so can use any of the configured dependencies (Repositories, Entity Framework, services etc).

Figure: A handler class

This approach brings many benefits:

• Each command or query represents an atomic, well-defined operation such as "Get My Order Details" (Query) or "Add Product X to My Order" (Command)
• In Web APIs, this encourages developers to keep logic out of controllers. The role of controllers becomes reduced to "Receive a request from the web and immediately dispatch to MediatR". This helps implement the "Thin controllers" rule:  https://rules.ssw.com.au/do-you-use-thin-controllers-fat-models-and-dumb-views. When logic is in a controller, the only way to invoke it is via web requests. Logic in a mediator handler can be invoked by any process that is able to build the appropriate request object, such as background workers, console programs or SignalR hubs
• Mediator also provides a simple pub/sub system allowing "side effects" to be explicitly implemented as additional, separate handlers. This is great for related or event-driven operations such as "Update the search index after a change to the product has been saved to database"
• Using a specific handler class for each operation means that there is a specific dependency configuration for each command or query
• Developers often implement interfaces and abstractions between the layers of their applications. Examples of this might include an IMessageService for sending emails or an IRepository interface to abstract database access. These techniques abstract specific external dependencies such as "How to save an order entity in the database" or "How to send an email message". We have witnessed many applications with clean, persistence-ignorant repository layers but then with messy spaghetti code on top for the actual business logic operations. MediatR commands and queries are better at abstracting and orchestrating higher-level operations such as "Complete my order" that may or may not use lower-level abstractions. Adopting MediatR encourages clean code from the top down and help developers "fall into the pit of success"
• Building even a simple app with this approach makes it easy to consider more advanced architectures such as event sourcing. You have clearly defined "What data can I get" and "What operations can I perform". You are then free to iterate on the best implementation to deliver the defined operations. MediatR handlers are easy to mock and unit test
• MediatR handlers are easy to mock and unit test
• The interface for MediatR handlers encourages the implementation of best-practice async methods with cancellation token support.
  
• MediatR introduces a pipeline behaviour system allowing custom to be injected around handler invocation. This is useful for implementing cross-cutting concerns such as logging, validation or caching
  

Figure: Good example - MediatR simplifies the dependencies injected into the controller. The incoming web request is simply mapped directly to a MediatR request that orchestrates all the logic for this operation. The implementation and dependencies needed to complete “GetItemForEdit” are free to change without needing to change the controller class

​

Figure: A Typical ASP.NET Controller using Mediator

In the above example, the API contains a Create action that includes a CreateProductCommand parameter. This command is a request to create a new product, and the request is associated with an underlying request handler. The request is sent using MediatR with the method call _mediator.Send(command). ​​MediatR will match the request to the associated request handler and return the response (if any). In a typical implementation, the request and request handler would be contained within separate files:

Figure: Bad Example - The request is contained within CreateProductCommand.cs

Figure: Bad Example - The request handler is contained within CreateProductCommandHandler.cs

In the above implementation, the request handler is cleanly separated from the request. However, this separation results in reducing discoverability of the handler. For example, a developer looking at the action in this first figure might be interested in the logic behind the command. So, they press F12 to go to the definition and can see the request (CreateProductCommand), but not the logic since it is contained within the request handler (CreateProductCommandHandler). The developer must then navigate to the handler using Solution Explorer or some keyboard wizardry. This is assuming that the developer is familiar with the design, and knows that there is an underlying request handler that contains the logic of interest. We can avoid these problems and improve discoverability by instead using the following approach:

Figure: Good Example - Nesting the Request Handler within the Request Improves Discoverability of Command and Associated Command Logic

In the above example the request handler is nested within the request, there by improving the discoverability of the command and associated command logic.

The purpose of a VM is also the transfer of data, however VMs can encapsulate behaviour. This behaviour is useful, for example, when creating a WPF + MVVM application, but not so useful when creating a SPA - since you can't serialize the behaviour and pass it from ASP.NET MVC to the client.

Learn more about the above concepts in the following Weekly Dev Tips podcasts:

·  Data Transfer Objects (part 1)

·  Data Transfer Objects (part 2)​

Figure: Bad Example - Managing Request Validation within the Controller

In the above example, model state validation is used to ensure the request is validated before it is sent using MediatR. I am sure you are wondering - why is this a bad example? Because in the case of creating products, we want to validate every request to create a product, not just those that come through the Web API. For example, if we're creating products using a console application that invokes the command directly, we need to ensure that those requests are valid too. So clearly the responsibility for validating requests does not belong within the Web API, but rather in a deeper layer, ideally just before the request is actioned.

One approach to solving this problem is to move validation to the Application layer, validate immediately before the request is executed. In the case of the above example, this could be implemented as follows:

Figure: OK Example - Validation Handled Manually within Request Handler Ensuring All Requests are Validated

The above implementation solves the problem. Whether the request originates from the Web API or a console app it will be validated before further processing occurs. However, the above code is boilerplate and will need to be repeated for each and every request that requires validation. And of course, it will only work if the developer remembers to include the validation check in the first place!
 
Fortunately, if you are following our recommendations and combining CQRS with MediatR you can solve this problem by incorporating the following behaviour into your MediatR pipeline:

Figure: Good Example - Automatically Validate All Requests By Using a MediatR Pipeline Behaviour

This RequestValidationBehavior class will automatically validate all incoming requests and throw a ValidationException should the request be invalid. This is the best and easiest approach since existing requests, and new requests added later, will be automatically validated. This is possible through the power of MediatR pipeline behaviours. The documentation for MediatR includes a section on Behaviours; https://github.com/jbogard/MediatR/wiki/Behaviors. Review this documentation to understand how you can enhance your request handlers with behaviours and how to register pipeline behaviours.​

The only step that remains is handle any validation exceptions. Within the console app, a try catch block will suffice. The action taken within the catch block will of course depend on requirements. Within the Web API, use an ExceptionFilterAttribute to catch these exceptions and convert them into a BadRequest result as follows:

Figure: Good Example – Use an ExceptionFilterAttribute to Catch and Handle Exceptions within the Web API

As an example, consider an AD account. An AD Account consists of a domain name and user name, e.g. SSW\Jason. It is a string so using the string type makes sense. Or does it?

Figure: Bad Example - Storing an AD Account as a String (AD Account is a complex type)

An AD Account is a complex type. Only certain strings are valid AD accounts. Sometimes you will want the string representation (SSW\Jason), sometimes you will need the domain name (SSW), and sometimes just the user name (Jason). All of this requires logic and validation, and the logic and validation cannot be provided by the string primitive type. Clearly, what is required is a more complex type such as a value object.

​

Figure: Good Example - Storing an AD Account as a Value Object to Support Logic and Validation

The underlying implementation for the AdAccount class is as follows:

Figure: Good Example - Implementation of the AdAccount Value Object Supports Logic and Validation

The AdAccount type is based on the ValueObject type, which you can view here; https://github.com/SSWConsulting/NorthwindTraders/blob/master/Northwind.Domain/Infrastructure/ValueObject.cs.

Working with the AD accounts will now be easy. You can construct a new AdAccount with the factory method For as follows:

The factory method For ensures only valid AD accounts can be constructed and for invalid AD account strings, exceptions are meaningful, i.e. AdAccountInvalidException rather than IndexOutOfRangeException.

Given an AdAccount named account, you can access:

1. The domain name using; account.Domain
2. The user name using; account.Name
3. The full account name using; account.ToString()

The value object also supports implicit and explicit conversion operators. You can:

1. Implicitly convert from AdAccount to string using; (string)account
2. Explicitly convert from string to AdAccount using; (AdAccount)"SSW\\Jason"

If you're using Entity Framework Core, you should also configure the type as follows:

Figure: Using Entity Framework Core to Configure Value Objects as Owned Entity Types

​With the above configuration in place, EF Core will name the database columns for the properties of the owned entity type as AdAccount_Domain and AdAccount_Name. You can learn more about Owned Entity Types by reviewing the EF Core documentation.​

Next time you are building an entity, consider carefully if the type you are defining is a primitive type or a complex type. Primitive types work well for storing simple state such as first name or order count, complex types work best when defining types that include complex logic or validation such as postal or email addresses. Using a value object to encapsulate logic and validation will simplify your overall design.