Decorator Pattern

Decorator solves the "feature combination explosion" problem. Here's the scenario: you have a service that sends notifications, and you want to optionally add logging, caching, retry, and metrics to it. With inheritance, you'd need a separate subclass for every possible combination — LoggingService, CachingService, LoggingCachingService, LoggingRetryService, LoggingCachingRetryMetricsService... that's 2⁴ = 16 classes for just 4 features. Add a 5th feature? Now it's 32 classes.

Decorator avoids this entirely. You write 4 small wrapper classes — one per feature. Each one implements the same interface as the thing it wraps, adds one behavior, and delegates everything else to the inner object. At runtime, you stack whichever ones you need: new Logging(new Retry(new RealService())). Want caching too? Just wrap another layer. Don't need retry? Leave it out. The client code doesn't know (or care) how many layers are around the real service — it just sees the interface.

Think of it this way: inheritance is like baking a cake with the ingredients already mixed in. Once it's baked, you can't remove the chocolate. Decorator is like adding toppings — you can add frosting, sprinkles, and a cherry, and you can always scrape off a topping you don't want.

Technically, inheritance fixes behavior at compile time. You pick a subclass (LoggingOrderService) and that's what you get forever. If you want logging + caching, you need a new subclass LoggingCachingOrderService. Decorator adds behavior at runtime by wrapping objects. You stack wrappers dynamically: new Logging(new Caching(new RealService())). Tomorrow you can swap out Caching for Redis without rewriting anything.

Three practical differences that matter in interviews:

1. Combinability: Inheritance needs a new class for every combination (2^N explosion). Decorator needs N classes total — compose any subset.
2. Runtime flexibility: With Decorator, you can add/remove behavior based on configuration, feature flags, or tenant settings. Inheritance is static.
3. C# limitation: C# doesn't support multiple inheritance. You literally can't create LoggingAndCachingService by inheriting from both LoggingService and CachingService. Decorator sidesteps this entirely through composition.

// INHERITANCE: behavior locked at compile time
var service = new LoggingCachingOrderService(db); // can't change at runtime
// Want logging without caching? Need ANOTHER class

// DECORATOR: behavior composed at runtime
IOrderService service = new OrderService(db);
service = new CachingDecorator(service);  // add caching
service = new LoggingDecorator(service);  // add logging
// Want logging without caching? Just remove one line

A coffee shop is the classic analogy. Start with a plain espresso (the base component). Add milk → that's a latte (first decorator). Add whipped cream → another decorator. Add caramel drizzle → another decorator. Each addition wraps the previous drink, adds its own cost and flavor, but the espresso at the core is unchanged. You can combine any toppings you want, skip any you don't, and the barista doesn't need a separate recipe for every possible combination.

Four roles:

1. Component (interface) — the contract both the real object and decorators implement. Example: IOrderService
2. Concrete Component — the real object with actual business logic. Example: OrderService
3. Base Decorator (abstract) — implements the interface and forwards all calls to the inner component. Optional but highly recommended to avoid forwarding boilerplate
4. Concrete Decorators — extend the base decorator, override specific methods to add behavior. Example: LoggingOrderDecorator, CachingOrderDecorator

The key difference is that a Decorator implements the same interface as the object it wraps. This means decorators are transparent to the client — the client code works with IOrderService and doesn't know whether it's talking to the real service or 5 decorators deep. A plain wrapper typically has its own distinct interface, breaking this transparency. Because decorators share the interface, they can stack: Decorator A wraps Decorator B wraps Decorator C wraps the real object.

Stream is the abstract base (the Component). FileStream, MemoryStream, NetworkStream are concrete components — they read/write actual data. BufferedStream, GZipStream, CryptoStream, BrotliStream are decorators — they take a Stream in their constructor and add a feature (buffering, compression, encryption) while still being a Stream themselves. You can stack any combination: compress then encrypt, buffer then compress, etc.

Two approaches:

1. Manual factory (built-in DI): Register a factory lambda that resolves the inner service and wraps it.
2. Scrutor (recommended): Clean, readable, automatically handles all dependencies.

// Option 1: Manual factory (messy with multiple layers)
services.AddScoped<IOrderService>(sp =>
    new LoggingDecorator(
        new CachingDecorator(
            new OrderService(sp.GetRequiredService<IRepository>()),
            sp.GetRequiredService<IMemoryCache>()),
        sp.GetRequiredService<ILogger<LoggingDecorator>>()));

// Option 2: Scrutor (clean and composable)
services.AddScoped<IOrderService, OrderService>();
services.Decorate<IOrderService, CachingDecorator>();  // inner
services.Decorate<IOrderService, LoggingDecorator>();  // outer (last = outermost)

Decorator is great for adding optional, combinable behaviors — but it's not always the right tool. Think of it like gift wrapping: wrapping a present in nice paper makes sense. But wrapping a single sticky note in three layers of paper, tape, and ribbon? Overkill. Here are the situations where Decorator causes more pain than it solves:

Avoid Decorator when:

• There's only one behavior that's always applied — if logging is always on and never optional, just put it in the class. Decorator adds indirection for zero benefit when there's no "mix and match" happening.
• You need access to private members — decorators only see the public interface. If the behavior you're adding needs to read internal state, Decorator can't help. Use inheritance or modify the class directly.
• The interface is huge (20+ methods) — even with a base decorator, forwarding 20 methods is noisy. If your interface is that big, it probably violates Interface Segregation Principle (ISP). Split it first, then consider Decorator.
• Performance-critical hot paths — each layer adds a virtual method dispatch (~2-5ns). For a database call, that's irrelevant. For a math function called 100 million times per second in a game engine, those nanoseconds add up.
• Decoration order is fragile — if swapping two decorators causes bugs and the "correct" order isn't obvious, consider a Pipeline pattern (like MediatR behaviors) where order is explicit and documented.

The smell test: if you always apply the same decorators in the same order to every implementation, you probably don't need Decorator. Its power is in optional, combinable behaviors — if nothing is optional, you're adding complexity for no reason.

ASP.NET Core middleware is essentially Decorator applied to HTTP request processing. Each middleware wraps the next one via the RequestDelegate next parameter. It can run code before calling next(context) (decorating the request) and after (decorating the response). The "base component" is the endpoint handler at the center. Just like Decorator, middleware is composable, order matters, and each layer does one thing (auth, logging, compression, CORS).

// MIDDLEWARE: wraps HTTP pipeline via RequestDelegate
public class LoggingMiddleware
{
    private readonly RequestDelegate _next; // "inner" component
    public async Task Invoke(HttpContext ctx)
    {
        Log("Before");
        await _next(ctx);  // forward to next layer
        Log("After");
    }
}

// DECORATOR: wraps specific interface via constructor injection
public class LoggingDecorator : IOrderService
{
    private readonly IOrderService _inner; // "inner" component
    public async Task<Order> CreateAsync(CreateOrderRequest req)
    {
        Log("Before");
        var result = await _inner.CreateAsync(req); // forward to inner
        Log("After");
        return result;
    }
}
// Same concept. Different abstraction level.

This is one of the most common interview questions because the two patterns look almost identical in code. Both implement the same interface. Both hold a reference to the wrapped object. Both delegate calls to it. If you showed someone the code without class names, they might not be able to tell them apart.

The difference is intent — what you're trying to achieve:

• Decorator: "I want to add behavior." Logging, caching, retry, metrics — the real service still runs, but extra behavior is layered around it. Decorators are designed to stack (multiple layers).
• Proxy: "I want to control access." Lazy loading (create the object only when needed), security checks (verify permissions before calling), remote proxy (the object lives on another server). Proxies typically stand alone (one proxy, not stacked).

In practice, some wrappers blur the line. A caching wrapper could be called either — it "adds" caching behavior (Decorator) but also "controls access" by deciding whether to call the real service (Proxy). The naming you choose tells other developers your intent.

The answer depends on whether your decorator has state (data it remembers between calls) or is stateless (just passes things through with some logic).

Stateless decorators (like a pure logging decorator) are automatically thread-safe — they don't store anything, so there's nothing for threads to fight over. Multiple threads can call them simultaneously with zero risk.

Stateful decorators (like a caching decorator that remembers previous results) need protection. If two threads try to update the same cache simultaneously, you get race conditions — corrupted data, duplicate computations, or crashes.

// ❌ NOT thread-safe — Dictionary is not designed for concurrent access
public class CachingDecorator : IOrderService
{
    private readonly Dictionary<int, Order> _cache = new();  // 💥 race condition
    private readonly IOrderService _inner;

    public Order GetOrder(int id)
    {
        if (!_cache.ContainsKey(id))          // Thread A checks: not cached
            _cache[id] = _inner.GetOrder(id); // Thread B also checks: not cached → duplicate call!
        return _cache[id];
    }
}

// ✅ Thread-safe — ConcurrentDictionary handles locking internally
public class CachingDecorator : IOrderService
{
    private readonly ConcurrentDictionary<int, Order> _cache = new();
    private readonly IOrderService _inner;

    public Order GetOrder(int id) =>
        _cache.GetOrAdd(id, key => _inner.GetOrder(key));  // atomic check-and-add
}

The golden rule: match your decorator's DI lifetime to its thread-safety guarantees. A Singleton decorator must be thread-safe (multiple threads share it). A Scoped decorator gets one instance per HTTP request — usually safe because web requests are single-threaded within a scope.

Imagine you have 6 decorators (logging, caching, retry, metrics, auth, validation), and your IOrderService interface has 5 methods. Without a base decorator, each of those 6 decorators must manually forward all 5 methods — that's 30 forwarding methods to write and maintain. Now add a new method to the interface? You need to update all 6 decorators. Miss one? The compiler catches it (it won't compile), but now you're doing the same copy-paste forwarding in 6 files.

A base decorator class solves this by forwarding everything by default. Your concrete decorators inherit from it and override only the methods they care about:

// Base decorator — forwards everything to inner by default
public abstract class OrderServiceDecorator : IOrderService
{
    protected readonly IOrderService _inner;
    protected OrderServiceDecorator(IOrderService inner) => _inner = inner;

    public virtual Order GetOrder(int id)         => _inner.GetOrder(id);
    public virtual IList<Order> GetAll()          => _inner.GetAll();
    public virtual void PlaceOrder(Order order)    => _inner.PlaceOrder(order);
    public virtual void CancelOrder(int id)        => _inner.CancelOrder(id);
    public virtual OrderStats GetStats()           => _inner.GetStats();
}

// Concrete decorator — only overrides what it enhances (2 methods, not 5!)
public class LoggingOrderDecorator : OrderServiceDecorator
{
    private readonly ILogger _log;
    public LoggingOrderDecorator(IOrderService inner, ILogger log)
        : base(inner) => _log = log;

    public override Order GetOrder(int id)
    {
        _log.LogInformation("Getting order {Id}", id);
        return base.GetOrder(id);  // forwards to inner automatically
    }
    // GetAll, PlaceOrder, CancelOrder, GetStats — auto-forwarded by base!
}

When a new method is added to IOrderService, you add it once in the base decorator — all 6 concrete decorators inherit the forwarding automatically. Zero maintenance overhead.

A retry decorator re-attempts a failed operation a configurable number of times before giving up. It's one of the most useful decorators in production, especially for services that call external APIs (payment gateways, email providers, third-party integrations) where transient failures are common.

Key requirements for a production-grade retry decorator:

• Async all the way — use await for inner calls and await Task.Delay() for backoff. Never .Result or Thread.Sleep() (see Bug Study #5)
• Configurable retry count and delay strategy — fixed delay, exponential backoff, or jittered backoff to avoid thundering herd
• Only retry specific exceptions — retry on HttpRequestException (network failure), not on ValidationException (bad input won't fix itself)
• Log each attempt — so you can see "attempt 1 failed, retrying... attempt 2 failed, retrying... attempt 3 succeeded"
• Re-throw the last exception — if all retries fail, don't swallow the error. The caller needs to know something went wrong.

public class RetryPaymentDecorator : IPaymentGateway
{
    private readonly IPaymentGateway _inner;
    private readonly ILogger _logger;
    private readonly int _maxRetries;

    public RetryPaymentDecorator(IPaymentGateway inner, ILogger logger,
        int maxRetries = 3)
    {
        _inner = inner;
        _logger = logger;
        _maxRetries = maxRetries;
    }

    public async Task<PaymentResult> ChargeAsync(PaymentRequest request)
    {
        Exception? lastException = null;

        for (int attempt = 1; attempt <= _maxRetries; attempt++)
        {
            try
            {
                return await _inner.ChargeAsync(request); // ✅ await, not .Result
            }
            catch (HttpRequestException ex) // ✅ only retry network errors
            {
                lastException = ex;
                _logger.LogWarning("Attempt {Attempt}/{Max} failed: {Error}",
                    attempt, _maxRetries, ex.Message);

                if (attempt < _maxRetries)
                {
                    // ✅ Exponential backoff with jitter
                    var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt))
                        + TimeSpan.FromMilliseconds(Random.Shared.Next(0, 1000));
                    await Task.Delay(delay); // ✅ non-blocking wait
                }
            }
            // ❌ Don't catch ValidationException, ArgumentException, etc.
            // Those won't fix themselves on retry
        }

        throw lastException!; // ✅ re-throw — caller needs to know we failed
    }
}

Walking through the code: The decorator wraps the inner payment gateway and tries calling it up to _maxRetries times. If the call succeeds, it returns immediately. If it throws an HttpRequestException (network/server error), it logs the failure, waits using exponential backoff (2s, 4s, 8s) with random jitter (to prevent all retries hitting the server at the same instant), and tries again. If all retries fail, it throws the last exception so the caller can handle it. Notice: it only catches network errors — a ValidationException means the input is wrong, and retrying won't fix bad data.

When you call services.Decorate<IOrderService, LoggingDecorator>(), Scrutor does something clever behind the scenes. It doesn't just "add" your decorator — it performs a registration replacement:

1. Find the existing ServiceDescriptor for IOrderService in the service collection
2. Remove that registration
3. Create a new registration — a factory lambda that first resolves the original implementation (captured in a closure), then passes it as the inner constructor parameter to your decorator
4. Preserve the lifetime — if OrderService was registered as Scoped, the decorator is also Scoped

When you chain multiple Decorate calls, each one wraps around the previous result. So Decorate<A>() then Decorate<B>() means the factory creates: B(A(RealService)). The last one registered is outermost.

With Scrutor, the last registered decorator is outermost. If you do Decorate<A>() then Decorate<B>() then Decorate<C>(), the chain is C → B → A → RealService. C runs first, then delegates to B, and so on. The recommended order: outermost = observability (logging, metrics), middle = resilience (retry, circuit breaker), innermost = data (caching, validation). Document the order with comments in your DI setup.

Let's put real numbers on this. Each decorator layer adds one virtual method call — approximately 2-5 nanoseconds on modern hardware. To put that in perspective:

• A database query takes ~1-10 milliseconds (1,000,000+ nanoseconds)
• An HTTP call takes ~50-500 milliseconds
• Even 10 decorator layers add only ~50 nanoseconds total

So for any method that does I/O (which is almost every real service method), decorator overhead is less than 0.001% of the total time — completely invisible.

The real performance concern isn't the virtual dispatch — it's object allocation. If decorators are registered as Transient (new instance per request), a 5-layer chain creates 5 objects per request. At 10,000 requests/second, that's 50,000 small objects entering Gen 0 garbage collection every second. The fix is simple: register decorators as Singleton or Scoped. Singletons are allocated once and shared. Scoped decorators are allocated once per request scope and reused within it.

The only scenario where decorator overhead truly matters is in tight computational loops — math functions called 100 million times per second with zero I/O. In those cases, every nanosecond counts and you should inline the logic. But if your method touches a database, file system, or network? Add as many decorators as you need. The maintainability benefit dwarfs the nanosecond cost.

Both achieve the same goal — adding behavior around method calls — but they work completely differently under the hood.

Decorators are compile-time, explicit. You write a real class that implements the interface. You can see the code, step through it in the debugger, and test it like any other class. The downside: you must write a decorator class for each interface you want to wrap, and forward all methods you don't override.

Interceptors are runtime, implicit. A framework (Castle DynamicProxy, DispatchProxy) generates a proxy class at runtime using reflection or IL generation. You write one interceptor method that handles all method calls on any interface. No forwarding boilerplate, no interface-specific code. The downside: harder to debug (you're stepping through framework-generated code), higher runtime overhead, and the "magic" is invisible in your codebase.

When to use which: If the concern applies to 3-5 specific services and you want full control, use explicit Decorators. If the same concern applies uniformly to 50+ services (like adding trace logging to everything), Interceptors save massive boilerplate.

Yes — and this is one of Decorator's most powerful features. Instead of writing a separate logging decorator for IOrderRepository, ICustomerRepository, IProductRepository, you write one generic decorator that works for all of them. Think of it like a universal gift wrapper that fits any box size — you write the wrapping logic once, and it adapts to whatever's inside.

// The generic interface
public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync(int id);
    Task<IList<T>> GetAllAsync();
    Task SaveAsync(T entity);
}

// ONE decorator that works for ALL entity types
public class LoggingRepository<T> : IRepository<T> where T : class
{
    private readonly IRepository<T> _inner;
    private readonly ILogger<LoggingRepository<T>> _log;

    public LoggingRepository(IRepository<T> inner, ILogger<LoggingRepository<T>> log)
        => (_inner, _log) = (inner, log);

    public async Task<T?> GetByIdAsync(int id)
    {
        _log.LogInformation("Getting {Type} with ID {Id}", typeof(T).Name, id);
        return await _inner.GetByIdAsync(id);
    }
    // ... same pattern for GetAllAsync and SaveAsync
}

// Register with Scrutor — open generic means it applies to ALL repositories
services.Decorate(typeof(IRepository<>), typeof(LoggingRepository<>));
// Now IRepository<Order>, IRepository<Customer>, IRepository<Product>
// ALL get automatic logging — zero extra code per entity!

This is exactly how MediatR's pipeline behaviors work. IPipelineBehavior<TRequest, TResponse> is a generic decorator around IRequestHandler<TRequest, TResponse>. You write one validation behavior and it applies to every handler in your app.

Cross-cutting concerns are behaviors that apply to many services but aren't part of the core business logic — things like logging, caching, authorization, retry. The question is: how do you apply them without copy-pasting the same code into 50 services?

Decorator approach: You manually write a wrapper class for each concern. LoggingDecorator wraps IOrderService and adds logging. It's explicit — you can see exactly what happens, set breakpoints, and debug normally. The trade-off: you write more code, and each service that needs decoration must be explicitly wrapped.

AOP approach (PostSharp, Fody, Castle DynamicProxy): You add an attribute like [Log] to a method, and the framework automatically injects logging behavior — either at compile time (PostSharp weaves IL into your assembly) or at runtime (DynamicProxy creates a subclass on-the-fly). Less code to write, but the behavior is "magic" — harder to debug because the injected code isn't visible in your source.

// Decorator approach — explicit, debuggable
services.AddScoped<IOrderService, OrderService>();
services.Decorate<IOrderService, LoggingDecorator>();    // visible in code
services.Decorate<IOrderService, CachingDecorator>();    // you control the order

// AOP approach — attribute-based, less code
[Log]        // ← PostSharp weaves logging at compile time
[Cache(60)]  // ← you don't see HOW it's implemented
public Order GetOrder(int id) => _db.Orders.Find(id);

In modern .NET, the trend has strongly moved toward explicit Decorator + DI over magic AOP. MediatR pipeline behaviors, HttpClient DelegatingHandlers, and ASP.NET middleware are all Decorator-style patterns. The community consensus: if the concern applies to 3-5 services, use explicit decorators. If it applies to 50+ services identically, consider source generators to reduce boilerplate.

Decorators are one of the easiest patterns to test, because each decorator takes an interface in its constructor — which means you can pass in a mock. No special test infrastructure needed. Just "new up" the decorator with a mock inner, call the method, and assert.

Use a three-layer testing strategy:

1. Unit test each decorator in isolation — mock the inner service, verify the decorator adds its specific behavior. This is the most important layer.
2. Integration test the full chain — stack all decorators on a real (or in-memory) service, verify end-to-end behavior.
3. DI configuration test — resolve the service from the real container, verify the chain is wired correctly.

// Layer 1: Unit test — test the CachingDecorator in isolation
[Fact]
public async Task CachingDecorator_SecondCall_ReturnsCached()
{
    var mockInner = new Mock<IOrderService>();
    mockInner.Setup(s => s.GetOrder(42)).Returns(new Order { Id = 42 });
    var decorator = new CachingDecorator(mockInner.Object);

    var first  = decorator.GetOrder(42);  // calls inner
    var second = decorator.GetOrder(42);  // should return cached

    mockInner.Verify(s => s.GetOrder(42), Times.Once()); // inner called ONCE, not twice
    Assert.Same(first, second);  // same cached object returned
}

// Layer 2: Integration test — verify full chain works together
[Fact]
public async Task FullChain_LogsCachesAndReturnsOrder()
{
    var realService = new InMemoryOrderService();
    var cached  = new CachingDecorator(realService);
    var logged  = new LoggingDecorator(cached, testLogger);
    var result  = logged.GetOrder(1);
    Assert.NotNull(result);
    Assert.Contains("Getting order", testLogger.Messages);
}

// Layer 3: DI test — verify chain is wired correctly
[Fact]
public void DI_ResolvesDecoratorChain()
{
    var provider = CreateServiceProvider(); // your real DI setup
    var service  = provider.GetRequiredService<IOrderService>();
    Assert.IsType<LoggingDecorator>(service);   // outermost = logging
}

Let's break down the actual numbers. In .NET on a 64-bit system, every object has a fixed overhead:

• 8 bytes — object header (used by GC and locking)
• 8 bytes — method table pointer (how .NET knows the object's type)
• 8 bytes — the _inner field (reference to the wrapped service)

That's 24 bytes minimum per decorator. Add fields for injected dependencies (ILogger = 8 bytes, IMemoryCache = 8 bytes), and a typical decorator uses 32-48 bytes. A 5-layer chain? About 200-300 bytes total — less than a single string like "Hello, World!" takes in memory.

For Singleton or Scoped registration, this memory is allocated once and shared across all callers. Memory impact: effectively zero.

The concern arises only with Transient registration at high throughput. If every request creates a fresh 5-layer chain, at 10,000 requests/second that's 50,000 short-lived objects per second entering Gen 0 garbage collection. Gen 0 collections are fast (~1ms), but at extreme scale this adds GC pressure. The fix: register decorators as Scoped (one per request scope, reused within it) or Singleton (one for the entire application lifetime).

In practice, decorator memory has never been a production issue in any real-world project. The internal state of decorators (caches holding thousands of entries, buffers holding MB of data) dwarfs the wrapper objects themselves.

Disposal in a decorator chain is about answering one question: who created it, who cleans it up? This is the "ownership" rule — the object that created a resource is responsible for destroying it.

There are two scenarios:

DI-managed chains (most common): The DI container created each layer, so the container disposes each layer independently when the scope ends. Your decorators do NOT need to dispose the inner service — the container handles it. If you dispose the inner yourself, you might cause a double-dispose crash.

Manually-built chains (like .NET Streams): You created the chain, so you must clean it up. Each decorator should implement IDisposable and propagate Dispose to the inner object:

// For manual chains: propagate Dispose with try/finally
public class EncryptingStream : Stream, IDisposable
{
    private readonly Stream _inner;
    private readonly bool _leaveOpen;  // ← the escape hatch

    public EncryptingStream(Stream inner, bool leaveOpen = false)
        => (_inner, _leaveOpen) = (inner, leaveOpen);

    protected override void Dispose(bool disposing)
    {
        if (disposing && !_leaveOpen)
            _inner.Dispose();  // only dispose inner if we OWN it
        base.Dispose(disposing);
    }
}

// Usage — leaveOpen controls ownership:
using var fileStream = File.OpenRead("data.bin");
using var buffered   = new BufferedStream(fileStream);
using var encrypted  = new EncryptingStream(buffered);
// When 'encrypted' disposes, it disposes 'buffered',
// which disposes 'fileStream'. Clean chain.

// For DI-managed chains — do NOT dispose inner:
public class LoggingDecorator : IOrderService  // no IDisposable needed
{
    private readonly IOrderService _inner;  // DI container owns this
    // ... just delegate calls, don't touch disposal
}

A subtle gotcha: if a CachingDecorator caches results containing IDisposable objects, who disposes the cached items when they're evicted? Use IMemoryCache's PostEvictionCallback to handle this — otherwise you'll leak resources silently.

Decorators wrap the client-side service abstraction. Define IPaymentGateway as an interface. The concrete implementation makes HTTP calls to the payment service. Wrap it with decorators: RetryDecorator (handles transient failures), CircuitBreakerDecorator (stops calling when service is down), CachingDecorator (caches idempotent responses), MetricsDecorator (records latency and error rates). In .NET, HttpClient's DelegatingHandler chain is Decorator at the HTTP level — Polly integrates here via AddPolicyHandler().

The biggest pain point with Decorator is the forwarding boilerplate — if your interface has 10 methods, your base decorator must forward all 10, even though most concrete decorators only override 1-2 of them. Source generatorsSource generators are a C# compiler feature that generates additional source code at compile time based on your existing code. They analyze your types via Roslyn and emit new .cs files that become part of your compilation. No runtime reflection, no IL weaving — just generated code that's visible and debuggable. eliminate this entirely.

A source generator reads your interface at compile time, generates the forwarding base class automatically, and you just write the override for the methods you want to enhance:

// Step 1: Mark your interface for generation
[GenerateDecorator]  // ← source generator attribute
public interface IOrderService
{
    Task<Order> GetOrderAsync(int id);
    Task<IList<Order>> GetAllAsync();
    Task PlaceOrderAsync(Order order);
    Task CancelOrderAsync(int id);
    Task<OrderStats> GetStatsAsync();
}

// Step 2: The source generator auto-creates this at compile time:
// (you never write this — it's generated into obj/Generated/)
public abstract partial class OrderServiceDecoratorBase : IOrderService
{
    protected readonly IOrderService _inner;
    protected OrderServiceDecoratorBase(IOrderService inner) => _inner = inner;
    public virtual Task<Order> GetOrderAsync(int id) => _inner.GetOrderAsync(id);
    public virtual Task<IList<Order>> GetAllAsync() => _inner.GetAllAsync();
    // ... all 5 methods auto-forwarded
}

// Step 3: You write only the override you care about
public class LoggingDecorator : OrderServiceDecoratorBase
{
    public LoggingDecorator(IOrderService inner, ILogger log) : base(inner) { }

    public override async Task<Order> GetOrderAsync(int id)
    {
        _log.LogInformation("Getting order {Id}", id);
        return await base.GetOrderAsync(id);
    }
    // Other 4 methods: auto-forwarded by the generated base class!
}

The generated code has zero runtime overhead — no reflection, no proxies, no IL weaving. It's just plain C# that the compiler produces. You can inspect it in the obj/Generated/ folder, set breakpoints in it, and debug it normally. If the interface changes (method added/removed), the generator updates the base class automatically at compile time.

OpenTelemetry gives you distributed tracing — the ability to follow a single request across services and see exactly where time is spent. A TracingDecorator wraps your service and creates a "span" (a timed block) around each method call, recording what happened, how long it took, and whether it succeeded.

In .NET, spans are represented by the Activity class (from System.Diagnostics). Your TracingDecorator creates an Activity before calling the inner service, adds tags with useful context, and marks success or failure when the call completes:

public class TracingOrderDecorator : IOrderService
{
    private static readonly ActivitySource Source = new("MyApp.Orders");
    private readonly IOrderService _inner;

    public TracingOrderDecorator(IOrderService inner) => _inner = inner;

    public async Task<Order> GetOrderAsync(int id)
    {
        using var activity = Source.StartActivity("GetOrder");
        activity?.SetTag("order.id", id);  // searchable in Jaeger/Zipkin

        try
        {
            var result = await _inner.GetOrderAsync(id);
            activity?.SetTag("order.found", result != null);
            activity?.SetStatus(ActivityStatusCode.Ok);
            return result;
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            activity?.RecordException(ex);  // exception details in the trace
            throw;
        }
    }
}

// Register as OUTERMOST decorator — so it traces the full chain
// (including retry attempts, cache hits, etc.)
services.AddScoped<IOrderService, OrderService>();
services.Decorate<IOrderService, CachingDecorator>();
services.Decorate<IOrderService, RetryDecorator>();
services.Decorate<IOrderService, TracingOrderDecorator>(); // outermost = registered last

Pair this with a MetricsDecorator that records histograms (latency percentiles) and counters (success/failure rates), and you get full observability without touching any business logic — pure Decorator benefit.

Here are decorator patterns that I've used (or seen used) in real production .NET systems. The common thread: each concern is optional, independently toggleable, and has nothing to do with core business logic — exactly what Decorator is designed for:

• Retry + exponential backoff with jitter — wraps any service that calls external APIs. Configurable max retries and delay per endpoint. Handles transient HTTP 500s, timeouts, and network blips without the caller knowing.
• Circuit breaker — tracks failure rate. After N consecutive failures, it "opens" and immediately returns an error (or fallback) instead of calling the failing service. After a timeout, it "half-opens" and lets one request through to test if the service recovered. Prevents cascade failures in microservices.
• Distributed cache (Redis-backed) — caches responses with configurable TTL per method. The decorator checks Redis first; if there's a hit, returns cached data without calling the inner service. Cache misses go through to the real service and cache the result.
• Rate limiting — per-tenant throttling for multi-tenant SaaS. If Tenant A exceeds their quota, the decorator returns HTTP 429 without touching the service. Other tenants are unaffected.
• Audit logging — records who called what, when, with before/after snapshots of the data. Critical for compliance (GDPR, SOX). The decorator captures the state before the inner call, then the state after, and writes both to an audit trail.
• Feature flags — decorator that checks a feature flag service. If the feature is disabled, it short-circuits to a fallback behavior instead of calling the new implementation. Enables safe gradual rollouts.

In a typical production service, you might stack 3-4 of these: TracingDecorator → RetryDecorator → CachingDecorator → RealService. Each one is independently testable, independently removable, and none knows about the others.

The distinctions:

• Decorator: wraps a specific interface. Type-safe, compile-time checked, works per-service. Best for: service-level concerns (caching IOrderService, retrying IPaymentGateway)
• Middleware: wraps a generic request/response pipeline. Runs for ALL requests. Best for: infrastructure concerns (auth, CORS, compression, request logging)
• Pipeline (MediatR behaviors): wraps a generic handler with typed request/response. Best for: cross-cutting concerns across all handlers (validation, logging, transaction management)

When a method call goes through 5 decorator layers and the result is wrong, the challenge is figuring out which layer caused the problem. Is the caching decorator returning stale data? Is the retry decorator masking an error? Is the real service returning bad data? Here's a systematic approach:

Four debugging strategies:

1. Structured logging in every decorator — each decorator logs entry/exit with its class name. The log sequence tells you exactly which layers ran and in what order. If the logs show "CachingDecorator: returning cached result" when you expected a fresh DB call, you've found the culprit.
2. Correlation IDs — pass a unique ID through the chain so you can filter logs for one specific call across all layers. Without this, high-traffic logs become impossible to follow.
3. Bypass decorators — in development, resolve the concrete service directly (skip DI decoration) to test if the issue is in a decorator or the real service.
4. Unit tests per decorator — if each decorator passes its isolated tests, the bug is likely in the interaction between layers (ordering, state sharing).

A powerful diagnostic technique: add a startup log that dumps the full chain structure so you never have to guess:

// Log the full decorator chain at startup
public static void LogDecoratorChain<T>(IServiceProvider sp, ILogger log)
{
    var service = sp.GetRequiredService<T>();
    var chain = new List<string>();
    var current = service as object;

    while (current != null)
    {
        chain.Add(current.GetType().Name);
        // Try to read the "_inner" field via reflection (dev only!)
        var innerField = current.GetType()
            .GetField("_inner", BindingFlags.NonPublic | BindingFlags.Instance);
        current = innerField?.GetValue(current);
    }

    log.LogInformation("IOrderService chain: {Chain}", string.Join(" → ", chain));
    // Output: "IOrderService chain: LoggingDecorator → RetryDecorator →
    //          CachingDecorator → OrderService"
}

Decorator chain from outermost to innermost:

1. TracingDecorator (outermost) — creates OpenTelemetry span, captures full call duration including retries
2. MetricsDecorator — records latency histogram, success/failure counters
3. LoggingDecorator — logs entry/exit, method args, correlation ID
4. RateLimitingDecorator — per-tenant rate limiting, throws 429 if exceeded
5. CircuitBreakerDecorator — opens after 5 failures, half-open after 30s
6. RetryDecorator — 3 retries with exponential backoff + jitter
7. PaymentGatewayHttpClient (innermost, concrete) — makes the actual HTTP call

Why this order? Tracing sees everything including retries. Metrics count at the business level (one charge attempt = one metric even if retried). Logging captures the full story. Rate limiting stops excessive calls before they hit retry logic. Circuit breaker prevents calling a dead service. Retry handles transient failures closest to the actual call.