C# Records vs Record Structs: Immutability Explained

A record struct is not automatically immutable — that single misconception causes more production surprises than almost anything else in this module.

You already know records from Foundations: value-based equality, a readable ToString, and with expressions, all generated from a one-line declaration. That's the pitch. What Foundations didn't need to cover — but a production codebase absolutely does — is exactly what the compiler writes on your behalf, what happens when a record inherits from another record, and a genuinely dangerous trap: record struct is not automatically immutable the way a class-based record is. Get that one wrong and you've built a value type that silently invites the exact mutable-struct bugs the previous lesson just warned you about — wrapped in the deceptively safe-looking word "record."

In this lesson, you'll see exactly what the compiler generates for a positional record, the real difference between record class and record struct mutability, how record inheritance works (and why it's a class-only feature), and when a record struct genuinely beats a record class.

What Is It?

The Quick Recap

A record is a type declaration that gets compiler-generated value equality, a readable ToString, and with-expression support. record and record class mean the same thing — a reference type. record struct applies the same generated machinery to a value type. That's the Foundations-level summary. This lesson is about the parts that only matter once you're actually shipping records in production code.

The Mutability Rule That Trips Everyone Up

This is the single most important fact in this lesson, so it's stated plainly before anything else: a positional record class generates init-only properties by default; a positional record struct generates ordinary mutable { get; set; } properties by default. The two keywords look parallel — both say "record" — but their default mutability is opposite.

public record Point(int X, int Y);          // record class: X and Y are init-only — immutable

public record struct Coord(int X, int Y);    // record struct: X and Y are get; set; — MUTABLE!

var c = new Coord(1, 2);
c.X = 99; //  compiles fine — a plain record struct is a mutable value type

To get a genuinely immutable record struct, you must say so explicitly:

public readonly record struct Coord(int X, int Y); // NOW X and Y are init-only — truly immutable

var c = new Coord(1, 2);
c.X = 99; //  compile error — exactly what most people assumed "record struct" already gave them

Why Does It Exist?

The Problem

Before record struct (C# 10), if you wanted value-type semantics (stack allocation, copy-by-value, no GC pressure) and compiler-generated value equality, you had to hand-write it — a struct with a manually overridden Equals, GetHashCode, and ToString, exactly the same boilerplate records were invented to eliminate for classes.

The Need

Developers needed the record ergonomics — generated equality, printing, deconstruction, with — for small, frequently-copied value types too, without giving up struct's stack-allocation and copy-by-value characteristics.

The Solution — And Why Its Default Differs From record class

C# 10 added record struct, generating the same equality/printing/deconstruction/with machinery on a value type. But the language designers made record structs mutable by default, matching how ordinary structs had always defaulted — rather than immutable by default like record classes. The reasoning: an ordinary struct in C# has always defaulted to mutable fields, and changing that expectation specifically for record struct (while struct itself stayed mutable-by-default) would have been its own source of confusion. The trade-off is that you must opt in to immutability explicitly with readonly record struct — the same discipline the previous lesson recommended for any struct you design.

Big Picture

How It Works

public record Shape(string Name);
public record Circle(string Name, double Radius) : Shape(Name);

public record struct Shape2D(string Name);
public record struct Circle2D(string Name, double Radius) : Shape2D(Name); //  compile error

Shape s = new Circle("A", 5);
Shape s2 = new Shape("A");
Console.WriteLine(s == s2); // False — different RUNTIME TYPES, even though "Name" matches

Simple Example

// A genuinely immutable, value-typed coordinate — the idiomatic way to write one
public readonly record struct GeoCoordinate(double Latitude, double Longitude);

var a = new GeoCoordinate(51.5074, -0.1278);
var b = a with { Latitude = 51.51 }; // 'with' works on record structs too — produces a NEW value

Console.WriteLine(a);            // GeoCoordinate { Latitude = 51.5074, Longitude = -0.1278 }
Console.WriteLine(a == b);       // False — different Latitude
Console.WriteLine(a.GetType());  // GeoCoordinate — a genuine struct, no heap allocation for 'a' itself

Meaning: with works identically on record structs and record classes — it always produces a new value rather than mutating in place. For a readonly record struct, that's the only way to get a changed value at all, since there's no mutable setter to fall back on.

Real-World Example

A game or simulation tracking thousands of small position updates per frame is exactly where readonly record struct earns its keep — value semantics and equality checking, without heap allocation for every position.

public readonly record struct GridCell(int Row, int Col);

public class PathfindingGrid
{
    private readonly HashSet<GridCell> _visited = [];
    private readonly HashSet<GridCell> _obstacles;

    public PathfindingGrid(IEnumerable<GridCell> obstacles) => _obstacles = [.. obstacles];

    public bool TryVisit(GridCell cell)
    {
        if (_obstacles.Contains(cell) || !_visited.Add(cell))
            return false; // blocked, or already visited — GridCell's generated Equals/GetHashCode make this work correctly in a HashSet
        return true;
    }
}

var grid = new PathfindingGrid([new GridCell(2, 3), new GridCell(4, 1)]);
grid.TryVisit(new GridCell(0, 0));           // true — new cell
grid.TryVisit(new GridCell(0, 0) with { });   // false — already visited; value equality recognizes it as "the same cell"

Because GridCell is a readonly record struct, it can be used as a HashSet<T>/Dictionary<TKey,_> key correctly out of the box (generated GetHashCode/Equals) while living entirely on the stack or inline inside the set's internal storage — no per-cell heap allocation for thousands of grid positions, and no risk of a cell silently "changing under you" once it's been added to a set.

Analogy

Under the Hood

public class Point : IEquatable<Point>
{
    public int X { get; init; }
    public int Y { get; init; }

    public Point(int x, int y) { X = x; Y = y; }

    // Equality — compares runtime type AND every property
    public override bool Equals(object? obj) => Equals(obj as Point);
    public virtual bool Equals(Point? other) =>
        other is not null && GetType() == other.GetType() && X == other.X && Y == other.Y;
    public static bool operator ==(Point? a, Point? b) => a?.Equals(b) ?? b is null;
    public static bool operator !=(Point? a, Point? b) => !(a == b);
    public override int GetHashCode() => HashCode.Combine(X, Y);

    // Printing
    public override string ToString() => $"Point {{ X = {X}, Y = {Y} }}";

    // Destructuring — pairs with positional patterns (next lesson)
    public void Deconstruct(out int x, out int y) { x = X; y = Y; }

    // Backs 'with' — a protected "copy constructor" plus a hidden clone method
    protected Point(Point original) { X = original.X; Y = original.Y; }
    public virtual Point <Clone>$() => new Point(this);
}

Common Confusion

1. "It's a record, so it must be immutable" — false for record struct

This is worth repeating because it's the single most common wrong assumption: a plain record struct is mutable by default. "Record" guarantees you get generated equality, printing, and with support — it does not, by itself, guarantee immutability for the struct variant. Only readonly record struct does.

2. Record inheritance is not the same feature as struct-vs-class inheritance in general

Record classes support the exact same single-inheritance rules ordinary classes always have — nothing new there. The one genuinely new wrinkle records add is that equality automatically becomes type-aware across the hierarchy (a base-typed reference to a derived record still compares correctly, as shown in "How It Works"), something you'd otherwise have to hand-write carefully.

3. A record struct's Equals is not virtual, and that's fine

Class-based record equality is virtual to support the inheritance chain correctly. A record struct's generated members are never virtual, because structs can't be inherited from — there's no polymorphism to support. This isn't a missing feature; it's simply not applicable to a sealed-by-nature value type.

Common Mistakes

Mistake 1 — Writing record struct when you meant "immutable value type"

public record struct Money(decimal Amount, string Currency); for something you intend to treat as an immutable value — this compiles, and every property is silently mutable.

public readonly record struct Money(decimal Amount, string Currency); — make the intent explicit and enforced.

Mistake 2 — Trying to make a record struct inherit from another record

public record struct Base(int A);
public record struct Derived(int A, int B) : Base(A); //  compile error

If you need an inheritance hierarchy of data types, use record class (which supports it); if you specifically need value-type semantics, compose or duplicate the shared shape instead — value types never support inheritance, records included.

Mistake 3 — Assuming a derived record's equality only checks its own new properties

public record Shape(string Name);
public record Circle(string Name, double Radius) : Shape(Name);

Shape a = new Circle("X", 5);
Shape b = new Shape("X");
Console.WriteLine(a.Equals(b)); // False — many assume this is True because "Name" matches

Generated equality always compares the runtime type first — a Circle is never equal to a plain Shape, even with matching shared properties, exactly because they represent genuinely different kinds of data.

When Should I Use It?

• Use record class for most data models — DTOs, domain events, snapshots — especially any that benefit from an inheritance hierarchy (e.g. a family of related event types).
• Use readonly record struct when the data is small, genuinely value-shaped, copied or compared frequently (dictionary/set keys, coordinates, small tuples-with-names), and you specifically want to avoid heap allocation.
• Avoid a plain, mutable record struct in almost all cases — if you find yourself reaching for it, ask whether you actually wanted readonly record struct instead; the mutable form reintroduces exactly the mutable-struct hazards from the previous lesson.

Mental Model

Key Takeaway

Check Your Understanding

You've seen what the compiler generates for a record, and — critically — the mutability trap between record class and record struct. Let's check your understanding.

You now know exactly what a record generates, and — most importantly — the mutability trap that separates record struct from readonly record struct.