C# 9 Records Explained: Immutability, Value Equality and When to Use Them

using System;

// Positional record syntax — the compiler generates init-only properties,
// a constructor, Equals, GetHashCode, ToString, and Deconstruct automatically.
public record Money(decimal Amount, string Currency);

// You can also use the verbose form if you need custom logic on a property.
public record ProductSku
{
    public string Code { get; init; }  // init-only: set once, never changed
    public string Category { get; init; }

    public ProductSku(string code, string category)
    {
        // Validate in the constructor — records support this just like classes
        if (string.IsNullOrWhiteSpace(code))
            throw new ArgumentException("SKU code cannot be empty.", nameof(code));

        Code = code.ToUpperInvariant(); // normalise on the way in
        Category = category;
    }
}

class Program
{
    static void Main()
    {
        var price = new Money(9.99m, "USD");
        var samePriceAgain = new Money(9.99m, "USD");
        var differentCurrency = new Money(9.99m, "GBP");

        // Value equality — compares property values, not memory addresses
        Console.WriteLine(price == samePriceAgain);      // True
        Console.WriteLine(price == differentCurrency);   // False
        Console.WriteLine(price.Equals(samePriceAgain)); // True

        // Compiler-generated ToString shows all properties
        Console.WriteLine(price); // Money { Amount = 9.99, Currency = USD }

        // Deconstruction — unpack a record into individual variables
        var (amount, currency) = price;
        Console.WriteLine($"{amount} {currency}"); // 9.99 USD

        // Verbose-form record with validation
        var sku = new ProductSku("abc-123", "Electronics");
        Console.WriteLine(sku.Code); // ABC-123  (normalised to uppercase)
    }
}

using System;

public record ShippingAddress(
    string RecipientName,
    string Line1,
    string? Line2,
    string City,
    string PostalCode,
    string CountryCode
);

public record Order(
    Guid OrderId,
    string Status,
    ShippingAddress Destination,
    decimal TotalAmount
);

class Program
{
    static void Main()
    {
        var originalAddress = new ShippingAddress(
            RecipientName: "Alice Johnson",
            Line1: "42 Elmwood Drive",
            Line2: null,
            City: "Portland",
            PostalCode: "97201",
            CountryCode: "US"
        );

        var originalOrder = new Order(
            OrderId: Guid.NewGuid(),
            Status: "Pending",
            Destination: originalAddress,
            TotalAmount: 149.99m
        );

        // 'with' creates a brand-new record — originalOrder is NEVER modified
        var dispatchedOrder = originalOrder with { Status = "Dispatched" };

        // Apply a correction to just the postal code — everything else stays
        var correctedAddress = originalAddress with { PostalCode = "97202" };

        // 'with' also works on nested records, but you must replace the whole nested record
        var reRoutedOrder = originalOrder with
        {
            Destination = originalAddress with { City = "Seattle", PostalCode = "98101" }
        };

        Console.WriteLine($"Original  status : {originalOrder.Status}");   // Pending
        Console.WriteLine($"Dispatched status: {dispatchedOrder.Status}"); // Dispatched

        Console.WriteLine($"Same OrderId? {originalOrder.OrderId == dispatchedOrder.OrderId}"); // True
        Console.WriteLine($"Same object?  {ReferenceEquals(originalOrder, dispatchedOrder)}");  // False

        Console.WriteLine($"Original city  : {originalOrder.Destination.City}");    // Portland
        Console.WriteLine($"Re-routed city : {reRoutedOrder.Destination.City}");    // Seattle

        // Value equality compares the full graph of properties
        var duplicate = originalOrder with { };  // identical copy
        Console.WriteLine($"Equal to duplicate? {originalOrder == duplicate}");     // True
    }
}

using System;
using System.Collections.Generic;

// RECORD — value equality, immutable, great for DTOs and value objects
public record EmailAddress(string Value)
{
    // Custom validation in a compact primary constructor body
    public EmailAddress(string value) : this(value)
    {
        if (!value.Contains('@'))
            throw new ArgumentException("Not a valid email address.", nameof(value));
    }
}

// CLASS — reference equality, mutable state, represents a 'thing' with a lifecycle
public class UserSession
{
    public Guid SessionId { get; } = Guid.NewGuid();
    public string UserName { get; set; }  // can change during the session
    public List<string> VisitedPages { get; } = new();

    public UserSession(string userName) => UserName = userName;

    public void NavigateTo(string page) => VisitedPages.Add(page);
}

class Program
{
    static void Main()
    {
        // --- Record behaviour ---
        var email1 = new EmailAddress("alice@example.com");
        var email2 = new EmailAddress("alice@example.com");

        // Same value → considered equal. Perfect for use as dictionary keys.
        Console.WriteLine($"Emails equal: {email1 == email2}"); // True

        var emailLookup = new Dictionary<EmailAddress, string>
        {
            [email1] = "Alice Johnson"
        };
        // email2 works as the lookup key because it has the same value
        Console.WriteLine($"Name: {emailLookup[email2]}"); // Alice Johnson

        // --- Class behaviour ---
        var session1 = new UserSession("alice");
        var session2 = new UserSession("alice");

        // Different objects in memory → NOT equal, even with same data
        Console.WriteLine($"Sessions equal: {session1 == session2}"); // False

        // Classes are designed for mutable, evolving state
        session1.NavigateTo("/dashboard");
        session1.NavigateTo("/orders");
        Console.WriteLine($"Pages visited: {session1.VisitedPages.Count}"); // 2
    }
}

using System;

// Base record — shared properties for all payment events
public abstract record PaymentEvent(
    Guid PaymentId,
    DateTime OccurredAt,
    decimal Amount
);

// Derived records — each adds its own context
public record PaymentInitiated(
    Guid PaymentId,
    DateTime OccurredAt,
    decimal Amount,
    string PayerEmail          // extra field for this event type
) : PaymentEvent(PaymentId, OccurredAt, Amount);

public record PaymentSucceeded(
    Guid PaymentId,
    DateTime OccurredAt,
    decimal Amount,
    string TransactionReference // extra field for this event type
) : PaymentEvent(PaymentId, OccurredAt, Amount);

public record PaymentFailed(
    Guid PaymentId,
    DateTime OccurredAt,
    decimal Amount,
    string FailureReason
) : PaymentEvent(PaymentId, OccurredAt, Amount);

class Program
{
    static void ProcessEvent(PaymentEvent evt)
    {
        // Pattern matching on records is clean and exhaustive
        var description = evt switch
        {
            PaymentInitiated e  => $"Payment started by {e.PayerEmail}",
            PaymentSucceeded e  => $"Payment confirmed. Ref: {e.TransactionReference}",
            PaymentFailed e     => $"Payment failed: {e.FailureReason}",
            _                   => "Unknown payment event"
        };
        Console.WriteLine($"[{evt.OccurredAt:HH:mm:ss}] ${evt.Amount:F2} — {description}");
    }

    static void Main()
    {
        var paymentId = Guid.NewGuid();
        var now = DateTime.UtcNow;

        var initiated  = new PaymentInitiated(paymentId, now, 49.99m, "bob@example.com");
        var succeeded  = new PaymentSucceeded(paymentId, now.AddSeconds(2), 49.99m, "TXN-8821");
        var failed     = new PaymentFailed(paymentId, now, 49.99m, "Card declined");

        ProcessEvent(initiated);
        ProcessEvent(succeeded);
        ProcessEvent(failed);

        // IMPORTANT: type matters for equality
        // Even though all base properties match, these are DIFFERENT types
        PaymentEvent asBase = initiated;
        var anotherInitiated = new PaymentInitiated(paymentId, now, 49.99m, "bob@example.com");

        Console.WriteLine($"Same type, same values: {initiated == anotherInitiated}"); // True
        // Casting doesn't change what the object IS
        Console.WriteLine($"Base ref == derived:    {asBase == anotherInitiated}");    // True (same type at runtime)
    }
}