Delegates and Events

You already pass numbers and objects into methods. A delegate lets you pass a method the same way. It is a variable whose value is a method — you can store one, hand it to another method, keep a list of them, and call whatever is in it without knowing what it is.

Why would you want that? Because sometimes the caller knows the rule and the callee knows the process. A checkout knows how to total an order; it does not know which discount your marketing team invented this week. Handing the discount in as a value keeps the checkout out of that argument.

// A delegate type describes a shape: what goes in, what comes out.
public delegate decimal DiscountRule(decimal orderTotal);

public class Checkout
{
    public decimal FinalTotal(decimal total, DiscountRule rule) => rule(total);
}

public static class DiscountRules
{
    public static decimal None(decimal total) => total;

    public static decimal TenPercentOverFiveThousand(decimal total) =>
        total > 5_000m ? total * 0.9m : total;
}

Checkout checkout = new Checkout();

// Note: no parentheses. This stores the method, it does not call it.
DiscountRule rule = DiscountRules.TenPercentOverFiveThousand;

Console.WriteLine(checkout.FinalTotal(6_000m, rule));                    // 5400
Console.WriteLine(checkout.FinalTotal(6_000m, DiscountRules.None));      // 6000

// In practice you would use the built-in type instead of declaring your own.
Func<decimal, decimal> sameThing = DiscountRules.TenPercentOverFiveThousand;
Console.WriteLine(sameThing(6_000m));                                    // 5400

• public delegate decimal DiscountRule(decimal orderTotal); declares a type, not a method. It says: any method taking one decimal and returning a decimal fits here.
• DiscountRules.TenPercentOverFiveThousand with no parentheses is the method itself. Adding parentheses would call it and store the result instead, which is a common early slip.
• rule(total) inside FinalTotal calls whatever was passed in. The checkout has no idea which rule it is running.
• Func<decimal, decimal> is a delegate type the libraries already provide. The last type argument is the return type; the ones before it are the parameters. Because of Func and Action, writing your own delegate type is now uncommon — do it when the name genuinely helps, as DiscountRule arguably does.
• Compare this with defining an IDiscountRule interface with one method. Both work. The delegate is lighter when the abstraction is one operation; the interface is better when implementations need state or several related methods.

public class OrderSubmittedEventArgs : EventArgs
{
    public OrderSubmittedEventArgs(string reference, decimal total)
    {
        Reference = reference;
        Total = total;
    }

    public string Reference { get; }
    public decimal Total { get; }
}

public class OrderService
{
    // Outside code may only += and -=. It cannot raise this or clear it.
    public event EventHandler<OrderSubmittedEventArgs>? OrderSubmitted;

    public void Submit(string reference, decimal total)
    {
        // ... save the order first ...

        // ?. because the event is null until somebody subscribes.
        OrderSubmitted?.Invoke(this, new OrderSubmittedEventArgs(reference, total));
    }
}

public class WarehouseNotifier
{
    public void Watch(OrderService service)
    {
        service.OrderSubmitted += OnOrderSubmitted;
    }

    private void OnOrderSubmitted(object? sender, OrderSubmittedEventArgs e)
    {
        Console.WriteLine($"Picking list requested for {e.Reference}");
    }
}

• The event is declared nullable because a delegate with no subscribers is null, not an empty list. That is the single most common source of crashes in event code.
• ?.Invoke(...) reads the event once and calls it only if it is not null. Writing if (OrderSubmitted != null) OrderSubmitted(...) looks equivalent and is not: with more than one thread, the last subscriber can detach between the check and the call.
• this is passed as the sender so a handler can tell which object raised the event. The details go in the EventArgs subclass, where they are read-only.
• The subscriber attaches its own private method. Nothing in OrderService knows that WarehouseNotifier exists, which is the point — the publisher announces, and who listens is somebody else's decision.
• Invocation is synchronous. Submit does not return until every handler has finished, so a slow handler slows down order submission.

public sealed class OrderAuditLog : IDisposable
{
    private readonly OrderService _service;

    public OrderAuditLog(OrderService service)
    {
        _service = service;
        _service.OrderSubmitted += Record;       // subscribe
    }

    private void Record(object? sender, OrderSubmittedEventArgs e)
    {
        Console.WriteLine($"Audit: {e.Reference} for {e.Total:N2}");
    }

    public void Dispose()
    {
        _service.OrderSubmitted -= Record;       // and, equally important, unsubscribe
    }
}

// The trap. These two lambdas look identical and are two different methods.
service.OrderSubmitted += (sender, e) => Console.WriteLine(e.Reference);
service.OrderSubmitted -= (sender, e) => Console.WriteLine(e.Reference);   // removes nothing

// Keep a reference if a lambda subscription needs to be removed later.
EventHandler<OrderSubmittedEventArgs> handler = (sender, e) => Console.WriteLine(e.Reference);
service.OrderSubmitted += handler;
service.OrderSubmitted -= handler;                                        // this one works

• Holding the publisher in a field is what makes unsubscribing possible. A subscriber that cannot reach the publisher later has no way to detach.
• IDisposable gives the subscription an explicit end. In a using block or a framework that disposes its components, Dispose is where the -= belongs.
• -= matches on the target object and the method. Two separately written lambdas compile to two distinct methods, so removal silently does nothing — no exception, no warning, and the subscription stays.
• Assigning the lambda to a variable first gives you the one thing -= needs: the same delegate instance to remove.
• If you cannot control the subscriber's lifetime at all, the remaining options are a weak-reference event pattern or an explicit subscription object handed back by the publisher. Both are more machinery than most code needs, so reach for them when the ownership problem is real rather than by default.