Type handlers via attribute registration, with a shim for vanilla handlers

[mgravell]

Replaces the shipped-but-never-implemented [TypeHandler<TValue, THandler>] with a registration the generator actually reads.

TypeHandlerAttribute<,> and TypeHandler<T> ship in the package, but nothing in the analyzer or generator has ever consulted them — so every [module: TypeHandler<,>] written to date is a silent no-op (issues #159, #165, #173). There is no behavior to preserve, only metadata: both are now [Obsolete(..., error: true)] naming the replacement, and stay put, so binary compatibility holds.

Registration

[module: TypeHandler(typeof(LocalDate), typeof(LocalDateHandler))]

Non-generic on purpose: on .NET Framework, GetCustomAttributes() over an assembly or type carrying a generic attribute throws NotSupportedException for the whole call, which poisons unrelated third-party reflection, not just ours. Same wall we hit in protobuf-net, same typeof resolution.

Assembly/module scope only. A narrower scope (a handler for one member or parameter) is a plausible future addition — widening AttributeUsage and adding a constructor are both non-breaking — but shipping a form nothing reads is the problem this PR exists to remove. Deliberately not [Conditional("DEBUG")], unlike our enablement attributes: a package should be able to declare handlers for the types it owns, which needs the metadata to survive the build.

Runtime API

IDbValueHandler<T>, with a DbValueHandler<T> base for convenience: SetValue / SetNullValue (so a handler over a struct is never handed a null it cannot express), Parse for output parameters, and Tokenize / Parse(reader, ordinal, token) mirroring how generated row factories already work.

Existing Dapper handlers stay usable, across the snk boundary

An interface rather than a base class is what makes that possible. The library cannot reference Dapper — a consumer may be on Dapper or Dapper.StrongName, and referencing either loads both and splits the registry — but the generator sees the consumer's symbols, and generated code compiles against whichever Dapper they actually have. So a registration naming a SqlMapper.ITypeHandler emits

private static readonly global::Dapper.IDbValueHandler<global::Money> TypeHandler1
    = new global::Dapper.Aot.Generated.VanillaTypeHandler<global::Money>(new global::MoneyHandler());

with file sealed class VanillaTypeHandler<T> : IDbValueHandler<T> generated into the same file. Our interface, their implementation, a generated shim between. Migrating an existing handler is a matter of moving the registration out of a startup method, not rewriting the handler.

What generated code does

All four paths dispatch: AddParameters, the in-place UpdateParameters used by command caching, PostProcess for output parameters, and the row-factory read. One static per registration, emitted only for registrations the code actually reached; CanPrepare is cleared at handler sites, since the handler owns the parameter's type and size.

Tokenize is wired, which is what makes the read path worth having: a handler's per-column decision travels in the row factory's existing state channel — one int array per query, filled by a second pass over the token span (so it works the same whichever shape the mapping loop took), indexed positionally in Read. Members sharing a handler share a case-arm. One array per query, nothing per row.

TypeHandlerProtocolTests pins that contract from outside the generator: a hand-written factory in the shape the generator emits, asserting Tokenize runs once per column however many rows are read, that its token reaches every Parse, and that a factory reading a slice asks about its own column rather than column 0.

Diagnostics

• DAP053 — SqlMapper.AddTypeHandler in a Dapper.AOT compilation with no declarative registration for that type, naming the attribute to paste. Quiet when declared, quiet outside Dapper.AOT. It only sees calls in the compilation being built, so it narrows the silent-wrongness surface rather than closing it.
• DAP054 — a registration naming something generated code cannot use: implements neither contract, handles the wrong value type, no public parameterless constructor, abstract, static, inaccessible. These were skipped silently, which is the failure mode this whole PR exists to kill. A warning, not an error — the code still compiles, it just binds without the handler.
• DAP055 — two different handlers registered for one type. First registration wins deterministically (module scope before assembly, source order within each); the message names both and says which is dropped, as DAP021 does for parameters. An exact repeat stays quiet, since the outcome is identical either way.

All three have rule docs.

Does this satisfy #117 and #162?

Both external PRs ship the same fixture — module-scoped registration of a handler for a custom type, then three call sites — so it works as a statement of intent. TypeHandlerPriorArt.input.cs is that fixture translated verbatim (same call sites, type names, member names) into this PR's shapes, so the two can be read side by side. All three scenarios generate through the handler:

their scenario	here
Query<MyType> where MyType.C is the handled type	result.C = ... TypeHandler0.Parse(reader, columnOffset, handlerTokens[i])
Query<int>("def", new { Param = new CustomClass() }) — anonymous parameter	if (typed.Param is null) TypeHandler0.SetNullValue(p); else TypeHandler0.SetValue(p, typed.Param);, shape witness intact
[DbValue(Direction = Output)] CustomClass OutputValue	args.OutputValue = TypeHandler0.Parse(ps[0]);

The handler is emitted once, as a static readonly field shared by every factory in the file — #162's improvement over #117 (which allocated at every parameter and every column read), without the ??= its review flagged as non-atomic. #117's proposed read contract, Read(DbDataReader, int columnOffset), is satisfied as a superset: Parse(DbDataReader, int ordinal, int token) adds the per-column token.

Two spellings differ from theirs, both deliberate:

• registration is typeof-based, not generic — a generic attribute cannot be read by .NET Framework's GetCustomAttributes, which throws for the whole call and poisons unrelated reflection over the assembly;
• SetValueCore and Parse are abstract, where their base class defaulted them and their fixture's handler was empty. A handler that handles nothing should be a compiler error, not a silent pass-through.

Reading #162 for this also surfaced a gap it had solved and this PR had not: duplicate registrations were silently dropping the loser. That is now DAP055 — the credit is theirs.

One thing from #162 is deliberately not carried over: its TypeHandlerInstanceRegistry keys generator state on INamedTypeSymbol, which the plain-data model introduced in #187/#188 exists to prevent (and ModelShapeTests now enforces). The registry idea survives as TypeHandlerRegistration, projected to strings at parse time.

Verification

Full suite green on net8.0 (366) and net48 (359); solution builds clean. Golden fixtures cover a native handler, a vanilla handler through the shim, a nullable member, an output parameter, a command-cache update, a handler with a real Tokenize, and the prior-art scenarios above.

Relationship to #206

#206 (honor runtime registrations, behind an opt-in) is now closed: even gated, its read-side check landed in RowFactory.GetValue<T> — the type-flexible arm of every mapped member — so consumers who never enabled it still paid for it. This PR is the answer on its own, and existing Dapper handlers migrate by being named in the attribute rather than rewritten.