📝 Lesson 3.1: Records and Value Equality

What Is a Record?

Many types exist just to bundle a few related values — a Point, a Product, an API response. Writing those as full classes means a lot of boilerplate: properties, a constructor, equality logic, a ToString. A record gives you all of that automatically.

Here's a class and the equivalent record. Both hold a name and age — but look at the difference in effort:

// As a class — lots of boilerplate
class PersonClass
{
    public string Name { get; init; }
    public int Age { get; init; }
    public PersonClass(string name, int age) { Name = name; Age = age; }
}

// As a record — one line, and you get MORE (equality + ToString)
record PersonRecord(string Name, int Age);

Positional Records

That one-liner is a positional record. The parameters in parentheses become read-only properties automatically, and you get a matching constructor for free:

record Product(string Name, string Category, decimal Price);

Product keyboard = new Product("Keyboard", "Electronics", 45m);

Console.WriteLine(keyboard.Name);    // Keyboard
Console.WriteLine(keyboard.Price);   // 45

Records also generate a readable ToString out of the box — great for debugging:

Console.WriteLine(keyboard);
// Product { Name = Keyboard, Category = Electronics, Price = 45 }

Value vs. Reference Equality

This is the headline feature. With a normal class, two objects are "equal" only if they're the same object in memory — that's reference equality. Two separate class objects with identical data are considered different:

class PointClass
{
    public int X { get; init; }
    public int Y { get; init; }
}

var a = new PointClass { X = 1, Y = 2 };
var b = new PointClass { X = 1, Y = 2 };

Console.WriteLine(a == b);        // False — different objects in memory
Console.WriteLine(a.Equals(b));   // False

A record instead compares by the values it holds — value equality. Two records with the same data are equal:

record PointRecord(int X, int Y);

var c = new PointRecord(1, 2);
var d = new PointRecord(1, 2);

Console.WriteLine(c == d);        // True — same values!
Console.WriteLine(c.Equals(d));   // True

Immutability and with

Positional record properties are immutable by default — once created, they can't be changed (they use init accessors, settable only during construction):

record Product(string Name, string Category, decimal Price);

Product p = new Product("Keyboard", "Electronics", 45m);
// p.Price = 50m;   // ❌ Error — records are immutable by default

Immutability is a feature: data that can't change under you is easier to reason about. But what if you need "the same product but cheaper"? Use a with-expression to create a modified copy, leaving the original untouched:

Product original = new Product("Keyboard", "Electronics", 45m);

Product discounted = original with { Price = 40m };

Console.WriteLine(original.Price);     // 45 — unchanged
Console.WriteLine(discounted.Price);  // 40 — a new copy with one change

Deconstruction

Positional records can be deconstructed — unpacked into separate variables in one step, mirroring how they were constructed:

record Point(int X, int Y);

Point p = new Point(3, 4);

var (x, y) = p;          // deconstruct into x and y
Console.WriteLine($"x = {x}, y = {y}");   // x = 3, y = 4

Record vs. Class

Records don't replace classes — they're a better fit for a specific job. Here's how to choose:

💡 Rule of thumb: If a type is mostly a bundle of values and two instances with the same data should count as equal, use a record. If a type is about behavior and identity — a BankAccount, a Game, a service — use a class.

Exercise & Quiz

record Money(string Currency, decimal Amount);

// TODO: create two equal Money values and compare with ==
// TODO: use 'with' to make a copy with a new Amount
// TODO: deconstruct a Money into (currency, amount)

record Money(string Currency, decimal Amount);

var m1 = new Money("USD", 50m);
var m2 = new Money("USD", 50m);
Console.WriteLine(m1 == m2);          // True — value equality

var raised = m1 with { Amount = 75m };
Console.WriteLine(m1);                 // Money { Currency = USD, Amount = 50 }
Console.WriteLine(raised);            // Money { Currency = USD, Amount = 75 }

var (currency, amount) = m1;
Console.WriteLine($"{amount} {currency}");   // 50 USD

True
Money { Currency = USD, Amount = 50 }
Money { Currency = USD, Amount = 75 }
50 USD

Summary

📚 Additional Resources

• Records — C# reference
• Record types — fundamentals
• with expression — reference

🚀 What's Next?

Records pair beautifully with our next topic. In Lesson 3.2: Pattern Matching, you'll test and deconstruct values with expressive switch expressions and type patterns — turning tangled if chains into clear, concise code.