The Basics of ASP.NET Core Middleware

Middleware in ASP.NET Core is a building block of the HTTP request pipeline. But what exactly is the HTTP request pipeline?

Imagine a series of interconnected stations, each performing a specific task. When a user sends a request to your ASP.NET Core web application, it doesn't immediately reach your application's core logic. Instead, it enters this pipeline. Each station in the pipeline, or each middleware component, has the opportunity to inspect, modify, or even short-circuit the request.

Here is how the Request flows:

1. Request Arrives at the Web Server (IIS or Kestrel):

• When a user sends a request, it first reaches your web server, typically either IIS (for Windows servers) or Kestrel (a cross-platform web server built into ASP.NET Core).

2. HttpContext is Generated:

• The web server then passes the request to the ASP.NET Core runtime. Here, HttpContext object is created from the request. This object holds all the details of the request, such as headers, the request body, and URL parameters.

3. Request Enters the Middleware Pipeline:

• The HttpContext object now enters the middleware pipeline, where a series of middleware process the request.

4. Middleware Components Process the Request:

• Each middleware component in the pipeline performs a specific task, in a defined order.

  • For example, an authentication middleware might check user login details from the HttpContext.

  • A logging middleware logs the information from the request.

  • An error handling middleware might manage any errors that occur during the request.

5. Routing Determines the Endpoint:

• After the middleware components have processed the request, the routing middleware determines which part of your application (endpoint) should handle it. This could be a controller action in your API or a page in your web application.

6. Endpoint Executes and generates a response:

• The selected endpoint then runs, using the information from the HttpContext and a response is generated.

7. Response Sent to User via Middleware (in Reverse Order):

• The generated response now travels back through the middleware pipeline, but in reverse order. This allows each middleware component to perform any necessary post-processing tasks before the web server (IIS or Kestrel) sends the final response back to the user.

Why Middleware?

Imagine building a Web API that requires a number of actions to be performed for every incoming request. You might need to handle user authentication and authorization, implement rate limiting, provide centralized exception handling, and maintain logs. Without a centralized solution, you'll likely end up with duplicated code and a difficult-to-maintain application.

Consider a common scenario: logging request information. Without middleware, you might have logging code scattered throughout your API endpoints:

public IActionResult GetData(int id)
{
    var requestPath = HttpContext.Request.Path;
    _logger.LogInformation($"Request to {requestPath} with id: {id}");
    // logic to get data
    return Ok(data);
}

public IActionResult CreateData(Data data)
{
    var requestPath = HttpContext.Request.Path;
    _logger.LogInformation($"Request to {requestPath}");
    // logic to create data
    return CreatedAtAction(nameof(GetData), new { id = data.Id }, data);
}

As you add more endpoints, this duplicated logging code becomes increasingly difficult to manage. If you need to change the logging behavior (e.g. add more details, change the log format), you'd have to modify it in multiple places.

To address this duplication issue, middleware effectively centralizes this common logging logic into a reusable component, applied to every request. This centralized approach simplifies development, enhances maintainability, and ensures consistency.

The Middleware Pipeline: Ordering Matters

The order in which middleware components are added to the pipeline is important. For instance, authentication middleware should typically come before authorization middleware. If the order is reversed, authorization might be attempted before the user's identity is established, leading to unexpected behavior. Similarly, error handling middleware should be placed early in the pipeline to catch exceptions thrown by subsequent components. If placed after other middleware, it might miss exceptions from earlier stages, resulting in unhandled errors.

As the diagram above illustrates, the sequence of middleware components directly affects the request/response flow. In this example, if the 'Endpoint Middleware' handles the request and generates a response, the request never reaches the 'Authentication' and 'Authorization' middleware.

Short-Circuiting the pipeline

Middleware can "short-circuit" the pipeline, stopping further processing and sending a response directly. This is crucial for security and performance.

For example, authentication middleware might return a 401 Unauthorized response, preventing unauthenticated requests from reaching your application. Similarly, error handling middleware placed early in the pipeline ensures that exceptions from other components are caught, preventing unhandled errors and potential security risks.

The diagram above demonstrates how authentication and authorization middleware interact and how short-circuiting can occur. Authentication middleware verifies user credentials, and if valid, associates the authenticated user with the current request. Authorization middleware then checks if the user is authorized to access the requested resource. If the user is not allowed, the authorization middleware will short-circuit the pipeline and generate an Unauthorized response, preventing the request from reaching the application's core logic.

Building a Custom Exception Handling Middleware with Logging

Middleware's way of managing requests gives you a lot of flexibility, and one great use is for handling errors and logging them yourself. This custom approach in your ASP.NET Core application can make things smoother for users and easier to figure out when things go wrong, beyond what the default settings offer.

Step 1: Creating the Custom Middleware

We define a custom middleware class, ExceptionHandlingMiddleware. This middleware follows the standard ASP.NET Core pattern, requiring a constructor that takes a RequestDelegate (representing the next middleware in the pipeline) and an InvokeAsync method that handles the request. We also inject an ILogger instance to enable logging of exceptions.

public class ExceptionHandlingMiddleware
{

    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(context, ex, _logger);
        }
    }

    private static async Task HandleExceptionAsync(HttpContext context, Exception exception, ILogger<ExceptionHandlingMiddleware> logger)
    {
        HttpStatusCode statusCode;
        string message;

        switch (exception)
        {
            case AuthenticationException ex:
                statusCode = HttpStatusCode.Unauthorized;
                message = "Authentication failed.";
                logger.LogWarning(exception, "Authentication failure.");
                break;
            case UnauthorizedAccessException ex:
                statusCode = HttpStatusCode.Unauthorized;
                message = "You are not authorized to access this resource.";
                logger.LogWarning(exception, "Unauthorized access attempt.");
                break;
            case KeyNotFoundException _:
                statusCode = HttpStatusCode.NotFound;
                message = "The requested resource was not found.";
                logger.LogWarning(exception, "Resource not found.");
                break;
            case ArgumentException _:
                statusCode = HttpStatusCode.BadRequest;
                message = "Invalid request parameters.";
                logger.LogWarning(exception, "Invalid request.");
                break;
            default:
                statusCode = HttpStatusCode.InternalServerError;
                message = "An unexpected error occurred. Please try again later.";
                logger.LogError(exception, "Unhandled exception occurred.");
                break;
        }

        context.Response.ContentType = "application/json";
        context.Response.StatusCode = (int)statusCode;

        var errorResponse = new { StatusCode = (int)statusCode, Message = message };
        var jsonResponse = JsonSerializer.Serialize(errorResponse);

        await context.Response.WriteAsync(jsonResponse);
    }
}

The InvokeAsync method operates by attempting to execute the subsequent middleware in the pipeline (_next(context)). If any exception is thrown during this process, the catch block is executed. Here, the exception is logged using the injected ILogger. The HandleExceptionAsync method then formats an error response as JSON, which is sent back to the client.

Step 2: Registering the Middleware

To integrate the ExceptionHandlingMiddleware into the request pipeline, it is registered in the Startup.cs or Program.cs(.Net core 6.0 and later) using app.UseMiddleware<ExceptionHandlingMiddleware>() . Because the goal is to capture all unhandled exceptions that might occur during the processing of a request, it's crucial to register this middleware early in the pipeline. This ensures that it wraps the execution of subsequent middleware components, allowing it to intercept any exceptions before they reach the default error handling mechanisms.

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.UseMiddleware<ExceptionHandlingMiddleware>();
app.UseAuthorization();

app.MapControllers();

app.Run();

Step 3: Testing the Middleware

To demonstrate the functionality of the ExceptionHandlingMiddleware, an API endpoint can be created to intentionally trigger an exception:

[ApiController]
[Route("api/[controller]")]
public class ErrorController : ControllerBase
{
    [HttpGet("trigger")]
    public IActionResult TriggerError()
    {
        throw new InvalidOperationException("This is a test exception from the ErrorController.");
    }
}

When a request is made to the /api/error/trigger endpoint, the InvalidOperationException will be thrown. Our ExceptionHandlingMiddleware will catch this exception, log it on the server, and return a JSON response to the client with a 500 Internal Server Error status code and a generic error message. The server-side logs will contain the detailed exception information.

The Power of Middleware: A Final Look

Understanding and utilizing ASP.NET Core middleware is essential for building effective web applications. From its role in the request pipeline to the creation of custom components like our exception handler, middleware offers powerful tools for managing request flow, handling errors, and implementing cross-cutting concerns. By embracing middleware, you gain significant control over your application's behavior and architecture.

Happy Coding!!

But for those who just need a quick refresher, here's the gist:

As you can see, the key idea is that dependencies point inwards, towards the domain core. But there's another crucial aspect: layers communicate exclusively through abstractions, not concrete implementations. This keeps our application flexible, maintainable, and testable. Each layer has a specific responsibility, and we'll be exploring how to implement them step by step in the following posts.

We're going to focus on the practical application of these principles, so let's get started!

Project Setup: Creating the Solution and Layers

1. Create Solution and Solution Folders:

   1. In Visual Studio, create a new "Blank Solution" named "OnionArchitectureGuide".

   2. Create Solution Folders named "Core", "Infrastructure", and "Presentation".

2. Create Domain Layer:

   1. Inside the "Core" Solution Folder, add a new "Class Library (.NET Standard/.NET Library)" project named "OnionArchitectureGuide.Domain".

3. Create Application Layer:

   1. Inside the "Core" Solution Folder, add a new "Class Library (.NET Standard/.NET Library)" project named "OnionArchitectureGuide.Application.Abstraction".

   2. Inside the "Core" Solution Folder, add a new "Class Library (.NET Standard/.NET Library)" project named "OnionArchitectureGuide.Application.Implementation".

4. Create Infrastructure Layer:

   1. Inside the "Infrastructure" Solution Folder, add a new "Class Library (.NET Standard/.NET Library)" project named "OnionArchitectureGuide.Persistence".

5. Create Presentation Layer:

   1. Inside the "Presentation" Solution Folder, add a new "ASP.NET Core Web API" project named "OnionArchitectureGuide.Api".

Note: Application layer is split into OnionArchitectureGuide.Application.Abstraction and OnionArchitectureGuide.Application.Implementation. The Presentation layer communicates with the Application layer, but it should not have direct access to implementations. Placing service interfaces and their implementations together violates the principles of Onion Architecture and creates tight coupling between layers. The outer layer should interact with the inner layer only through abstractions, not concrete implementations.

Your Folder Structure Look like this:

Setting up Project Dependencies:

Now, we need to set up the project dependencies according to the Onion Architecture principles. Remember, dependencies should point inwards.

1. OnionArchitectureGuide.Application.Implementation references OnionArchitectureGuide.Domain and OnionArchitectureGuide.Application.Abstraction.

2. OnionArchitectureGuide.Infrastructure references OnionArchitectureGuide.Application.Abstraction and OnionArchitectureGuide.Domain.

3. OnionArchitectureGuide.Api references OnionArchitectureGuide.Application.Abstraction

Here is a visual Representation of the Project Dependencies.

This dependency structure is crucial. The API depends on the Application layer, and Infrastructure depends on the Application and Domain Layer, and finally Application layer depends on the Domain layer. This keeps our core logic independent and allows us to easily swap out implementations. This inward dependency flow also ensures that changes in outer layers have minimal impact on the inner layers, enhancing stability. Furthermore, it allows for better testability as the core business logic can be tested in isolation.

We now have the basic project structure set up. In the next post, we'll start implementing Onion Architecture layer by layer.

Layer-by-Layer Implementation

Alright, we've laid the foundation, now lets construct Domain layer.

Constructing Domain Layer

Now, let's define our domain entities and repository interfaces within the OnionArchitectureGuide.Domain project. This layer holds our core business objects and their contracts.

Create Folder named Entities inside OnionArchitectureGuide.Core project and add classes:

public class Book
{
    public int BookId { get; set; }
    public string Title { get; set; }
    public DateTime PublishedOn { get; set; }
    public int AuthorId { get; set; }
    public Author Author { get; set; }
}

public class Author
{
    public int AuthorId { get; set; }
    public string Name { get; set; }
    public List<Book> Books { get; set; }
}

Create Contracts Folder inside OnionArchitectureGuide.Core project and add Repository Interfaces:

public interface IBookRepository
{
    Task<List<Book>> GetAllAsync();
}

public interface IAuthorRepository
{
    Task<List<Author>> GetAllAsync();
}

Your Domain layer should look like this:

The Core layer holds our domain model, free from external dependencies. This ensures core logic is reusable and maintainable.

Next, we'll create abstractions in the OnionArchitectureGuide.Application.Abstraction before implementing these contracts in the OnionArchitectureGuide.Application.Implementation.

Building Application Contracts (Abstraction)

Now that we've defined our domain entities and repository contracts in the Domain layer, let's move on to creating the application contracts in the OnionArchitectureGuide.Application.Abstraction project. This layer will define the DTOs and interfaces that our application services will implement.

Inside the OnionArchitectureGuide.Application.Abstraction project, create a folder named Contracts. This folder will hold our service interface definitions.

public interface IBookService
{
    Task<List<BookDto>> GetAllBooks();
}

public interface IAuthorService
{
    Task<List<AuthorDto>> GetAllAuthors();
}

Create DTOs Folder inside OnionArchitectureGuide.Application.Abstraction project and add Data transfer objects:

public class BookDto
{
    public int BookId { get; set; }
    public string Title { get; set; }
    public DateTime PublishedOn { get; set; }
}

public class AuthorDto
{
    public int AuthorId { get; set; }
    public string Name { get; set; }
}

Your OnionArchitectureGuide.Application.Abstraction project should look like this:

By defining these service interfaces and DTOs in a separate OnionArchitectureGuide.Application.Abstraction layer, we decouple our application's core logic from the specific implementations and the data transfer details. This allows us to easily switch out implementations or change data transfer formats without affecting the rest of the application.

Next, we'll implement these service contracts in the OnionArchitectureGuide.Application.Implementation.

Implementing Application Services

Alright, let's move on to the OnionArchitectureGuide.Application.Implementation project. We'll be focusing on implementing the service contracts and utilizing the DTOs we defined in the OnionArchitectureGuide.Application.Abstraction.

Before Implementing this layer, lets first install required packages from Nuget package manager or package manager console.

NuGet\Install-Package AutoMapper -Version 14.0.0

Lets Create Mapping Profiles now. Create Folder named Mappings inside OnionArchitectureGuide.Application.Implementation project and add AutoMapper profiles:

internal class ApplicationProfile: Profile
{
    public ApplicationProfile()
    {
        CreateMap<BookDto, Book>().ReverseMap();
        CreateMap<Author, AuthorDto>().ReverseMap();
    }
}

Create Folder named Services inside OnionArchitectureGuide.Application.Implementation project and add service implementations:

public class BookService : IBookService
{
    private readonly IBookRepository _bookRepository;
    private readonly IMapper _mapper;
    public BookService(IBookRepository bookRepository, IMapper mapper)
    {
        _bookRepository = bookRepository;
        _mapper = mapper;
    }
    public async Task<List<BookDto>> GetAllBooks()
    {
        return _mapper.Map<List<BookDto>>(await _bookRepository.GetAllAsync());
    }
}

internal class AuthorService : IAuthorService
{
    private readonly IAuthorRepository _authorRepository;
    private readonly IMapper _mapper;
    public AuthorService(IAuthorRepository authorRepository, IMapper mapper)
    {
        _authorRepository = authorRepository;
        _mapper = mapper;
    }
    public async Task<List<AuthorDto>> GetAllAuthors()
    {
        return _mapper.Map<List<AuthorDto>>(await _authorRepository.GetAllAsync());
    }
}

This layer contains the core business logic of our application. By keeping it separate from the presentation and infrastructure layers, we ensure that our business logic is reusable and testable.

Before implementing Infrastructure layer, lets register all the Dependencies for this layer.

Create a file named ApplicationServiceExtensions.cs in the root level of the OnionArchitectureGuide.Application.Implementation project.

The OnionArchitectureGuide.Application.Implementation layer should look like this:

Now, register all the dependencies for this project:

public static class ApplicationServiceExtensions
{
    public static void AddApplicationServices(this IServiceCollection services)
    {
        //Registering all the automapper profiles
        services.AddAutoMapper(Assembly.GetExecutingAssembly());

        services.AddScoped<IBookService,BookService>();
        services.AddScoped<IAuthorService,AuthorService>();
    }
}

Next, we'll integrate the infrastructure layer to handle data access and implement repositories.

Integrating Infrastructure

Now that we've implemented our application services in the OnionArchitectureGuide.Application.Implementation project, let's integrate the Infrastructure layer (OnionArchitectureGuide.Persistence). The main purpose of this layer is to handle data access, external API integrations, and other infrastructure-related concerns. Since this is a simple implementation, we will only focus on data access and Repository implementation.

Make sure you have installed Microsoft.EntityFrameworkCore , Microsoft.EntityFrameworkCore.SqlServer and Microsoft.EntityFrameworkCore.Tools packages for SQL Server connection, Database operations and Migrations.

Run these commands in Package Manager Console:

NuGet\Install-Package Microsoft.EntityFrameworkCore -Version 9.0.3

NuGet\Install-Package Microsoft.EntityFrameworkCore.SqlServer -Version 9.0.3

NuGet\Install-Package Microsoft.EntityFrameworkCore.Tools -Version 9.0.3

After packages are installed, create Data Folder, which will hold our data access(DbContext).

internal class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<Book> Books { get; set; }
    public DbSet<Author> Authors { get; set; }
}

Create Folder named Repositories, which holds the repository implementations that we declared in the domain layer.

internal class BookRepository : IBookRepository
{
    private readonly ApplicationDbContext _context;

    public BookRepository(ApplicationDbContext context)
    {
        _context = context;
    }

    public async Task<List<Book>> GetAllAsync()
    {
        return await _context.Books.ToListAsync();
    }
}

internal class AuthorRepository : IAuthorRepository
{
    private readonly ApplicationDbContext _context;

    public AuthorRepository(ApplicationDbContext context)
    {
        _context = context;
    }

    public async Task<List<Author>> GetAllAsync()
    {
        return await _context.Authors.ToListAsync();
    }
}

Now lets register all the dependencies for the Infrastructure layer in the Dependency Injection container.

Create a file named InfrastructureServiceExtensions.cs in the root level of the OnionArchitectureGuide.Persistence project.

Your OnionArchitectureGuide.Presistence should look like this:

Register Infrastructure Dependencies as:

public static class InfrastructureServiceExtensions
{
    public static void AddInfrastructureServices(this IServiceCollection services, string connectionString)
    {
        //Registering Application DbContext and Seeding Values
        services.AddDbContext<ApplicationDbContext>(options =>
        {
            options.UseSqlServer(connectionString);
            options.UseSeeding((context, _) =>
            {
                var book = context.Set<Book>().FirstOrDefault();
                if (book == null)
                {
                    context.Set<Book>().AddRange(BookSeeds());
                    context.SaveChanges();
                }
            })
            .UseAsyncSeeding(async (context, _, cancellationToken) =>
                {
                    var book = context.Set<Book>().FirstOrDefaultAsync();
                    if (book == null)
                    {
                        context.Set<Book>().AddRange(BookSeeds());
                        await context.SaveChangesAsync();
                    }
                });

        });
        services.AddScoped<IBookRepository, BookRepository>();
        services.AddScoped<IAuthorRepository, AuthorRepository>();
    }
    private static List<Book> BookSeeds()
    {
        return new List<Book> { 
            new Book { Title = "Book 1", Author= new Author(){ Name ="XXX"} }, 
            new Book { Title = "Book 2", Author= new Author(){ Name ="YYY"} }
            };
    }
}

Infrastructure layer isolates our application's core logic from specific data access and external dependencies. This allows us to easily switch out data access implementations or integrate with different external systems without affecting the rest of the application.

Next, we'll expose our application through an API in the Presentation layer.

Exposing the Application (API)

Now that we've integrated the Infrastructure layer, let's expose our application's functionality through an API in the Presentation layer. This layer will handle incoming requests and outgoing responses. We'll also configure our dependencies and set up the connection string for our data access.

Inside the OnionArchitectureGuide.Api/Controllers, add new API controllers BookController.cs and AuthorController.cs and create endpoints as shown below.

[Route("api/[controller]")]
[ApiController]
public class BookController : ControllerBase
{
    private readonly IBookService _bookService;
    public BookController(IBookService bookService)
    {
        _bookService = bookService;
    }

    [HttpGet("get-books")]
    public async Task<IActionResult> GetBooks()
    {
        return Ok(await _bookService.GetAllBooks());
    }
}

[Route("api/[controller]")]
[ApiController]
public class AuthorController : ControllerBase
{
    private readonly IAuthorService _authorService;

    public AuthorController(IAuthorService authorService)
    {
        _authorService = authorService;
    }

    [HttpGet("get-authors")]
    public async Task<IActionResult> GetBooks()
    {
        return Ok(await _authorService.GetAllAuthors());
    }
}

We're almost there, but first, we must register all necessary dependencies from OnionArchitectureGuide.Application.Implementation and OnionArchitectureGuide.Infrastructure.

Currently, our OnionArchitectureGuide.Api project only references OnionArchitectureGuide.Application.Abstraction. While we could add references to OnionArchitectureGuide.Application.Implementation and OnionArchitectureGuide.Infrastructure directly, I prefer to handle dependency registration in a separate class library dedicated to managing these dependencies. This keeps our API project cleaner.

The OnionArchitectureGuide.Api project should not directly communicate with OnionArchitectureGuide.Application.Implementation or OnionArchitectureGuide.Infrastructure via concrete implementations. We should avoid using ApplicationDbContext, repositories, or service implementations directly in the API project. This is why all implementations have internal access modifiers.

To achieve this, let's create a new "Class Library (.NET Standard/.NET Library)" project named OnionArchitectureGuide.DependencyManager within the 'Presentation' solution folder. Then, add project references to OnionArchitectureGuide.Application.Implementation and OnionArchitectureGuide.Infrastructure to this new project.

The Dependency Flow should look like this:

Here is a screenshot of the OnionArchitectureGuide.Api and Dependency Manager.

Lets manage dependencies:

public static class DependencyManager
{
    public static void RegisterApplicationDependencies(this IServiceCollection services)
    {
        services.AddApplicationServices();
    }

    public static void RegisterInfrastructureDependencies(this IServiceCollection services, string connectionString)
    {
        services.AddInfrastructureServices(connectionString);
    }
}

Register all Dependencies in Program.cs of OnionArchitectureGuide.Api project.

//Register Application and Infrastructure services using Dependency manager
// you can also register directly from OnionArchitectureGuide.Application.Implementation and OnionArchitectureGuide.Presistence
//E.g. builder.Services.AddApplicationServices(); and builder.Services.AddInfrastructureServices(builder.Configuration.GetConnectionString("DefaultConnection") ?? String.Empty);

builder.Services.RegisterApplicationDependencies();
builder.Services.RegisterInfrastructureDependencies(builder.Configuration.GetConnectionString("DefaultConnection")?? String.Empty);

Add ConnectionString to appsettings.json

"ConnectionStrings": {
  "DefaultConnection":  "Your connection string"
}

One last step before we run our application.

Running Migration:

Install Microsoft.EntityFrameworkCore.Design package in OnionArchitectureGuide.Api project, for the migration to work.

NuGet\Install-Package Microsoft.EntityFrameworkCore.Design -Version 9.0.3

• Open Package Manager Console, set Default project to OnionArchitectureGuide.Persistence.

• Set a Project Startup to OnionArchitectureGuide.Api.

• Run: Add-Migration InitialMigration then Update-Database

add-migration initialMigration

update-database

We're now ready to run our application. Ensure all dependencies are correctly registered and the connection string is properly configured before proceeding.

• Run the OnionArchitectureGuide.Api project.

• Use Postman or Swagger to send requests to the API endpoints.

Example Output:

Congratulations! You've successfully built a simple application using Onion Architecture. We've navigated through each layer, implementing the core logic and exposing it through an API.

Now that you've grasped the fundamentals, it's time to put this knowledge into practice. Start by exploring how you can apply these principles to your own projects. Consider:

• Refactoring existing code: Identify areas where you can apply Onion Architecture to improve maintainability.

• Expanding your application: Add new features and functionalities, ensuring they fit within the established architecture.

• Experimenting with different technologies: Explore how Onion Architecture can be adapted to various databases, frameworks, and external systems.

Keep exploring, keep coding, and keep building robust applications. Thank you for joining me on this practical journey. Happy Coding!

Before we get into the details of Onion Architecture, let's talk about why we switched. It wasn't just about fixing that database problem; we wanted a system that was easier to maintain and change in the future.

Why We Chose Onion Architecture?

So, why did we pick Onion Architecture? Well, after that database change mess, we took a hard look at our old setup. We realized it had some serious issues that were slowing us down:

• Everything Was Mixed Together: Changing one thing broke other things.

• Business Rules were Hard to Find: Our main logic was spread all over.

• Hard to add new features: Adding new features took way longer than it should have.

• Hard to understand: New team members had a really hard time understanding the code.

We needed something to fix this. Onion Architecture looked good because:

• Things don't depend on each other: Our main code wouldn't depend on databases or the user interface.

• Business rules are the most important: Our main logic is at the center and untouched.

• Easy to swap out technology: If we wanted to change database or UI technology, it would be much easier.

• Easy to integrate third-party services: It would be much easier to integrate third-party services like email services, payment integration, etc.

• Code is easier to understand: The code becomes more organized and easier to follow.

So, we knew Onion Architecture was the answer for us. But what does it actually look like inside?

As you can see, it's like an onion, with different rings inside. Each ring has its own job. The important thing is how these rings talk to each other, or more importantly, how they don't talk to each other. Let's break down each layer and see what it does.

Layers of Onion Architecture

1. Domain Layer

It's the innermost layer, containing your core business logic and entities. This layer is incredibly important because it's almost entirely untouched by changes happening around it. It's pure business logic, meaning it doesn't care about databases, user interfaces, or any other external factors. It's just the rules and data that make your business work.

The Domain Layer typically contains:

• Entities: These are the core business objects, like 'Customer,' 'Order,' or 'Product.'

• Aggregates: Collections of related entities treated as a single unit.

• Repository Interfaces: Definitions of how to access and persist entities, without specifying the actual implementation.

• Domain Events: Notifications of significant changes within the domain.

• Value Objects: Immutable objects that represent domain concepts.

2. Application Layer

The Application Layer coordinates how your app uses its core logic. It sits between the Domain Layer and the UI/external layers, connecting them without exposing the Domain directly.

The Application Layer typically contains:

• Application Services: These services define the application's use cases. They receive requests directly from the UI or other outer layers and instruct the Domain Services on what to do.

• Data Transfer Objects (DTOs): These objects handle the transfer of data between the Application Layer and the outer layers, keeping the Domain Layer isolated from external data structures.

• Interfaces: This layer defines interfaces that the Infrastructure Layer will implement. This ensures that the Application Layer remains independent of specific infrastructure implementations.

3. Infrastructure Layer

The Infrastructure Layer connects your app to the outside world. It handles databases and other external services. It's the 'where' your app interacts. This layer changes most but doesn't affect the core logic.

The Infrastructure Layer typically contains:

• Database Implementations: This is where the actual code for interacting with databases resides. It implements the repository interfaces defined in the Domain Layer.

• API Integrations: This is where your application connects to external APIs, handling communication and data translation.

• External Service Integrations: This is where your application connects to external services like email, payment gateways, etc.

• Specific Technology Implementations: This is where any specific technological implementations live. For example, file system access, network communication etc.

4. Presentation Layer: It's the layer users interact with directly, whether it's a web page, mobile app, or desktop application.

So, that's how the Onion Architecture works! We have different layers, and we know how they talk to each other. Remember, the middle part (Domain Layer) should stay clean.

Onion vs N-Layered Architecture

We have seen how Onion architecture works, now let’s see how it is better than N-Layered Architecture.

1. Dependency Direction:

• N-Layered: Each layer depends on the layer below it. This creates a fragile structure where changes in lower layers can ripple through the entire application.

• Onion: Dependencies point inwards, towards the core business logic. This isolates the core, making changes in outer layers less risky.

2. Testability:

• N-Layered: Testing becomes complex due to tight coupling. Changes in one layer often require multiple layers testing.

• Onion: The isolated core allows for easier unit testing of business logic, leading to more reliable code.

3. Maintainability:

• N-Layered: Code becomes harder to maintain as dependencies grow. Changes require careful coordination across multiple layers.

• Onion: The clear separation of concerns simplifies maintenance. Changes in infrastructure or UI don't impact the core logic.

4. Separation of Concerns:

• N-Layered: Business logic can bleed into other layers, making the code harder to understand and evolve.

• Onion: Enforces a clean separation, with each layer having a distinct responsibility.

In essence: Onion Architecture prioritizes a stable core, making your application more adaptable to change. It's about building an architecture that evolves**.**

Real-World Scenarios: When Onion Architecture Fits (and When It Doesn't)

Onion Architecture shines in projects with complex business rules, evolving needs, microservices, TDD, long-term maintenance, and when large teams work on separate modules.

It's less ideal for simple CRUD apps, small projects, performance-critical systems (sometimes), or when your team lacks familiarity.

Choose Onion when you need stability, flexibility, and clear module separation for complex projects, especially with larger teams. OPT for simpler architectures for basic or short-term needs.

From Scenarios to Practice: Seeing Onion in Action

Now that we've seen when Onion Architecture fits, let's look at a practical code example. To provide you with a real-world context, I've created a simple project to demonstrates the key principles we've discussed, which is available on GitHub:

Conclusion: Building Maintainable and Scalable Applications

Onion Architecture offers a powerful way to build maintainable and scalable applications. While it might seem complex at first, its benefits become clear as your application grows.

By understanding and applying Onion Architecture, you can build applications that are easier to test, maintain, and evolve. Happy coding!