TCIS.Pluggable.Engine.Autofac 1.0.8-rc.9

TCIS.Pluggable.Engine.Autofac

Swaps the default DI container for Autofac and adds AOP logging to the Pluggable Engine: input arguments, execution time and exceptions are logged for boundary classes without a single logging statement in the business code.

Required for Template 3 (Pluggable). Optional — but recommended — for Templates 1 and 2.

Table of contents

1. Registration

dotnet add package TCIS.Pluggable.Engine.Autofac

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseTPluggableAutofac();

// or with explicit settings
builder.Host.UseTPluggableAutofac(
    configSection: "TLogSettings:AopSettings",
    configureOptions: o => o.TargetNamespaces.Add("Port.CatLai"));

A worker host (Host.CreateApplicationBuilder) has no IHostBuilder; use the IHostApplicationBuilder overload — same parameters, same behaviour. The IHostBuilder overload is unchanged.

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.AddTSerilog();
builder.UseTPluggableAutofac(configureOptions: o => o.ExcludedSuffixes.Add("Rule"));   // see section 3
builder.Services.AddTLogging(builder.Configuration);
builder.Services.AddPluggablePipeline(builder.Configuration, typeof(MyPlatformModule).Assembly);

One call does three things:

Step 3 matters more than it looks: without it, discovery and metrics would report the proxy type name instead of your class, and step resolution by type would miss. The resolver is registered inside the Autofac container, so it wins over the engine's DefaultRealTypeResolver whether UseTPluggableAutofac is called before or after AddPluggablePipeline. (Before 30/10/2026 it went through IServiceCollection and the call order decided which one won — the default one winning made every rule "not seen by discovery" under RequireRuleOrder.)

2. What gets intercepted

PluggableLoggingModule decides in four steps:

Rule 2 is the important one: every pipeline step and business rule is instrumented regardless of its name, because those are exactly the classes whose duration and failures the metrics are built on. Rule 1 still runs first, so an ExcludedSuffixes entry removes even a step or a rule.

The proxy is an interface proxy with target, which has two consequences:

Code that resolves an interface and casts the result to its concrete class throws InvalidCastException under the proxy. Read the real type with IRealTypeResolver, never with GetType() on an instance.

// Intercepted — implements IPipelineStep<>
[PlatformStep("Gate.ValidateContainer", executionOrder: 10)]
public sealed class CoreValidateContainerStep : IPipelineStep<IGateInContext> { … }

// Intercepted — name ends with "Service"
public sealed class BerthAllocationService : IBerthAllocationService { … }

// NOT intercepted — name ends with "Context"
public sealed class GateInContext : TPipelineContextBase<GateInResponse> { … }

3. Configuration

{
  "TLogSettings": {
    "AopSettings": {
      "TargetNamespaces":  [ "TCIS" ],
      "ExcludedSuffixes":  [ "Context", "Options", "Attribute" ],
      "IncludedSuffixes":  [ "Service", "QueryProvider" ]
    }
  }
}

Pipelines with many rules

Every intercepted call writes one record — successes included. A pipeline running 40 rules per item writes 40 rule records per item, and a worker that re-scans a waiting queue every few seconds writes them again on every pass. Three knobs, none of which changes the package defaults:

Declare these in code (configureOptions) rather than in appsettings, next to the reason — and see section 4 for why appsettings lists append instead of replacing.

Testing a host that uses Autofac

AutofacServiceProviderFactory has no equivalent of ValidateOnBuild / ValidateScopes: a missing registration surfaces only when resolved, and a singleton holding a scoped service is not reported — the scoped instance lives for the container's lifetime. Keep both:

1. a test that builds the registrations on Microsoft DI with ValidateOnBuild = true, ValidateScopes = true — the registration check;
2. a test that builds the host exactly as Program does (ideally through the same method), on Autofac — the check of what actually runs, proxies included.

4. ⚠️ The configuration binding trap

IConfiguration.Bind appends to a list that already holds defaults; it does not replace it.

{ "TLogSettings": { "AopSettings": { "TargetNamespaces": [ "Port.CatLai" ] } } }

// What you expect
["Port.CatLai"]

// What you actually get
["TCIS", "Port.CatLai"]

This surprises people in both directions: a namespace you meant to exclude stays included, and a list you meant to shrink grows instead. To end up with only your own value, clear the list in code:

builder.Host.UseTPluggableAutofac(configureOptions: o =>
{
    o.TargetNamespaces.Clear();
    o.TargetNamespaces.Add("Port.CatLai");
});

configureOptions runs after binding, so it always has the last word.

This behaviour is pinned by R4_AopOptionsBindingTests — it is a property of Microsoft.Extensions.Configuration, not something this package can change.

5. Pitfalls

Captive dependencies are avoided by design: the interceptor is ResolveNamed-ed inside the middleware, once per resolution, rather than being held at module scope. Do not "optimise" that by caching the interceptor — it would capture a scoped graph into a singleton.