What are records in C#? Explain record classes and record structs, what the compiler generates (value equality, ToString, Deconstruct, with-expressions), how equality works with inheritance, and where records are a poor fit.

1. Generated code (simplified)

public class Money : IEquatable<Money>
{
    public Money(decimal Amount, string Currency) { this.Amount = Amount; this.Currency = Currency; }
    protected Money(Money original) { Amount = original.Amount; Currency = original.Currency; }  // copy ctor

    public decimal Amount { get; init; }
    public string Currency { get; init; }
    protected virtual Type EqualityContract => typeof(Money);

    public virtual bool Equals(Money? other) =>
        (object)this == other ||
        (other is not null && EqualityContract == other.EqualityContract &&
         EqualityComparer<decimal>.Default.Equals(Amount, other.Amount) &&
         EqualityComparer<string>.Default.Equals(Currency, other.Currency));

    public override int GetHashCode() =>
        HashCode.Combine(EqualityContract, Amount, Currency);   // conceptually

    public virtual Money <Clone>$() => new Money(this);
    public void Deconstruct(out decimal Amount, out string Currency) { ... }
    protected virtual bool PrintMembers(StringBuilder builder) { ... }
    public override string ToString() { ... }
}

with compiles to var copy = original.<Clone>$(); copy.Amount = 20m; — calling init setters on the clone, which is allowed because it's part of object creation semantics.

2. Customising generated members

• Declare your own Equals(Money? other) and GetHashCode() to change equality (e.g. case-insensitive currency or sequence comparison for collections). If you declare Equals(T), also declare GetHashCode.
• Override PrintMembers to control ToString (e.g. redact).
• sealed override ToString() (C# 10) stops derived records regenerating it.
• Explicit property declarations can replace positional ones: public string Currency { get; init; } = Currency.ToUpperInvariant(); normalises input.

3. Validation and with

public sealed record Percentage
{
    public Percentage(decimal value) => Value = value is >= 0 and <= 100 ? value : throw new ArgumentOutOfRangeException(nameof(value));
    public decimal Value { get; init; }
}
var p = new Percentage(10) with { Value = 500 };   // bypasses the constructor check!

Validation in the constructor doesn't run for with. To protect invariants, validate in the init accessor (C# 14 field keyword makes this concise: public decimal Value { get; init => field = value is >= 0 and <= 100 ? value : throw ...; }), or don't expose init.

4. Record structs

• record struct generates the same members except EqualityContract, copy constructor and inheritance-related members.
• Equality is generated field-by-field (fast — no reflection, unlike ValueType.Equals), making record structs good dictionary keys.
• readonly record struct makes positional properties init-only and the struct readonly (avoids defensive copies).

5. Serialisation

System.Text.Json supports positional records via constructor binding (parameter names match property names, case-insensitively by default), init properties and required members. Record structs serialise like structs. Records are ideal API contracts and message types (e.g. for Azure Service Bus payloads).

6. Performance considerations

• Record class equality compares every field; GetHashCode hashes every field. For records with many fields used heavily in sets, consider custom equality on a key.
• with allocates a new object (record class).
• Record structs avoid allocation but are copied by value — keep them small.

Try it yourself

1. Decompile a record in SharpLab and read the generated members.
2. Compare a base and derived record with the same values for equality.
3. Create a record with a List<string> property and compare two instances with equal lists.
4. Show that with bypasses constructor validation, then fix it with an init accessor using field.

// Value object with validation
public sealed record Money
{
    public decimal Amount { get; init; }
    public string Currency { get; init; }

    public Money(decimal amount, string currency)
    {
        if (currency is not { Length: 3 }) throw new ArgumentException("ISO code required", nameof(currency));
        Amount = decimal.Round(amount, 2);
        Currency = currency.ToUpperInvariant();
    }
    public Money Add(Money other) =>
        other.Currency == Currency ? this with { Amount = Amount + other.Amount }
                                   : throw new InvalidOperationException("Currency mismatch");
}

// Positional records for messages
public record OrderPlaced(Guid OrderId, string CustomerId, Money Total, DateTimeOffset At);

// Value-type record for a strongly typed ID (no heap allocation)
public readonly record struct OrderId(Guid Value)
{
    public static OrderId New() => new(Guid.CreateVersion7());
    public override string ToString() => Value.ToString("N");
}

// Usage
var quote = new Money(100m, "aud");
var withGst = quote with { Amount = quote.Amount * 1.1m };
Console.WriteLine(quote == new Money(100m, "AUD"));   // True: value equality
var (amount, currency) = withGst;                     // needs Deconstruct; positional records get it free

// Inheritance and EqualityContract
public record Person(string Name);
public record Employee(string Name, string Team) : Person(Name);
Person p = new Person("Ana"), e = new Employee("Ana", "IT");
Console.WriteLine(p == e);                           // False