Type handlers: honor runtime registrations, behind [UseRuntimeTypeHandlers]

[mgravell]

Draft. Reopened and reworked: the behavior is the same as before, but it is now opt-in rather than the default, which is what makes it defensible — and what shrinks the diff from 107 files to 24.

What it does

Generated code can honor type-handlers registered at runtime with SqlMapper.AddTypeHandler, by deferring to Dapper's own decision procedure when it executes: LookupDbType on the write side, and on the read side a bridge installed from a module initializer, compiled against the consumer's own Dapper (the library cannot reference Dapper — a consumer may be on Dapper or Dapper.StrongName, and referencing either loads both and splits the registry). Design and probed contracts in notes/typehandlers-design.md.

Why it is off by default

Honoring a registration made at run time is not a neutral choice:

• it is not AOT-safe. What it defers to reaches SqlMapper.TypeHandlerCache<T>, a generic instantiated over a runtime-chosen type. ILC cannot know which instantiations to keep and nothing warns at publish; issue TypeHanderCache issue #165 is that crash on a deployed app;
• it keeps the world open, so nothing reachable from the registry can be trimmed;
• it costs a lookup per parameter on unrecognized types;
• it cannot be checked at build, where a declared handler can be;
• generated code baked its decision at compile time, so a registration arriving later is either ignored or forces a per-operation check to catch it.

So: [module: UseRuntimeTypeHandlers], default off, and DAP053 reports that attribute combined with PublishAot=true — the one configuration where it is a trap rather than a trade.

Assembly/module scope only, enforced by AttributeUsage rather than by a diagnostic we would have to invent: a handler registration is a property of a type, so it cuts across every call-site touching that type, and per-method scope would let one type bind two different ways in one process.

Measured both ways

Same build, Dapper test suite, net10.0, local SQL Server:

harness	passed	failed	skipped	interception
[module: UseRuntimeTypeHandlers]	705	64	24	533 / 725
default (no attribute)	677	92	24	533 / 725

The default line is the clean-main baseline exactly — nothing changes for anyone who does not ask. The corpus keeps its 705 for one line in DapperAotEnable.cs, so no test in that suite needs editing, and interception is identical either way: the gate changes how unrecognized member types bind, not which call-sites are handled.

When off, the emitted dispatch disappears from every call-site and the module initializer is not emitted, so the bridge short-circuits on a null delegate. The residue in the library is one null check on the flexible read path and one Resolve call per query.

Still open

• the declarative replacement this is a transition away from is Type handlers via attribute registration, with a shim for vanilla handlers #208, which is where [TypeHandler(typeof(V), typeof(H))] and IDbValueHandler<T> live; DAP053's message should eventually point at it, and Type handlers via attribute registration, with a shim for vanilla handlers #208 renumbers its own diagnostic to DAP054;
• deferred by decision, unchanged: AddTypeMap on recognized scalars (the AnsiString pair) and the SetTypeMap runtime column-mapping family;
• prior art Typehandler support #117 and feat: TypeHandler support #162 remain the right shape for the static tier and deserve a decision independent of this PR.

[mgravell]

Two additions from the design discussion: enum parameters no longer pay the lookup unless Settings.PreferTypeHandlersForEnums is actually on (a static bool read guards it; vanilla only consults enum handlers under that setting anyway), and the design note now records the agreed direction — declarative [module: ...] config attributes as the primary spelling (better scoped than the process-global registries they replace, per-assembly and deterministic), with this PR's runtime bridge as the compatibility tier and a strict switch to come. Post-gate cost profile: recognized scalars pay zero, enums pay a field read, one dictionary hit per query for the whole-type check — the remaining per-parameter lookups land only on types that were previously an exception. Suite holds at 705/793.

[mgravell]

Closing this. The gate made it opt-in, but it does not make it free: the bridge's read-side check sits in RowFactory.GetValue<T>, which is the type-flexible arm of every mapped member — around 130 call sites across the interceptor goldens, taken whenever a column type does not exactly match the member type. That path picks up a DBNull type test it did not have, a typeof(T) materialisation, and a static delegate probe, and it stops being a single-expression method that inlines into generated code. Everyone pays that, including the large majority who would never turn the feature on.

I could push the check behind the opt-in at emission time rather than at runtime, the way the write side already works. But it buys a second read path to maintain, in the runtime library, for a mode whose whole purpose is to be temporary — and one that cannot be published with native AOT anyway, since what it defers to reaches SqlMapper.TypeHandlerCache<T>.

So the declarative form in #208 is the answer, and this is not needed alongside it. Existing handlers written against Dapper are not orphaned: name the type in [module: TypeHandler(typeof(Money), typeof(MoneyHandler))] and generated code adapts a SqlMapper.ITypeHandler through a shim, so migrating is moving the registration out of a startup method, not rewriting the handler.

The branch stays for reference — the probed contracts in notes/typehandlers-design.md (handlers want DBNull rather than null; char has to stay out of the dispatch because StringFixedLength pads) were paid for and are worth keeping.