Leveraging C# Record Types for Immutable Domain Models

Because of these traits, records are an excellent fit for **domain models** where you want an object that represents a fact about the system and never changes.

Real‑World Example: Modeling an Order Aggregate

Imagine we need to track an Order in our system. An order consists of a unique identifier, a customer, a collection of line items, and a status. The status can transition only a few times, and once an order is shipped we must not allow further changes.

Below is a production‑ready set of record types that we shipped in a recent project. The code includes validation in the constructor and a few helper methods, all while staying immutable.

public record Customer(string Id, string Name, Email Email)
{
    // Immutable, automatically generates Equals, GetHashCode, ToString
    public Email Address => Email; // convenience property
}

public record Email(string Value)
{
    // Small value object – also immutable
    public override string ToString() => Value;
}

public record Money(decimal Amount, string Currency)
{
    // Helper for addition – returns a new Money instance
    public Money Add(Money other)
    {
        if (Currency != other.Currency)
            throw new InvalidOperationException("Cannot add money with different currencies.");
        return new Money(Amount + other.Amount, Currency);
    }
}

public record LineItem(Guid Id, Product Product, int Quantity, Money UnitPrice)
{
    public Money Total => UnitPrice * Quantity;
}

public record Order
(
    Guid Id,
    Customer Customer,
    IReadOnlyList Items,
    OrderStatus Status
)
{
    // Immutable collection – we expose a read‑only view
    public IReadOnlyList Items { get; } = Items ?? new List();

    // Business rule: Shipped orders cannot be modified
    public Order Ship()
    {
        if (Status != OrderStatus.Pending)
            throw new InvalidOperationException("Only pending orders can be shipped.");
        return this with { Status = OrderStatus.Shipped };
    }

    // Convenience method to calculate the order total
    public Money GetTotal() => Items.Aggregate(Money.Zero, (acc, li) => acc.Add(li.Total));
}

public enum OrderStatus { Pending, Shipped, Cancelled }

// Extension method to create a zero Money amount
public static class MoneyExtensions
{
    public static Money Zero(this object _) => new Money(0m, "USD");
}

Notice how each record is defined with positional syntax. The Order record uses the with expression in Ship to create a new instance with an updated status, preserving immutability.

Advanced Patterns: Pattern Matching and Deconstruction

Because records implement Deconstruct automatically when you declare positional fields, we can easily unpack them in a using statement or a switch expression. This is handy when we need to log or serialize domain objects.

// Example of deconstruction for logging
public static void LogOrderDetails(Order order)
{
    using var _ = order.Deconstruct(out var id, out var customer, out var items, out var status);
    Console.WriteLine($"Order {id} belongs to {customer.Name} and has {items.Count} items.");
}

// Switch expression to handle different order states
public static string Describe(Order order) => order.Status switch
{
    OrderStatus.Pending => $"Order {order.Id} is awaiting processing.",
    OrderStatus.Shipped => $"Order {order.Id} has been dispatched.",
    OrderStatus.Cancelled => $"Order {order.Id} was cancelled.",
    _ => "Unknown status."
};