Konduit 0.6.0

Konduit

ASP.NET Core style middleware pipelines for any dependency-injected service.

Register a service the way you already do, and chain WithMiddleware<T>() to wrap every call to it:

services.AddScoped<IOrderService, OrderService>()
        .WithMiddleware<LoggingMiddleware>()
        .WithMiddleware<RetryMiddleware>();

Resolving IOrderService now gives you a proxy. Every call travels Logging → Retry → OrderService, and the "after" half of each middleware unwinds on the way back out — exactly like app.Use(...), but for method calls instead of HTTP requests.

Proxies are source-generated, so there is no reflection on the call path and nothing to configure.

Writing middleware

Middleware takes the next step in the pipeline as a KonduitDelegate constructor parameter, just as ASP.NET Core middleware takes a RequestDelegate. Every other constructor parameter comes from DI.

public sealed class LoggingMiddleware(KonduitDelegate next, ILogger<LoggingMiddleware> logger)
    : IKonduitMiddleware
{
    public async ValueTask InvokeAsync(KonduitContext context)
    {
        logger.LogInformation("→ {Method}", context.Method.Name);

        var started = Stopwatch.GetTimestamp();
        await next(context);

        logger.LogInformation("← {Method} in {Elapsed}",
            context.Method.Name, Stopwatch.GetElapsedTime(started));
    }
}

The pipeline is built per service resolution, from the resolving scope, so middleware can inject scoped dependencies directly:

public sealed class AuditMiddleware(KonduitDelegate next, AppDbContext db) : IKonduitMiddleware

What's on the context

Because Result holds the awaited value, a middleware wrapped around Task<Order> PlaceAsync() sees the finished Order after await next(context) — not a Task that hasn't run yet.

Things middleware can do

// Rewrite an argument on the way in
context.Arguments[0] = Sanitize((string)context.Arguments[0]!);

// Rewrite the result on the way out
await next(context);
context.Result = Redact((Order)context.Result!);

// Short-circuit: skip the target entirely
if (cache.TryGetValue(key, out var hit))
{
    context.Result = hit;
    return;               // never calls next
}

// Handle failures
try { await next(context); }
catch (TimeoutException) { context.Result = Order.Unavailable; }

What gets intercepted

Every method declared on the service interface, including inherited ones.

Opt a single method out with [SkipKonduit] — it is forwarded straight to the implementation, allocating nothing and running no middleware:

public interface IOrderService
{
    Task<Order> PlaceAsync(Cart cart, CancellationToken cancellationToken);

    [SkipKonduit]
    string Describe(int id);      // hot path, no middleware
}

When the interface belongs to a package you can't edit, put the attribute on your implementation instead:

public sealed class OurStorage : IThirdPartyStorage   // interface you cannot annotate
{
    public Task<Stream> ReadAsync(string key) => ...;

    [SkipKonduit]
    public Task<bool> ExistsAsync(string key) => ...;   // no middleware for this one
}

services.AddScoped<IThirdPartyStorage, OurStorage>().WithMiddleware<LoggingMiddleware>();

That applies to OurStorage alone — another implementation behind the same interface keeps every method intercepted.

It works because the registration names the implementation, which is the only thing to check:

services.AddScoped<IFoo, Foo>()                         // ✅ named
services.AddScoped(typeof(IFoo), typeof(Foo))           // ✅ named
services.AddHttpClient<IFoo, Foo>()                     // ✅ named
services.AddScoped<IFoo, Foo>(sp => new Foo(...))       // ✅ named, even with a factory
services.AddScoped<IFoo>(sp => new Foo(...))            // ❌ not named

Only the last form hides it. If you build the instance yourself and want the attribute honoured, use the two-type-parameter factory overload — same lambda, one more type argument.

Properties, indexers and events are forwarded without interception. So are methods Konduit cannot proxy — each one produces a build warning naming the method and the reason, so nothing is silently uninstrumented.

Interception happens through the interface. A call from inside OrderService to its own method does not pass through the pipeline, and neither does a call through a concrete OrderService reference. The implementation stays resolvable unwrapped if you want it:

provider.GetRequiredService<IOrderService>();   // the proxy
provider.GetRequiredService<OrderService>();    // the real thing, no pipeline

Registration

WithMiddleware<T>() decorates the service registered immediately before it, so chain it directly onto the registration:

// Good
services.AddScoped<IOrderService, OrderService>().WithMiddleware<LoggingMiddleware>();

// Build error KDT001 — Konduit can't tell which service this belongs to
services.AddScoped<IOrderService, OrderService>();
services.WithMiddleware<LoggingMiddleware>();

AddScoped, AddSingleton and AddTransient all work, in their generic, factory, instance and typeof(...) forms. The registration keeps its original lifetime.

Konduit does not replace the built-in registration methods. An AddScoped<TService, TImpl>() of its own would have the same signature as the BCL's and make every registration in your project ambiguous, so WithMiddleware<T>() is the only extension added.

Not supported

Keyed services and open generics both throw at registration time with a message naming the type. Register each closed generic separately if you need middleware on it:

services.AddScoped<IRepository<Order>, OrderRepository>().WithMiddleware<LoggingMiddleware>();

Build diagnostics

Caveats

Synchronous methods and async middleware. Sync methods are supported: the proxy runs the same pipeline and, when every middleware completed synchronously — the usual case for logging, validation or metrics — takes the result with no blocking at all. It blocks only if a middleware genuinely went async inside a synchronous call, which carries the usual sync-over-async deadlock risk. If your middleware does real I/O, prefer async methods on the interface.

IAsyncEnumerable<T> is not streamed. A method returning IAsyncEnumerable<T> is treated as an ordinary value-returning method: middleware sees the enumerable object as Result, and the "after" half runs when the method returns, before anything is enumerated. Timing or logging middleware on such a method measures the call, not the iteration.

Init-only interface properties cannot be forwarded. No proxy can assign another object's init-only member. The generated accessor throws NotSupportedException and KDT006 warns at build time.

Default interface members are not intercepted directly. They still dispatch correctly, and calls they make back onto the interface do go through the pipeline.

Performance

Proxies are generated at compile time, so an intercepted call costs a direct virtual call plus the context and argument-array allocations — no reflection, no IL emit, no dynamic dispatch. Method descriptors and the terminal delegates are static and shared across calls. [SkipKonduit] methods compile down to a direct forward.

The library is trim- and AOT-compatible.

MediatR

MediatR discovers handlers by scanning assemblies, so there is no registration call to chain WithMiddleware<T>() onto. The companion package Konduit.MediatR adds one call that wraps everything MediatR found:

services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

services.AddKonduitToMediatRHandlers()
        .WithMiddleware<LoggingMiddleware>()
        .WithMiddleware<RetryMiddleware>();

Commands, queries, notifications and streams all run through the same middleware you write for ordinary services, with [SkipKonduit] opting a handler out.

Typed HttpClient services

AddHttpClient<TClient, TImplementation>() returns an IHttpClientBuilder, with no registration call to chain WithMiddleware<T>() onto. The companion package Konduit.Http adds AddMiddleware<T>():

services.AddHttpClient<IOrderApi, OrderApi>(c => c.BaseAddress = new Uri("https://api.example.com"))
        .AddMiddleware<LoggingMiddleware>()
        .AddMiddleware<RetryMiddleware>();

This wraps calls to the service, not the underlying HttpClient: middleware sees GetAsync(7) returning an Order, not a GET /orders/7 returning 200 OK. Reach for a DelegatingHandler when you want the HTTP exchange itself — the two compose.

Typed clients registered under a name work the same way. A bare named client (AddHttpClient("orders")) registers no interface, so there are no method calls to intercept; put the middleware on the service that consumes it instead.

Samples

Three runnable console apps under samples/, one per package, printing what the pipeline did at each step:

dotnet run --project samples/Konduit.Sample
dotnet run --project samples/Konduit.MediatR.Sample
dotnet run --project samples/Konduit.Http.Sample

Requirements

Konduit targets netstandard2.0, net8.0 and net10.0, so it runs on .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5 and later, Mono, Xamarin and Unity.

Building requires the .NET 6 SDK or later. That is a property of the compiler, not of what you target: the proxies come from an incremental source generator, which needs Roslyn 4.0. You can build with a current SDK and still target net472.

The source generator ships inside the Konduit package; no separate reference is needed.