Comments

Layered Architecture in ASP.NET Core Applications

One of the viewers of my YouTube channel asked me an interesting question. He mentioned in a typical layered architecture, he sees ASP.NET MVC building blocks (Controller, View, and Model) as part of the presentation layer. These days, however, a lot of modern applications are built with Angular/React on the client and ASP.NET Core (Web API) on the server. So, what is the presentation layer in this kind of architecture? Let’s see!

With this stack, we have the following layers:

  • Presentation
  • Service
  • Business Logic/Application Core
  • Data Access/Persistence

Presentation Layer

Your Angular components, their templates, and the models you define in your Angular app are all presentation layer artifacts.

Service Layer

The confusing thing about this layer is that the term “service” is overloaded and it means different things to different people. In the context of a layered architecture, it wraps an application and exposes the application functionality in terms of a simple API that the user interface can talk to. This is the classic definition. Think of it as the glue between the presentation and business logic layers.

Now, in our modern stack, our logical service layer is physically composed of two parts: one part is on the client (Angular HTTP services) and the other part is on the server (ASP.NET Core controllers). These Angular services and ASP.NET Core controllers are very cohesive. The methods on these services (eg CourseService.getCourses()) talk directly to the endpoints exposed by your ASP.NET Core controllers.

Business Logic Layer

In your ASP.NET Core controllers, you often use repository interfaces (ICourseRepository), domain classes (Course) and services (PhotoService). All these are part of the business logic layer. They represent the core of an application irrespective of any presentation or persistence frameworks.

Note that here I’m talking about repository interfaces and not their implementations. These implementations are part of the data access/persistence layer.

Also, note that the services we have here are responsible for orchestration. For example, when adding a photo to a course, first, you need to store that photo in the file system (or some other kind of storage), and then you need to add it to the database (using a repository interface). Here is an example:

// Store the file first 
var uploadsPath = Path.Combine(host.WebRoot, "uploads");
if (!Directory.Exists(uploadsPath))
    Directory.CreateDirectory(uploadsPath);

var fileName = Guid.NewGuid().ToString() + Path.GetExtension(file.FileName);
var filePath = Path.Combine(uploadsPath, fileName);

using (var stream = new FileStream(filePath, FileMode.Create))
{  
    file.Copyto(stream);
}

// Add a record to the database
var photo = new Photo { FileName = fileName };
repository.Add(photo);
unitOfWork.Complete(); 

You wouldn’t write all this logic inside an ASP.NET Core Controller. Imagine, tomorrow you decide to use a different framework. You want to re-use as much code as possible. By encapsulating this code in a service (PhotoService.AddPhoto()), you can switch from ASP.NET Core to a different framework with less effort.

But wait for a second…

Now, that strongly-opinionated developer comes and says: “But who does replace ASP.NET Core with something else? How often does that happen?” Let’s say never! By moving all this logic from a controller into a service, you put the responsibility where it really belongs. The result is cleaner, slimmer, easier to read and easier to test controllers.

Imagine a restaurant where the chef does it all. He’s at the door, welcoming guests, giving them a table, taking their order, then going in the kitchen, chopping the vegetables, cooking, washing the dishes, then coming out and giving the bill to the guests. Would you go to that restaurant? I hope not!

In a good and organized restaurant, there are a few people each focusing on only one job. The waiters/waitresses are purely responsible for welcoming the guests and giving them the bill. The chef is purely responsible for cooking. He or she doesn’t wash the dishes! By the same token, you should have classes that do only one thing and do it well. This is what we call separation of concerns. You should put the responsibility where it really belongs, even if you’re never going to change the presentation or persistence framework of your application.

So, once again, all your domain classes (Course), repository interfaces (ICourseRepository) and application services (PhotoService) are part of the business logic layer. They represent the core of your application completely decoupled from any presentation and persistence frameworks. This is what Uncle Bob defines as Clean Architecture.

Data Access Layer

This layer is all about persistence. Here we have implementations tightly coupled to Entity Framework (or other frameworks) for persisting and retrieving data. If you’re using Entity Framework, your DbContext belongs in this layer. So do UnitofWork and Repository implementations.

Splitting a Project

Now, a common (and bad) practice I’ve seen some developers do, is that they blindly split an ASP.NET project into multiple class libraries, one for each layer. And with this, they assume just because they have a class library called MyProject.BLL or MyProject.DAL, they have properly layered their application. But that’s not necessarily right.

What matters is the direction of dependency and coupling between classes, not folders or projects. You can easily organize your classes into folders and projects but these classes can be poorly coupled to each other, which results in spaghetti architecture. Read my blog post on the topic:

Should you split your ASP.NET MVC/Core projects?

 

If you learned something from this post, please share it and drop your comments/questions below.

Tags: , , , , ,
Comments

4 Common Mistakes with the Repository Pattern

As part of my new ASP.NET Core course, I’ve been encouraging my students to post their code to GitHub. While reviewing various solutions, I’ve encountered a few common mistakes in the implementation of the repository pattern.

One repository per domain

You should think of a repository as a collection of domain objects in memory. If you’re building an application called Vega, you shouldn’t have a repository like the following:

public class VegaRepository 
{
}

Instead, you should have a separate repository per domain class, like OrderRepository, ShippingRepository and ProductRepository.

Repositories that return view models/DTOs

Once again, a repository is like a collection of domain objects. So it should not return view models/DTOs or anything that is not a domain object. I’ve seen many students using AutoMapper inside their repository methods:

public IEnumerable<OrderViewModel> GetOrders() 
{
     var orders = context.Orders.ToList();

     return mapper.Map<List<Order>, List<OrderViewModel>(orders);
}

Mapping is not the responsibility of the repository. It’s the responsibility of your controllers. Your repositories should return domain objects and the client of the repository can decide if it needs to do the mapping. By mapping the domain objects to view models (or something else) inside a repository, you prevent the client of your repositories from getting access to the underlying domain object. What if you return OrderViewModel but somewhere else you need OrderDetailsViewModel or OrderSnapshotViewModel? So, the client of the repository should decide what it wants to map the Order object to.

Save/Update method in repositories

Yet another very common mistake! As I’ve explained in my YouTube video before, your repositories should not have a Save() or Update() method. I repeat: think of a repository as a collection of domain objects in memory. Do collections have a Save() or Update() method? No! Here’s an example:

var list = new List<int>();
list.Add(1);
list.Remove(1);
list.Find(1);

list.Save();    // doesn't exist!
list.Update();  // doesn't exist!

Another reason your repositories should not have a Save() method is because sometimes as part of a transaction you may work with multiple repositories. And then you want to persist the changes across multiple repositories in one transaction. Here’s an example:

orderRepository.Add(order);
orderRepository.Save();

shippingRepository.Add(shipping);
shippingRepository.Save();

Can you see the problem in this code? For each change, we need a separate call to the Save() method on the corresponding repository. What if one of these calls to the Save() method fails? You’ll end up with a database in an inconsistent state. Yes, we can wrap that whole thing inside a transaction to make it even more ugly!

A pattern that goes hand in hand with the repository pattern is the unit of work. With the unit of work, we can re-write that ugly code like this:

orderRepository.Add(order);
shippingRepository.Add(shipping);
unitOfWork.Complete();

Now, either both objects are saved together or none are saved. The database will always be in a consistent state. No need to wrap this block inside a transaction. No need for two separate calls to the Save() method!

If you want to learn how to implement the repository and unit of work pattern together, watch my YouTube video here.

Repositories that return IQueryable

One of the reasons we use the repository pattern is to encapsulate fat queries. These queries make it hard to read, understand and test actions in ASP.NET MVC controllers. Also, as your application grows, the chances of you repeating a fat query in multiple places increases. With the repository pattern, we encapsulate these queries inside repository classes. The result is slimmer, cleaner, more maintainable and easier-to-test actions. Consider this example:

var orders = context.Orders
    .Include(o => o.Details)
        .ThenInclude(d => d.Product)
    .Where(o => o.CustomerId == 1234);

Here we are directly using a DbContext without the repository pattern. When your repository methods return IQueryable, someone else is going to get that IQueryable and compose a query on top of it. Here’s the result:

var orders = repository.GetOrders()
    .Include(o => o.Details)
        .ThenInclude(d => d.Product)
    .Where(o => o.CustomerId == 1234);

Can you see the difference between these two code snippets? The only difference is in the first line. In the first example, we use context.Orders, in the second we use repository.GetOrders(). So, what problem is this repository solving? Nothing!

Your repositories should return domain objects. So, the GetOrders() method should return an IEnumerable. With this, the second example can be re-written as:

var orders = repository.GetOrders(1234);

See the difference?

What are the other issues you’ve seen in the implementation of the repository pattern? Share your thoughts!

If you enjoyed this article, please share it.

Tags: ,
Comments

Why I don’t like IEntity interfaces

One comment that keeps popping up in regards to my YouTube video about repositories (Repository Pattern, Done Right) is why I don’t like IEntity interfaces. So, let’s see.

The case for IEntity is to apply a constraint in the repository interfaces.

public interface IRepository<T> where T : IEntity 

I need to write another post about why you should avoid generic repositories. But for now, let’s just ignore it and focus on IEntity.

So, what’s the value of this constraint here? Does this force a developer from accidentally creating a repository for an integer?

public class IntRepository : IRepository<int>

Probably not! Those familiar with domain-driven design (DDD) argue that repositories are should be created for aggregate roots. So, this will stop a developer from creating a repository for an entity that is not an aggregate root, or a value object. So, perhaps it’s more accurate to call this interface IAggregateRoot (which is even worse than IEntity, as you’ll find out shortly).

With either IEntity or IAggregateRoot, a junior developer can bypass this “constraint” in just a second:

public class Money : IEntity
{
}

So, these marker interfaces don’t really stop anyone from creating a repository for the wrong type!

With these interfaces, every time you want to create a class, you need to write some additional code (noise) to mark it as an entity or aggregate. What is the value of this? I’ve never seen it! Hopefully, you can drop a comment and enlighten me.

What is an interface really?

An interface is a contract. When you declare an interface and implement it, all those implementations follow that contract. This gives you two benefits: extensibility and testability.

Think of the classic polymorphism example you read in your first object-oriented book.

IEnumerable<IShape> shapes = GetShapes();
foreach (var shape in shapes)
    shape.Draw(); 

Here, the type of the actual objects in our enumerable doesn’t really matter. We can “extend” this design, and define new shapes that implement this contract (IShape). At a minimum, they all will have a Draw method.

Another benefit of these contracts is that they help us mock dependencies of objects during unit testing. For example, we can unit test a controller or a service by providing a mock or fake repository. This way, we don’t need a database up and running to test the controller / service.

The case for IEntity

Look at this IEntity declaration. This is what I call a hollow interface.

public interface IEntity // or IAggregateRoot
{
}

What is the point of this interface? It’s an empty contract. What’s that supposed to mean “conceptually”? A contract that doesn’t enforce anything?! Really? Again, back to the first example, if you think by using these interfaces you prevent an inexperienced developer creating the wrong repository, you’re just fooling yourself.

Wait, I have a better solution!

Ok, Mosh, how about this interface?

public interface IEntity // or IAggregateRoot
{
    int Id { get; set; }
}

Not a hollow interface anymore! At least it enforces that every entity or aggregate root should have an Id, and that Id should be integer.

Wait… what if one of our entities needs a Guid as an Id?

Ok, what about IEntity<T>?

Here is another form of IEntity:

public interface IEntity<T> // or IAggregateRoot<T>
{
    T Id { get; set; }
}

This interface is even worse. Why? Look at how we use it:

public class Student : IEntity<int>

Read the code in plain English: class Student which is an entity of integer. What?! Entity of integer? (*my head spinning*).

Nonetheless, what value do you get from an interface like that? That every entity or aggregate root follows a contract? Would you be working with those IEntity or IAggregateRoot instances without caring what object is actually under the interface at runtime (like the polymorphism example I showed earlier)? Most likely not! You work with concrete types, like Student, Course, etc.

So, one more time, what’s the point of creating these contracts? To the best of my knowledge, nothing but extra noise in your code.

Unfortunately, interfaces are one of the least understood constructs of object-oriented programming languages. If you want to learn more about interfaces, check out my C# course: Classes, Interfaces and Object-0riented programming.

Tags: , , ,
Comments

Repositories or Command / Query Objects?

This is a follow up post to my YouTube video Repository Pattern, Done Right. If you haven’t seen this video, it’s best to watch it first, before continuing reading.

There have been many interesting questions in the discussion area and I’ve replied to most (if not all) of them. One that has come up a few times is:

Should we favour command/query objects over repositories?

A few have referred me to Jimmy Bogard’s post. So, in this post, I’ll be comparing these two approaches and pros / cons of each.

Before I get started, I need to emphasise: neither the repository pattern, nor command / query objects, are silver-bullets. Just because these architectural patterns exist, doesn’t mean you should use them in every single application. If your queries are simple enough (one or two lines), don’t worry about creating an abstraction over them. There is nothing wrong with writing them in your controllers (assuming a web application).

If you do, however, have fat queries that have bloated your controllers, you might want to consider one of these patterns to achieve “better separation of concerns”.

Repository vs Command / Query object

In a repository, we often have many methods, all related to a specific entity:

GetUpcomingGigs()
GetGigsIAmAttending()
GetMyGigs()
GetPopularGigs()

When you promote one of these methods to a class, you’ll end up with what we call a query object.


public class GetPopularGigsQuery
{
     private GigsContext _context;

     public GetPopularGigsQuery(GigsContext context) 
     {
          _context = context;
     }

     public IEnumerable<Gig> Execute() 
     {
          return _context.Gigs
                      .Where(...)
                      .Include(...)
                      .Include(...)
                      .Include(...)
                      .OrderByDescending(...)
                      .Take(10)
                      .ToList();
     }
}

So, what you see in the Execute() method here, used to be one of the methods of a class like GigsRepository. Now, we’ve promoted that to a class. Have we gained anything here? Absolutely not!

With this approach, if you have a repository with 5 methods, you’ll end up with 5 new classes in your application. Now, take into account how many repository classes you have and eventually how many command / query classes you’ll end up with. You’ll end up with an explosion of classes that don’t provide any additional value than a simple method.

When Command / Query objects provide value

When you want to execute some operation before and / or after the execution of the command / query. Sometimes, in large enterprise applications, you may want to check that the current user has permission to execute a given query (or command), and additionally you may want to log that somewhere.

Without using command / query classes, your repository methods would end up with a lot of duplicate logic:

public IEnumerable<Gig> GetPopularGigs()
{
     // authorisation logic 

     // logging logic 
     
     return _context.Gigs.......
}

public IEnumerable<Gig> GetUpcomingGigs()
{
     // authorisation logic 

     // logging logic 
     
     return _context.Gigs.......
}

At this point, by promoting a method to a class, you’ll have at least a couple of options in front of you to implement the same behaviour in a more elegant way. You can use the template or strategy pattern.

With the template pattern, you would define a base class for your commands or queries like this:

public abstract class Query 
{
      public void Execute()
      {
           // authorisation logic 

           // logging logic
 
           DoExecute();
      }

      abstract void DoExecute();
}

So, you write the authorization and logging logic only once, in the base Query or Command class. Then, when implementing an actual command or query, you override the DoExecute method:

public abstract class GetPopularGigsQuery : Query 
{
      public override DoExecute()
      {
           return _context.Gigs....
      }
}

With the strategy pattern, instead of using inheritance, you’d use composition to achieve the same thing. If you need more understanding of inheritance vs composition, check out my C# course: Classes, Interfaces and Object-oriented programming.

What about ASP.NET MVC action filters?

Mosh, aren’t action filters exactly for that? To execute some custom logic (e.g. like authorisation or logging) before each action? True! Then, why bother using the command / query pattern?

Good question! First, you don’t have to use the pattern, if you prefer to use ASP.NET MVC action filters. But what if, in the future, you decide to use a different web presentation framework that doesn’t have the concept of MVC filters? Tools and frameworks come and go. What is popular now, is not going to be popular in a few years time. There was a time we thought ASP.NET WebForms was so cool. Now, it’s almost a dead technology!

If you want to protect your application architecture from change of external tools and framework, you need to decouple it from them by creating your own abstractions. Command / query pattern is one of the ways to create such abstraction. If you switch over to a different presentation framework, you can take all your existing code and re-use it without modifying a single line, and more importantly, without breaking things along the way!

What if…

What if you’re not too concerned about decoupling your application architecture from external tools / libraries? What if you think this is overkill? That’s a perfectly valid argument. Then, don’t use these patterns. As I always say to my students: “Keep it simple”. Use MVC filters to achieve the same result, and if they won’t help you in the future, then you’d spend time solving that new problem, not now.

What if you don’t have such requirements like authorisation and logging before each query? Then, command / query objects don’t give you any additional value. You’ll just waste your time and energy writing more and more code.

What if you don’t have complex queries in the first place? Don’t bother with the repository pattern either!

Every pattern is designed to solve a specific problem. Don’t solve a problem that does not exist!

Till my next post, all the best my friends!

 

 

Tags: , , , ,
%d bloggers like this: