Same interface, extra behavior, zero changes to the original class — and you can stack more than one.

Suppose EmailNotificationSender works fine, but now you need every send attempt logged, and separately, you need failed sends automatically retried. You could edit EmailNotificationSender directly to add logging and retry logic — but now every other class that also implements INotificationSender needs the same edit repeated, and you've permanently coupled "sending an email" with "logging" and "retrying," even for the one caller that doesn't want retries.

The Decorator Pattern — a Structural pattern, one of the three GoF categories from the design patterns lesson earlier in this Part — solves this by wrapping an object instead of editing it. A decorator implements the exact same interface as the thing it wraps, holds a reference to it, and adds behavior before, after, or around each delegated call — leaving the original class, and every other instance of it, completely untouched.

In this lesson, you'll learn the mechanical shape of Decorator, build a logging-and-retry notification sender by stacking two decorators together, and see the general principle behind it.

What Is It?

The Simple Explanation

A decorator wraps an object of the same type, adding behavior around it without changing its source code or affecting other instances. From the outside, a decorated object looks and is used exactly like the thing it wraps — because it implements the same interface — but calling it also runs the decorator's extra logic.

The Technical Definition

Attach additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality — instead of an EmailSenderWithLoggingAndRetry subclass (which locks that specific combination in permanently), you compose small, single-purpose wrapper objects at runtime, in whatever combination a given caller actually needs.

Why Does It Exist? — The Problem It Solves

Without Decorator, adding a cross-cutting behavior to one class tends to either bloat that class directly, or spawn a combinatorial explosion of subclasses:

//  WITHOUT Decorator — logging and retry logic baked directly into the class,
// mixed in with the class's actual job (sending an email)
public sealed class EmailNotificationSender : INotificationSender
{
    public async Task SendAsync(string recipient, string message)
    {
        Console.WriteLine($"Sending to {recipient}...");           // logging concern
        for (int attempt = 1; attempt <= 3; attempt++)              // retry concern
        {
            try
            {
                await SmtpClient.SendAsync(recipient, message);
                Console.WriteLine("Sent successfully.");            // logging concern
                return;
            }
            catch (SmtpException) when (attempt < 3) { }
        }
    }
}
// Want an SmsNotificationSender with the SAME logging+retry behavior?
// Copy-paste this whole mess again. Want a sender with logging but NOT retry?
// You can't — they're welded together inside one method.

Big Picture — Stacking Decorators

Each layer only knows about the layer immediately inside it, through the shared INotificationSender interface. EmailNotificationSender was never edited to add logging or retry — both were bolted on entirely from the outside, and can be added, removed, or reordered independently.

How It Works

Simple Example

public interface INotificationSender
{
    Task SendAsync(string recipient, string message);
}

// ── The real worker — never modified, has no idea it's wrapped ──
public sealed class EmailNotificationSender : INotificationSender
{
    public Task SendAsync(string recipient, string message)
    {
        Console.WriteLine($"[Email] To {recipient}: {message}");
        return Task.CompletedTask;
    }
}

// ── A decorator — same interface, wraps another INotificationSender, adds behavior ──
public sealed class LoggingNotificationSender(INotificationSender inner) : INotificationSender
{
    public async Task SendAsync(string recipient, string message)
    {
        Console.WriteLine($"[Log] Sending to {recipient}...");
        await inner.SendAsync(recipient, message);       // delegate to the wrapped instance
        Console.WriteLine("[Log] Send completed.");
    }
}

// ── Usage ──
INotificationSender sender = new LoggingNotificationSender(new EmailNotificationSender());
await sender.SendAsync("alice@example.com", "Your order shipped!");
// [Log] Sending to alice@example.com...
// [Email] To alice@example.com: Your order shipped!
// [Log] Send completed.

Code → Meaning → Result: sender is typed as INotificationSender — the calling code has no idea it's actually a LoggingNotificationSender wrapping an EmailNotificationSender. EmailNotificationSender's source code was never touched, and any other INotificationSender implementation could be logged the exact same way, for free.

Real-World Example — Stacking Logging AND Retry

public sealed class RetryingNotificationSender(INotificationSender inner, int maxAttempts = 3)
    : INotificationSender
{
    public async Task SendAsync(string recipient, string message)
    {
        for (int attempt = 1; attempt <= maxAttempts; attempt++)
        {
            try
            {
                await inner.SendAsync(recipient, message);   // delegate — success, done
                return;
            }
            catch (Exception) when (attempt < maxAttempts)
            {
                await Task.Delay(TimeSpan.FromSeconds(attempt));  // simple backoff, then retry
            }
        }
    }
}

// ── Stack BOTH decorators — order matters! ──
INotificationSender sender =
    new RetryingNotificationSender(               // outermost: retries the WHOLE inner pipeline
        new LoggingNotificationSender(             // middle: logs each attempt, including retries
            new EmailNotificationSender()));        // innermost: the real work

await sender.SendAsync("bob@example.com", "Payment received");
// A failed send now gets logged AND retried — neither EmailNotificationSender
// nor LoggingNotificationSender was ever modified to add retry behavior.

// ── Registering this composition in DI ──
services.AddSingleton(sp =>
    new RetryingNotificationSender(
        new LoggingNotificationSender(
            new EmailNotificationSender())));

Notice the order is deliberate: wrapping Retry around Logging means each retry attempt gets its own log entries — swap the order and you'd log only the first attempt, then silently retry inside the logger's delegation. Decorator composition order is a real design decision, not an arbitrary choice.

Analogy — Gift Wrapping

Under the Hood — The Composition Mechanics

Common Confusion

Decorator vs. inheritance — why not just subclass?

A subclass like LoggingEmailNotificationSender : EmailNotificationSender locks the combination in at compile time — you get exactly that one fixed pairing, and if you also want retry, you're either writing a third subclass for every combination (a combinatorial explosion: logging, retry, logging+retry, ...) or tangling multiple concerns into one override. Decorator composes the same behaviors at runtime, in any combination, without a new class per combination.

Decorator vs. Adapter — both "wrap" something, but for different reasons

Both patterns hold a reference to another object and delegate to it — but Decorator wraps an object in the same interface to add behavior, while Adapter (lesson 243) wraps an object to convert its interface into a different, incompatible one the caller expects. If the wrapper's interface matches the wrapped thing's interface, it's Decorator; if the interfaces are different shapes, it's Adapter.

Common Mistakes

Mistake 1 — Forgetting to delegate, and accidentally reimplementing the wrapped behavior

A decorator that logs, but then does its own SMTP call instead of calling inner.SendAsync(...) — this isn't decorating anymore, it's a second, divergent implementation that happens to also log. The delegated call to the wrapped instance must always happen; the decorator's entire value is adding behavior around that call, not replacing it.

Mistake 2 — Not noticing that decorator order changes behavior

Assuming new Retrying(new Logging(x)) and new Logging(new Retrying(x)) behave identically — they don't, as this lesson's real-world example showed. Reason explicitly about which layer should be "outermost" (runs first, sees the whole inner pipeline) versus "innermost" (closest to the real work).

Mistake 3 — Decorating when the behavior isn't actually optional or combinable

Building a decorator for something that should always happen for every single call, with no scenario where it's skipped — that's just... part of the class's normal behavior, not something worth externalizing. Decorator earns its cost when the behavior is genuinely optional, needs to be combined in different ways for different callers, or needs to be reused across multiple unrelated implementations of the same interface.

When Should I Use It?

• Cross-cutting behaviors — logging, caching, retry, rate-limiting, metrics — that apply to more than one implementation of the same interface, and that some callers need while others don't.
• When you'd otherwise face a combinatorial explosion of subclasses to cover every combination of "with logging," "with retry," "with both."
• When the original class genuinely shouldn't be modified — it's stable, well-tested, owned by another team, or reused elsewhere without the extra behavior.

And when it's overkill: for a behavior that's always required, for every caller, with no variation — just put it directly in the class. Wrapping a single always-on behavior in a decorator adds an object, a constructor parameter, and a mental indirection for zero actual flexibility gained.

Mental Model

Key Takeaway

Check Your Understanding

You've built a stacked logging-and-retry decorator pipeline. Let's check you understand the mechanics.

You now know how to add behavior to any object from the outside — without touching its source, and without a subclass explosion — and can spot the exact same shape in .NET's own HTTP pipeline.

dotnetmadeeasy.com — Learn C# and .NET, the right way.