Decorator ​

Namespace: DesignPatterns.Structural

Overview ​

Stack cross-cutting behaviors around a core service without subclass explosion.

Runtime ​

• IDecorator<T> — decorator contract
• IAsyncDecorator<T> — async decorator contract (DecorateAsync with CancellationToken)
• DecoratorStackBuilder<T> — ordered composition; optional Add(..., Func<bool>) skips a decorator when the predicate is false at build time

Conditional registration ​

var enableMetrics = configuration.GetValue<bool>("Metrics:Enabled");

var service = new DecoratorStackBuilder<IPaymentService>()
    .Add<LoggingPaymentDecorator>()
    .Add<MetricsPaymentDecorator>(() => enableMetrics)
    .Build(new PaymentService());

Generated {Contract}DecoratorStack.Build(core) always includes every [Decorator] type; use the manual builder for runtime switches.

Source generator ​

Mark each decorator with [Decorator<TContract>(order)] (or non-generic on netstandard2.0). The generator emits:

• {Contract}DecoratorStack.Build(core) — ordered stack
• {Contract}DecoratorOrder — public const int fields named after each decorator type

[Decorator<IPaymentService>(10)]
public sealed class LoggingPaymentDecorator : IPaymentService, IDecorator<IPaymentService> { ... }

// Elsewhere (after generation):
Console.WriteLine(PaymentServiceDecoratorOrder.LoggingPaymentDecorator);

Lower order wraps closer to the core; outer decorators run first on the way in. Duplicate orders are reported as DP016.

Diagnostics ​

DP016–DP019. DP042 for async signature validation. DP043 for DI resolvability.

DI integration ​

When the DesignPatterns.Extensions.DependencyInjection package is referenced, the source generator emits a RegisterDi(IServiceCollection, ServiceLifetime) method for each service contract. This registers all decorators with the DI container and enables Build(IServiceProvider, core) to resolve decorators from the container.

PaymentServiceDecoratorStack.RegisterDi(services);

var provider = services.BuildServiceProvider();
var core = new PaymentService();
var service = PaymentServiceDecoratorStack.Build(provider, core);

Decorators must be registered in the container before calling Build(IServiceProvider, core). The core service itself is not registered automatically — you provide it explicitly to Build.

Async variant ​

For asynchronous decoration scenarios, implement IAsyncDecorator<T> instead of IDecorator<T>. The async decorator uses DecorateAsync instead of Decorate:

public interface IAsyncDecorator<TService>
{
    ValueTask<TService> DecorateAsync(TService inner, CancellationToken cancellationToken = default);
}

[Decorator<IPaymentService>(10)]
public sealed class AsyncCachingPaymentDecorator : IPaymentService, IAsyncDecorator<IPaymentService>
{
    public async ValueTask<IPaymentService> DecorateAsync(IPaymentService inner, CancellationToken ct = default)
    {
        await InitializeCacheAsync(ct);
        return this;
    }
}

The source generator validates async decorator signatures (DP042–DP043). Use IAsyncDecorator<T> when decorator initialization requires async work (loading configuration, warming caches, establishing connections). For simple synchronous wrapping, IDecorator<T> is sufficient.

Sample ​

DesignPatterns.Samples.Decorator — generated stack + order constants, conditional Add, and core comparison.

Maintainer doc: docs/Decorator.md (中文).