A Gentle Introduction to Onion Architecture in ASP.NET MVC – Part 2

In part 1 of this series we discussed what an onion architecture application would look like and discussed the technologies that we can leverage in .Net 4 in order to make that work. In this section we’ll go over how the project is structured, including spending a bit of time looking at how the IoC container is configured. This being a simple application the configuration is significantly easier to understand than it can be in more complex applications.

Project Structure

The application consists of 4 projects: Core, Infrastructure, Infrastructure.Tests, and Web. Each one of these projects has a unique purpose and it behooves all developers to ensure that they don’t mix concerns between projects.

Core Project

The core project is responsible for defining all interfaces for all services which will be implemented in the infrastructure layer, and it also is responsible for having all domain models. In Entity Framework Code First projects, the EF Entity Models can exist in Core. The models that exist in the sample application are not “true” domain models, instead they are just POCO representations

Infrastructure and Test Project

The infrastructure project is responsible for the implementation of all of the services defined in the Core Project. One of the critical distinctions between onion architecture and traditional layered applications is that the data access code (if there is any) will live in an infrastructure style project instead of living in the base/core layer. In the sample application the Infrastructure project only calls out to third-party services. The test project only tests the behavior of the composite service as I have not written this application in a sufficiently decoupled fashion to pass in the RestClient and ideally an abstraction would also be built around the ConfigurationManager

Web Project

As the name probably implies, this is where the “web” parts of the application go, including controllers, views, front-end assets, etc. For this application front end assets are just managed by downloading and saving them into /Scripts, and then everything is manually wired up using the BundleConfig.cs in App_Start. The interactivity within the application is achieved by using a little bit of jQuery.

Dependency Resolution

This application exposes 4 services in total, but only has 2 interfaces. This is due to the fact that the CompositeBounceCheckerService is composed of both MailgunService and SendGridService, hence all three of them share the same interface. The final service, the SuppressionListCheckService just consumes the CompositeBounceCheckerService. This final layer of indirection isn’t, strictly speaking, necessary, however it does afford the ability easily pass one of the service-specific IThirdPartyBounceService services as its dependency if we only wanted to check for suppression in a single ESP. The DefaultRegistry below shows how to get that all setup.

                .EnumerableOf<IThirdPartyBounceService>().Contains(x =>

This code basically tells StructureMap to scan all registered assemblies (all assemblies listed in the Scan call above this) and register the SendGridService and MailgunService as services within the composite service.

StructureMap is capable of doing a lot more, such as having custom life-cycles for certain services or handling weird object hierarchies (you can do a lot more than just have interfaces and services).


Testing is fairly direct as we just mock out the services that feed into the service we want to test (generally known as the “SUT” or the System Under Test). One easy example of a test is this:

        public void Get_Bounces_Returns_A_List_Of_View_Models()
            // Arrange
            var returnList = new List<SuppressedEmailViewModel>
                new SuppressedEmailViewModel
                    AddedOn = DateTime.Now,
                    EmailAddress = "[email protected]",
                    EmailServiceProvider = EspEnum.UNKNOWN,
                    ErrorCode = string.Empty,
                    ErrorText = string.Empty

            var mockService1 = new Mock<IThirdPartyBounceService>();
            mockService1.Setup(x => x.GetBounces()).Returns(returnList);
            // Initialize the composite service with an array of one third party service.
            var compositeService = new CompositeBounceCheckerService(new[] { mockService1.Object });

            //Act and Assert
            var result = compositeService.GetBounces();

            Assert.Equal(returnList, result);
            mockService1.Verify(x => x.GetBounces(), Times.Once);

The code above will first: create data for the Mock to return, then: create and setup the mock, then: inject it into the service, then: call the service, and finally: make sure that the behavior of the service was correct. Having a robust suite of tests allows us to change the implementation of any of the services and still verify that the output is correct.

When writing tests, I generally follow the AAA pattern (Arrange, Act, Assert) and leave comments in the code where those things are happening as an easy way to make sure that my tests are structured in a consistent fashion.

That’s all for now folks. I hope that this two part series on the onion architecture made the benefits of using it a bit more clear.

Please, check out the code on Github, and drop me a line if you have any questions!

A Gentle Introduction to Onion Architecture in ASP.NET MVC – Part 1

Welcome to part one of a multi part series on Enterprise Application in .Net Core! In this series we’ll go over everything that is necessary to build a best in breed enterprise application with the Onion Architecture at its core. The word enterprise is integral in describing the software being described as it is going to be software which is capable of being extended year after year in a clean fashion while allowing things to stay DRY and testable. We’ll cover the following:

  1. System to Design
  2. Initial Architecture and Architectural Considerations
  3. Proper Abstractions Around Each Layer of the “Onion”
  4. Unit Testing

This series of posts isn’t going to exhaustively walk you through every decision that may need to be considered (i.e. we’ll only very briefly discuss localization). My intention with these posts is to put forth my ideas of what a solid architecture looks like. With that being said, the application we are going to design is called “Block List Checker” which is an application which will allow one or more Email Service Providers (ESPs) such as Mailgun, SendGrid, etc. to be queried simultaneously to return a list of all email addresses which are on a suppression list. This is a very simple application which is intentionally somewhat over-engineered for the purposes of illustrating the various components of the system.

Inversion of Control and Dependency Injection

In order to design this software appropriately there are several tools that will need to be incorporated into the solution. The first (and arguably the most important) of these is StructureMap a .Net-friendly IoC/DI Container. For those not familiar: IoC (or Inversion of Control) and DI (or Dependency Injection) are design patterns which help make code much more testable. They do this by “inverting” the dependency chain. The way this plays out in MVC applications is that controllers will be injected with all of the dependencies that all of the services which are used by those controllers require. The IoC container will basically maintain a mapping of interfaces to services and, at runtime, will provide the controller with an instance of the service requested. Due to the fact that this effectively requires loose-coupling between components, writing unit tests becomes much easier (note that the description of IoC here is just barely skimming the surface, entire books have been written on this subject).

Unit Testing

Because this application is so simple, I have opted not to write comprehensive tests around it, however I have written a few tests just to demonstrate using xunit with this application and how the loose coupling allows the testing to be achieved.

Known Issues

This application is very basic and the UI could use a bit of love. It currently targets Asp.Net MVC5 instead of .Net Core MVC6 due to the fact that I prefer writing API access code using RestSharp, and that currently doesn’t seem compatible with .Net Core. I may release another sample project in the not distant future which targets .Net Core. It also currently doesn’t make use of either a proper front end framework, or of most of the functionality that MVC5 exposes on the front end. I haven’t written this application to be overly robust, and due to the nature of how it consumes API keys without any authentication I wouldn’t expose it on a publicly facing web server.

Get the code

With all that being said, the code is available here: https://github.com/lbearl/BlockListChecker.

Part Two of the series is available here

One Month Retrospective

One Month In

The company I work for recently started a new initiative: a brand new piece of software completely divorced from the software we traditionally worked on. I along with three of my colleagues were selected to lead the entire architecture and build out all of the core features. All four of us are somewhat experienced developers, but none of us has ever worked on an architecture team at the very beginning of a software project which is very much enterprise-class software.

Just to not confuse anyone, when I say enterprise-class or “big” software I’m specifically referring to software that is expected to grow to encompass multiple modules and have a code base in excess of 500 KLOC. For smaller applications the concerns I bring up here probably aren’t relevant. In this article I am specifically referring to software which is (hopefully) going to have a lifetime measured in many years if not decades with hopefully only minimal refactoring of the core structure.

What We Did

As happens so often in the software world, we were given a whole bunch of pretty “loose” requirements, and it was up to the four us with minimal direction to prioritize and implement everything that we needed. The project basically ended up being implemented in the following order:

  1. Project Layout (we used the Onion Architecture, which I have become a very big fan of)
  2. Initial Core Application Services
  3. Some development niceties that are ASP.NET specific (like things to ensure that we always have an Anti-Forgery Token, etc.)
  4. The Authentication and Authorization systems (using ASP.NET Identity)
  5. The logging framework
  6. Site Navigation and initial site pages for core things

What We Probably Should Have Done

While everything works with the order we did the work in, it is also causing a number of issues because as we finish certain tasks we then have to go back and update other code. The most painful item on this list is the logging framework. I am now thoroughly convinced that one of the first things that should be setup in any new large project is a logging framework. It doesn’t help much for development at the very beginning, but as soon as your first release happens and you push the application live to a web server or anywhere that isn’t a developer’s desktop that logging framework becomes your best friend when something breaks. We happen to be a 100% Microsoft shop, so we could always do something fancy with remote debugging, but that has issues of its own (including ensuring that you can reproduce the issue).

Lessons Learned

Large enterprise-scale software is challenging to design, there will always be a number of moving parts. As developers and architects it makes our lives easier if we take a step back from the initial problem and try to see if there are dependencies which don’t necessarily block development, but which will require a fair amount of rework in order to incorporate after the fact. Logging is probably an example that will be true for just about every software project out there, but another great example is a localization framework (I developed one that doesn’t use resx files because I don’t like that approach). At minimum before any views are created, the localization should be fleshed out, otherwise there will be a massive amount of rework (depending on what the view contains it may be almost a full rewrite).

I hope that anyone who reads this can not repeat the mistakes made, although these mistakes are hardly the most costly out there.