Clean Architecture in .NET

By the end of this lesson you'll be able to split a .NET app into layers where the business rules sit at the centre, the database and email and web framework sit at the edges, and every dependency points inward — giving you a core you can unit-test in milliseconds and swap technologies without rewriting your logic.

1. The Layers & the Dependency Rule

A layer is just a group of classes with the same job, kept in its own project. The Domain is the heart — your entities and the rules they enforce, written in plain C# with no framework in sight. The Application layer holds use cases: thin orchestrators that drive the Domain to get something done. Infrastructure is the messy outside world — databases, email, HTTP. Presentation is the entry point — a controller or console Main. The one law tying them together is the Dependency Rule: source-code references only ever point inward. Read this worked example and run it.

using System;

// ═══════════════════════════════════════════════════════════════
// One file here for the runner, but imagine FOUR separate projects.
// The arrows show who is ALLOWED to reference whom. The golden rule:
// dependencies always point INWARD, toward the Domain. Nothing in
// the centre ever knows about the layers around it.
//
//   Presentation  ->  Application  ->  Domain  <-  Infrastructure
//   (controllers)     (use cases)     (rules)      (db, email, http)
// ════════════════
...

2. Ports & Adapters (Dependency Inversion)

Here's the puzzle: a use case needs to send email, but email is an outer concern — and inner layers can't depend on outer ones. The fix is the port & adapter pattern. A port is an interface defined in the inner layer ("someone must be able to notify a user"). An adapter is a class in Infrastructure that implements it (the real SendGrid call). The use case depends on the port, never the adapter — so even though data flows outward at runtime, the source-code dependency still points inward. That's dependency inversion, and it's the trick that makes the whole thing work.

using System;

// ═══════════════════════════════════════════════════════════════
// PORTS & ADAPTERS. A "port" is an interface the inner layers OWN.
// An "adapter" is an outer-layer class that implements it. The use
// case depends on the PORT (interface), never on the adapter — so
// the dependency arrow points INWARD, even though data flows out.
// ═══════════════════════════════════════════════════════════════

// ---------- APPLICATION owns the PORT (an interface = a promise) ----------
in
...

Your turn. The program below is almost complete — define a Domain entity that validates its input, and declare an Application port. Fill in the blanks marked ___ using the hints, then run it.

using System;

// 🎯 YOUR TURN — define a Domain entity and an Application port (interface).
// Replace each ___ then press "Try it Yourself".

// 1) DOMAIN entity: a User with a Name. The constructor must reject empty names.
class User
{
    public string Name { get; }

    public User(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new Exception("Name is required");
        Name = ___;          // 👉 store the validated name (just: name)
    }
}

// 2) APPLICA
...

3. Adapters & Use Cases That Point Inward

Now build the other half: an adapter that implements the port, and a use case that holds the interface type — not the concrete adapter. The adapter gets handed in from outside (this is dependency injection), so the use case stays blissfully ignorant of which implementation it's talking to. Get this right and you can drop in a fake adapter in your tests and a real one in production, changing nothing in between. Fill in the two blanks.

using System;

// 🎯 YOUR TURN — build an Infrastructure adapter and a use case that
// depends on the PORT, not the adapter. Fill in each ___.

// APPLICATION owns the port (given to you):
interface INotificationPort
{
    void Send(string message);
}

// 1) INFRASTRUCTURE adapter: implement the port. Just print the message.
class ConsoleAdapter : ___        // 👉 implement INotificationPort
{
    public void Send(string message)
        => Console.WriteLine($"🔔 {message}");
}

// 2) APPLICATI
...

// ❌ Domain coupled to the framework — avoid
public class Order { [Key] public int Id { get; set; } } // EF attribute leaks in

// ✅ Domain stays pure — the mapping lives in Infrastructure instead
public class Order { public Guid Id { get; private set; } } // plain C#

// A FAKE adapter — lives only in the test project
class FakeNotify : INotificationPort
{
    public string? LastMessage;
    public void Send(string to, string message) => LastMessage = message;
}

// The test: zero database, runs in microseconds
var fake = new FakeNotify();
var useCase = new WelcomeUser(fake);   // inject the fake instead of email
useCase.Run("Bob");
Assert.Equal("Welcome aboard, Bob!", fake.LastMessage);  // ✅ passes

using System;

// 🎯 MINI-CHALLENGE: a self-contained core with ZERO infra dependencies.
//
// Build these three pieces, then wire them in Main:
//   1. DOMAIN entity  Task(string title)  — reject an empty title.
//   2. APPLICATION port  ITaskStore  with  void Save(Task task);
//   3. INFRASTRUCTURE in-memory adapter  InMemoryTaskStore : ITaskStore
//      — keep a List<Task> and print "Saved: {title}" inside Save.
//   4. APPLICATION use case  AddTask  — its constructor takes an
//      ITaskS
...