Domain-Driven Design

By the end of this lesson you'll be able to model a business in code using the domain experts' own language — building value objects that make invalid states impossible, entities with identity, and aggregates whose roots guard the rules that must always hold. This is how large C# systems stay correct as they grow.

1. The Ubiquitous Language

The ubiquitous language is a shared vocabulary that the developers and the domain experts both use — in conversation, in documents, and in the code itself. If the business says "confirm an order", you write order.Confirm(), not order.SetStatus(2). The payoff is that misunderstandings surface early and the code becomes a living description of the business. When the language in your classes drifts from the language in the meeting room, bugs hide in the gap.

// ❌ Anaemic & technical — the rule is invisible
order.Status = 2;
order.Items.Add(item);

// ✅ Ubiquitous language — the rule is the method
order.Confirm();          // refuses to confirm an empty order
order.AddItem(product, price, qty);

2. Value Objects

A value object has no identity — it's defined entirely by its values, so two with the same values are interchangeable (10 GBP is 10 GBP). They're immutable (never change after creation) and self-validating (an invalid one can't exist). In C# a record is ideal: it's immutable by default and gives you value equality for free, so == compares contents, not references. Read this worked example and run it, then you'll build your own.

using System;

// A VALUE OBJECT has no identity — it is defined entirely by its values.
// Two banknotes both worth 10 GBP are interchangeable: you don't care WHICH
// note you hold, only how much it is worth. So 10 GBP == 10 GBP, full stop.
//
// A C# 'record' is the perfect tool: it is immutable (no setters) and gives
// you VALUE EQUALITY for free — two records with the same values are equal.
public record Money(decimal Amount, string Currency)
{
    // The domain rules live INSIDE the type,
...

Your turn. The program below builds a Distance value object and compares two of them — it just needs the record keyword and the equality operator. Fill in the two ___ blanks, then run it.

using System;

// 🎯 YOUR TURN — build a Distance VALUE OBJECT, then compare two of them.
// A value object is immutable and compared BY VALUE, so 5 km == 5 km.

// 1) Make this a record so you get immutability + value equality for free.
public ___ Distance(decimal Kilometres)   // 👉 the keyword is  record
{
    public override string ToString() => $"{Kilometres} km";
}

class Program
{
    static void Main()
    {
        var trip1 = new Distance(5m);
        var trip2 = new Distance(5m);     
...

3. Entities & Identity

An entity is the opposite of a value object: it has identity. Two customers called "Sam Lee" are different people, each with their own Id, and you compare entities by that identity — never by their attributes. An entity's data changes over time (a customer earns points), but its identity never does. Crucially, an entity should change its own state only through methods that enforce its invariants — the rules that must always be true.

using System;

// An ENTITY is the opposite of a value object: it HAS identity.
// Two customers named "Sam Lee" are NOT the same person — each has its own Id,
// and we compare entities by that Id, never by their attributes.
// An entity's data can change over time, but its identity never does.
public class Customer
{
    public Guid Id { get; }                 // identity — set once, never changes
    public string Name { get; private set; }
    public int LoyaltyPoints { get; private set; }


...

Now you try. Finish the Thermostat entity so it has its own identity and a method that refuses any temperature outside 5–30. Fill in the two ___ blanks:

using System;

// 🎯 YOUR TURN — finish the Thermostat ENTITY.
// It has identity (an Id) and an invariant: temperature stays within 5-30.
public class Thermostat
{
    public Guid Id { get; }
    public int Temperature { get; private set; }

    public Thermostat()
    {
        // 1) Give this entity its own unique identity.
        Id = ___;                     // 👉 a brand-new id:  Guid.NewGuid()
        Temperature = 20;
    }

    // SetTo must ENFORCE the invariant: reject anything outsi
...

4. Aggregates, Roots & Invariants

An aggregate is a cluster of related objects you treat as a single unit whenever you change them — for example an Order together with its line items. One entity is the aggregate root: it's the only way in. Outside code never touches the children directly, so the root can guarantee its invariants always hold (you can't confirm an empty order; you can't change a confirmed one). The list of children stays private and is exposed only as a read-only view, so nobody can sneak a change past the rules. Read this and run it.

using System;
using System.Collections.Generic;
using System.Linq;

// An AGGREGATE is a cluster of related objects treated as one unit for changes.
// The AGGREGATE ROOT (Order) is the ONLY entry point: outside code never edits
// the line items directly, so the root can guarantee its invariants always hold.
public class Order
{
    public Guid Id { get; } = Guid.NewGuid();
    public bool IsConfirmed { get; private set; }

    // The list is PRIVATE; outsiders only get a read-only view. They c
...

public class Order
{
    public Guid CustomerId { get; }      // ✅ reference another aggregate by Id
    private List<OrderLine> _lines;       // ✅ own your children directly
    // public Customer Customer { get; } // ❌ don't hold the whole customer object
}

5. Repositories

A repository gives the domain the illusion of an in-memory collection of aggregates: you ask for an Order by Id and get the whole thing back, with no SQL or Entity Framework leaking into your business logic. There's one repository per aggregate, and it always loads and saves the aggregate as a unit. The application code depends only on the interface — a domain concept — so the domain layer stays pure and testable. This example needs a database to run, so read it rather than running it.

// A REPOSITORY gives you the illusion of an in-memory collection of aggregates.
// It hides the database: the domain asks for an Order by Id and gets one back,
// with no SQL or EF Core leaking into the business logic. One repo per AGGREGATE.

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id);     // load a whole aggregate
    Task AddAsync(Order order);             // persist a new aggregate
    Task SaveChangesAsync();                // commit the unit of work
}

// The application layer depends only on the INTERFACE (a domain concept),
// never on the concrete data-access class. That keeps the domain pure.
public class PlaceOrderHandler
{
    private readonly IOrderRepository _orders;

    public PlaceOrderHandler(IOrderRepository orders) => _orders = orders;

    public async Task HandleAsync(Guid orderId)
    {
        var order = await _orders.GetByIdAsync(orderId)
            ?? throw new InvalidOperationException("Order not found");

        order.Confirm();                    // pure domain behaviour
        await _orders.SaveChangesAsync();   // infrastructure does the rest
    }
}

6. Domain Events

A domain event records something that happened in the domain, named in the past tense — OrderConfirmed, FundsWithdrawn. The aggregate raises the event to announce a fact, without knowing who reacts to it. That decouples side effects — sending an email, writing an audit log, reserving stock — from the core rules. The one discipline: dispatch events only after the change is saved, or a failed save will have already fired emails for an order that doesn't exist. This needs a dispatcher to run, so read it.

// A DOMAIN EVENT records something that HAPPENED in the domain, in the past
// tense (OrderConfirmed, FundsWithdrawn). It lets the aggregate announce a fact
// without knowing — or caring — who reacts to it. That decouples side effects
// (emails, audit logs, stock updates) from the core business rules.

public interface IDomainEvent { DateTime OccurredAt { get; } }

public record OrderConfirmed(Guid OrderId) : IDomainEvent
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
}

public class Order
{
    private readonly List<IDomainEvent> _events = new();
    public IReadOnlyList<IDomainEvent> Events => _events.AsReadOnly();

    public bool IsConfirmed { get; private set; }

    public void Confirm()
    {
        if (IsConfirmed) return;
        IsConfirmed = true;
        // The aggregate RAISES the event; it does not send the email itself.
        _events.Add(new OrderConfirmed(Id: Guid.NewGuid()));
    }
}

// A separate handler reacts AFTER the aggregate is saved. Dispatch events only
// once the change is committed — otherwise a failed save fires emails for nothing.
public interface IHandle<T> where T : IDomainEvent { Task On(T e); }

public class SendReceiptEmail : IHandle<OrderConfirmed>
{
    public Task On(OrderConfirmed e) => Task.CompletedTask; // ... send the email
}

7. Bounded Contexts

In a big system, one word means different things to different teams. To Sales, a "Customer" is a lead with a phone number and a deal size; to Support, a "Customer" is a ticket history; to Billing, it's a payment method and an invoice address. A bounded context is an explicit boundary — usually one module, service, or microservice — inside which a model and its ubiquitous language are consistent. Trying to make one giant Customer class serve every team produces a bloated mess that pleases no one. Instead, each context keeps its own focused model and they integrate at the edges (by Id, events, or APIs).

// Sales context
public class Customer { public string Name; public decimal DealSize; }

// Support context — same person, different concerns
public class Customer { public List<Ticket> Tickets; public string Tier; }

// Billing context
public class Customer { public PaymentMethod Card; public Address Invoice; }

using System;
using System.Collections.Generic;
using System.Linq;

// 🎯 MINI-CHALLENGE: Build a ShoppingCart AGGREGATE
// 1. Field: a PRIVATE List of CartItem, exposed only as IReadOnlyList.
// 2. AddItem(string name, decimal price): refuse it once the cart is checked out.
// 3. A bool IsCheckedOut property with a private setter.
// 4. Checkout(): throw if the cart is EMPTY, otherwise set IsCheckedOut = true.
//    (This is the invariant — you can't check out an empty cart.)
// 5. A Total prop
...