Events: letting objects notify each other

Why events?

When a customer places an order, many things should happen: send an SMS, send an email, update stock, award loyalty points. If the Order class called all of these directly, it would depend on every other part of the system, and adding a new reaction would mean editing Order. With an event, Order just announces "order placed", and each part subscribes on its own.

Declaring and raising an event

public class OrderPlacedEventArgs : EventArgs
{
    public int OrderId { get; }
    public decimal Amount { get; }
    public OrderPlacedEventArgs(int orderId, decimal amount) { OrderId = orderId; Amount = amount; }
}

public class OrderService
{
    public event EventHandler<OrderPlacedEventArgs>? OrderPlaced;

    public void Place(int orderId, decimal amount)
    {
        // ... save the order ...
        OnOrderPlaced(new OrderPlacedEventArgs(orderId, amount));
    }

    protected virtual void OnOrderPlaced(OrderPlacedEventArgs e) => OrderPlaced?.Invoke(this, e);
}

Subscribing and unsubscribing

var service = new OrderService();

service.OrderPlaced += (sender, e) => Console.WriteLine($"SMS: order {e.OrderId} confirmed");
service.OrderPlaced += SendEmail;

service.Place(1001, 799m);

service.OrderPlaced -= SendEmail;     // stop listening
service.Place(1002, 250m);

static void SendEmail(object? sender, OrderPlacedEventArgs e)
    => Console.WriteLine($"Email: receipt for Rs {e.Amount}");

What the event keyword adds

An event is a delegate with a protective wrapper. Outside code can only add (+=) and remove (-=) handlers. It cannot raise the event, and it cannot wipe out everyone else's handlers with =. Only the class that declares the event can raise it.

// service.OrderPlaced = null;                  // error: only += and -= allowed outside
// service.OrderPlaced?.Invoke(null, args);     // error: cannot raise from outside

Where you will meet events

• Desktop UI: button.Click += OnSaveClicked; in Windows Forms and WPF.
• Timers: System.Timers.Timer raises Elapsed every interval.
• File watching: FileSystemWatcher raises Created and Changed when files appear or change.
• Games: Unity code often uses C# events (or UnityEvents) for "player died" or "coin collected".

Common mistakes and fixes

• Raising without ?.: OrderPlaced(this, e) throws NullReferenceException when nobody subscribed. Use OrderPlaced?.Invoke(this, e).
• Never unsubscribing: the publisher keeps a reference to each subscriber, so long-lived publishers can keep short-lived objects alive (a memory leak). Use -= when the subscriber is done.
• Trying to unsubscribe a lambda by writing the same lambda again: it is a different delegate, so nothing is removed. Store the lambda in a variable, or use a named method.
• Slow work inside handlers: handlers run one after another on the same thread; a slow one delays the rest.