How do you use records well in production C#? Explain what the compiler generates for a record class (equality, EqualityContract, ToString, Deconstruct, copy constructor), how inheritance affects equality, why with is a shallow copy, the collection-equality trap, and where records fit or do not fit (DTOs, value objects, EF Core entities).

1. Generated code details

• Equals(Money? other): (object)this == other || (other is not null && EqualityContract == other.EqualityContract && EqualityComparer<decimal>.Default.Equals(<Amount>k__BackingField, other.<Amount>k__BackingField) && ...).
• Equality compares backing fields, including those of non-positional properties and any explicit fields.
• GetHashCode uses EqualityComparer<T>.Default.GetHashCode per field combined with multipliers.
• PrintMembers prints public fields and properties (not private), separated by commas.

2. Customisation rules

• If you declare Equals(R? other), you must also declare GetHashCode (compiler warns).
• You can't override Equals(object) directly in records (it's generated to call Equals(R?)).
• Declaring PrintMembers or ToString replaces generated ones; sealed override ToString() (C# 10) prevents derived regeneration.
• Explicit property declarations replace positional ones (e.g. to add validation or change accessibility).

3. Records and EF Core complex types

modelBuilder.Entity<Order>().ComplexProperty(o => o.ShippingAddress);
order.ShippingAddress = order.ShippingAddress with { Postcode = "2000" };   // EF detects value change

Complex types fit records perfectly; owned entity types have hidden identity and are less ideal for value semantics.

4. Serialisation

System.Text.Json binds positional records through the constructor (matching parameter names case-insensitively), supports init, required, and polymorphism with [JsonDerivedType] on abstract base records.

5. Performance

• Record class creation allocates like any class; with allocates a new instance.
• Equality on many fields costs more than reference equality; avoid huge records as hot dictionary keys.
• record struct avoids allocation for small values (see record structs).

Try it yourself

1. Decompile a record in SharpLab and read EqualityContract, PrintMembers and <Clone>$.
2. Compare base and derived records with equal base values.
3. Show that with shares a list.
4. Implement custom equality for a record with an ImmutableArray<T>.

using System.Collections.Immutable;
using System.Text;

public sealed record Money(decimal Amount, string Currency)
{
    public static Money Aud(decimal amount) => new(amount, "AUD");
    public Money Add(Money other) =>
        Currency == other.Currency ? this with { Amount = Amount + other.Amount }
                                   : throw new InvalidOperationException("Currency mismatch");
}

public sealed record OrderLine(string Sku, int Quantity, Money Price);

// Value equality over a collection: write it yourself
public sealed record OrderSnapshot(int OrderId, ImmutableArray<OrderLine> Lines)
{
    public bool Equals(OrderSnapshot? other) =>
        other is not null && OrderId == other.OrderId && Lines.SequenceEqual(other.Lines);

    public override int GetHashCode()
    {
        var hash = new HashCode();
        hash.Add(OrderId);
        foreach (var line in Lines) hash.Add(line);
        return hash.ToHashCode();
    }
}

public sealed record Basket(int Id, List<string> Items);   // List member: reference equality

public record Person(string Name, string Email)
{
    // Records are often logged: hide personal data from the generated ToString
    protected virtual bool PrintMembers(StringBuilder builder)
    {
        builder.Append($"Name = {Name}, Email = ***");
        return true;
    }
}

// The compiler generates PrintMembers for Employee that calls the base version, then appends StaffId
public sealed record Employee(string Name, string Email, int StaffId) : Person(Name, Email);

public static class Program
{
    public static void Main()
    {
        Console.WriteLine(Money.Aud(10) == Money.Aud(10));               // True: value equality
        Console.WriteLine(Money.Aud(10).Add(Money.Aud(5)));              // Money { Amount = 15, Currency = AUD }

        var a = new OrderSnapshot(1, [new OrderLine("A1", 2, Money.Aud(5))]);
        var b = new OrderSnapshot(1, [new OrderLine("A1", 2, Money.Aud(5))]);
        Console.WriteLine(a == b);                                        // True only because of the custom Equals

        var basket1 = new Basket(1, ["apple"]);
        var basket2 = new Basket(1, ["apple"]);
        Console.WriteLine(basket1 == basket2);                            // False: different List instances

        var copy = basket1 with { Id = 2 };
        copy.Items.Add("pear");                                           // shallow copy: shared list
        Console.WriteLine(basket1.Items.Count);                           // 2

        Person p = new("Mia", "[email protected]");
        Person e = new Employee("Mia", "[email protected]", 7);
        Console.WriteLine(p == e);                                        // False: different EqualityContract
        Console.WriteLine(e);                                             // Employee { Name = Mia, Email = ***, StaffId = 7 }
    }
}