PicoAop 2026.10.0

PicoAop

Compile-time AOP decorator generation for PicoDI. Zero runtime proxy, zero reflection.

Quick Start

dotnet add package PicoAop

using PicoDI;
using PicoAop.Abs;
using PicoAop.DI;

var container = new SvcContainer();

// Register interceptors
container.RegisterSingleton<LoggingInterceptor>();

// Mark services for interception — source generator emits decorator classes
container.Register<IGreeter, Greeter>(SvcLifetime.Scoped)
    .InterceptBy<LoggingInterceptor>();

container.Build();
await using var scope = container.CreateScope();

var greeter = scope.GetService<IGreeter>();
var log = scope.GetService<LoggingInterceptor>();

// Generated: IGreeter_LoggingInterceptorDecorator
var decorated = new IGreeter_LoggingInterceptorDecorator(greeter, log);
Console.WriteLine(decorated.Greet("World"));

Core Concepts

IInterceptor

The interceptor contract — 4 methods for the cross-product of {sync, async} × {has result, void}:

public interface IInterceptor
{
    TResult Invoke<TResult>(IInvocation<TResult> invocation,
        Func<IInvocation<TResult>, TResult> next);

    void InvokeVoid(IInvocation<VoidResult> invocation,
        Action<IInvocation<VoidResult>> next);

    ValueTask<TResult> InvokeAsync<TResult>(IInvocation<TResult> invocation,
        Func<IInvocation<TResult>, ValueTask<TResult>> next);

    ValueTask InvokeAsyncVoid(IInvocation<VoidResult> invocation,
        Func<IInvocation<VoidResult>, ValueTask> next);
}

The 4-method split is necessary to avoid allocations: ValueTask<VoidResult> cannot be returned where ValueTask is expected (no inheritance relationship). Collapsing to 2 methods would require async state machines for pass-through void calls.

IInvocation<TResult>

Call context exposed to interceptors:

public interface IInvocation<TResult>
{
    string MethodName { get; }    // Which method was called
    Type ServiceType { get; }     // Which service type
    TResult Result { get; set; }  // Modify return value
}

InterceptorBase

Abstract base with virtual pass-through defaults. Override only the methods you need:

public sealed class LoggingInterceptor : InterceptorBase
{
    public override TResult Invoke<TResult>(
        IInvocation<TResult> inv, Func<IInvocation<TResult>, TResult> next)
    {
        Console.WriteLine($"[LOG] {inv.ServiceType.Name}.{inv.MethodName}()");
        var result = next(inv);
        Console.WriteLine($"[LOG] → {result}");
        return result;
    }
}

How It Works

PicoAop.Gen detects .InterceptBy<T>() at compile time and emits:

1. Invocation structs — per-method value types that capture parameters and delegate to the target
2. Decorator classes — sealed classes implementing the service interface, wrapping _inner + _i0
3. DI registrations — ModuleInitializer that auto-registers decorator chains

All wiring is resolved at build time. No DispatchProxy, no Castle.Core, no IL emit.

Decoration chain (onion model):

Interceptor B (outermost)
  └→ Interceptor A
       └→ Real implementation (innermost)

container.Register<IGreeter, Greeter>()
    .InterceptBy<LoggingInterceptor>()    // outer
    .InterceptBy<TimingInterceptor>();    // inner

// Generated: TimingDecorator(LoggingDecorator(Greeter))
// Call: Timing.Invoke → next → Logging.Invoke → next → Greeter.Greet()

Per-Service Interception

container.Register<IGreeter, Greeter>(SvcLifetime.Scoped)
    .InterceptBy<LoggingInterceptor>()
    .InterceptBy<TimingInterceptor>();

Global Interception

Apply an interceptor to all matching services:

container.AddInterceptor<MetricsInterceptor>();

Filter chain (compile-time markers, detected by source generator):

container.AddInterceptor<LoggingInterceptor>()
    .WhereNamespace("MyApp.Services")
    .WhereImplements<IValidator>()
    .Except<HealthCheck>();

Excluding Interceptors

// Exclude specific interceptors from a service
container.Register<IGreeter, Greeter>()
    .WithoutInterceptor<MetricsInterceptor>()
    .InterceptBy<LoggingInterceptor>();

// Remove all interceptors (both per-service and global)
container.Register<IHealthCheck, HealthCheck>()
    .WithoutInterceptors();

Limitations

• ref / out / in parameters — delegated directly without interception (C# structs cannot store ref fields)
• Generic methods — type parameter substitution not implemented
• Properties — delegated transparently, not intercepted

Diagnostics

Packages

Thread Safety

All wiring is resolved at compile time. At runtime:

• Interceptors must be thread-safe if registered as Singleton (shared across concurrent requests)
• Decorators are stateless wrappers — thread safety depends on the inner service
• Invocation structs are stack-allocated value types — never shared across threads

Comparison

← Back to PicoInfra