An AOT-safe, source-generated DataContractSerializer

[g7ed6e]

An AOT-safe, source-generated DataContractSerializer

Draft. Not ready to merge — see Open decisions for the calls that need a maintainer.

DataContractSerializer cannot run under PublishAot: it generates IL at run time and reflects over
members a trimmer has no reason to keep. Every CoreWCF service that carries a data contract inherits
that. This branch adds a Roslyn generator that reads [DataContract]/[DataMember] at compile time
and emits a reflection-free serializer per contract, plus the seam CoreWCF needs to use one.

It is an optimization with a fallback, not a replacement. With the switch off, not one byte of
CoreWCF's behaviour changes: GetSerializer returns null, the formatter uses the reflection-based
serializer, and the 155 existing CoreWCF.Primitives tests pass unchanged. Contracts migrate one at
a time.

The premise is executed rather than assumed: a CoreWCF service published with Native AOT answers over
HTTP, and the serializer it replaces fails on the same contract in the same binary.

---

Contents

• Scope
• What works
• How the generator is built
• How it was verified
• What the AOT smoke test found
• Still to do
• Open decisions
• Reviewing this

---

Scope

In: the operation body path. A service's parameters and return values are serialized and
deserialized by generated code when a context covers them.

Out, deliberately: everything else that constructs a DataContractSerializer directly —
PrimitiveOperationFormatter, FaultContractInfo, Message/MessageFault/MessageHeader(s)/
AddressHeader, and the WS-Trust and secure-conversation serializers. Those are listed under
Still to do; none of them is blocked by anything here.

Out, permanently: contracts with no accessible parameterless constructor.
DataContractSerializer allocates without running one and generated code cannot. These are written
byte-exactly and never read — the one place the generated path is strictly less capable than
reflection. It declines rather than producing a wrong graph.

---

What works

	Corpus coverage
WriteObject	81 of 86 cases byte-identical to the recorded fixture
ReadObject	79 of 86 — the same set minus the two constructors above

The five write-side skips are deliberate exclusions: three contracts whose [KnownType] names a
method resolved at run time, one with a non-public data member, one with no [DataContract] at all.

Capabilities covered, each verified byte-for-byte:

member ordering and Order EmitDefaultValue, IsRequired contract and member renaming every primitive XmlWriterDelegator handles i:nil, Nullable<T> nested contracts, inheritance enums, including [Flags] and [EnumMember]

arrays, List<T>, jagged arrays, ArrayList Dictionary<K,V> IsReference — z:Id/z:Ref, cycles [KnownType] and i:type polymorphism boxed members (object, ValueType, Enum, Array) [Serializable], Uri, DateTimeOffset, XmlQualifiedName DateOnly/TimeOnly, whose format the runtime decides

Verification

Suite	Result
CoreWCF.DataContractSerialization.Tests	365 passing × net8.0/9.0/10.0, 198 × net472, 0 failures
CoreWCF.DataContractSerialization.Generator.Tests	74 passing × net8.0/9.0/10.0
CoreWCF.Primitives.Tests (switch never set)	155 passing — the gate that matters
CoreWCF.sln	builds with 0 errors
AOT smoke test	published, run, all five stages pass

net472 runs the same suite and reports every case unsupported rather than silently passing, which
is a distinct outcome worth asserting: a pass because nothing ran looks identical to a pass because
everything matched.

---

How the generator is built

The pipeline

[DataContractSerializable] on a partial context class
        │
        ▼
ForAttributeWithMetadataName ──► Parser ──► ContextSpec ──► Emitter ──► one .g.cs
                                (symbols)   (values only)   (no symbols)

Parser is the only code that touches an ISymbol, and it runs inside transform — before
Collect() — so its result is a plain value Roslyn can compare and cache. Emitter never sees a
symbol or a Compilation.

This is a deliberate divergence from CoreWCF.BuildTools, noted in a comment where it matters.
Those generators hold raw ISymbol references in their specs and build them inside
RegisterSourceOutput, which defeats incremental caching and re-runs on every keystroke. The cost of
getting this wrong is build time, silently — it fails no test.

Two consequences of that rule shape the code:

• EquatableArray<T> wraps every collection on a spec. Arrays compare by reference, so a spec
  holding a bare T[] never equals its predecessor and the cache never hits.
• DiagnosticInfo / LocationInfo carry a diagnostic as values. A Diagnostic holds a
  Location, which holds a SyntaxTree, which roots an entire Compilation; putting one in a cached
  model would both defeat caching and keep compilations alive. The real diagnostic is built at the
  point of reporting.

Layout

Five files mirroring the house style of CoreWCF.BuildTools, ~5,400 lines:

File	Lines
…Generator.Emitter.cs	3,197	spec → StringBuilder → AddSource
…Generator.Parser.cs	1,451	the only symbol-aware code; reports diagnostics
…Generator.ContractSpec.cs	342	per-contract and per-member specs, MemberKind
…Generator.cs	88	pipeline only
EquatableArray.cs, DiagnosticInfo.cs, DiagnosticDescriptors.cs, Indentor.cs	~300	plumbing

What gets emitted

One partial fill-in for the user's context class, containing:

• shared helpers — WriteNil, IsNil, ReadText, ReadXsiType, ReadQName, WriteEnum/
  ReadEnum, the DateTimeOffset adapter, the boxed-primitive table and its inverse;
• a reference scope per direction — __ReferenceScope (object → id, plus the by-value cycle
  guard) and __ReadScope (id → object), one instance per WriteObject/ReadObject call so nothing
  survives between documents;
• a content writer and content reader per contract, taking the scope, with no wrapping element —
  the mirror of how the wire format nests;
• a serializer class per root contract, deriving from AotXmlObjectSerializer.

Three levels of falling back, all returning null or false

Level	Signal
The generator declines a contract	no serializer emitted; GetSerializer returns null
The context does not cover the operation's known types	CreateAotSerializer returns null
The serializer writes but cannot read	CanReadObject is false

None of them throws, and each is checked before use, so a contract the generator does not handle is
simply served by the reflection-based serializer. That is what makes step-by-step migration possible.

Since falling back under AOT means a runtime failure rather than a lost optimization, each one is
also a build warning — COREWCF_0403 (nothing generated) and COREWCF_0404 (written but not read),
both Warning severity and suppressible. They carry the reason, nested as far as it goes:

App.Outer … member 'Value' cannot be read back: App.Inner cannot be read back: member
'_hidden' is not public

Reported on the type the user listed, not on every contract reachable from it — a nested contract
that cannot be written makes its container unsupported too, and reporting both buries the actionable
line under its consequences.

The generated code is checked in

Five snapshots, taken with Verify.SourceGenerators, put ~4,600 lines of emitted code in the
repository under …Generator/tests/Snapshots/. Nobody reviewing a change to this generator can hold
six hundred lines of output in their head from a diff of the emitter; here they read the output, and
a change to it turns up in the diff of the pull request that caused it.

The line-by-line assertions stay, because the two answer different questions. An assertion says why
a rule exists — that a QName resolves its prefix before the element closes — and survives
reformatting. A snapshot says what was actually emitted, in full. A changed snapshot tells you
something moved but not whether it should have; a passing assertion tells you one line is right and
nothing about the other six hundred. Neither says the output is correct — only the corpus does
that, by comparing bytes against the real serializer.

Five cases rather than one per feature: each snapshot carries the shared helpers as well as its own
contract's code, so they overlap heavily and a sixth would mostly repeat the first. One of them is a
pair of contracts that fall back, because Verify renders diagnostics beside sources — making it the
one place the wording of COREWCF_0403/0404 is visible as a user reads it.

One snapshot serves all three target frameworks. Verify names the .received. file per framework so
concurrent runs cannot collide, but they are compared against the same .verified. file, which is
the right arrangement: the generator's output is a function of the contract it is given rather than
of the runtime the test host is on. Every run re-checks that claim.

Gated by target framework

CoreWCF.DataContractSerialization.props/.targets ship under build/buildTransitive and enable
the generator on net8.0+ only, mirroring how CoreWCF.Primitives.targets gates the OperationInvoker
generator. Two things follow: emitted code may assume a modern language version rather than the
oldest any consumer compiles with, and GetSerializer is virtual returning null rather than
abstract, so a user's partial class MyContext : DataContractSerializerContext still compiles on
net472 where the generator never runs — no #if in user code.

The seam

XmlObjectSerializer cannot be subclassed cleanly: all 16 members carry [RequiresDynamicCode] and
[RequiresUnreferencedCode], IL2046/IL3051 are symmetric so an override must repeat them, and CoreWCF
calls through the base-typed reference anyway. A reflection-free subclass would make serialization
work under AOT without silencing one warning.

The System.Text.Json answer applies: STJ never un-annotated Serialize<T>(T), it added
Serialize(T, JsonTypeInfo<T>) alongside. So this branch adds AotXmlObjectSerializer — an
attribute-free abstraction in CoreWCF.Primitives carrying only the four members the formatter uses —
and DataContractSerializerOperationBehavior.CreateAotSerializer beside CreateSerializer.
PartInfo prefers it for WriteObject, and for IsStartObject/ReadObject when CanReadObject.

Suppressing on CoreWCF's call sites was rejected: at that point CoreWCF cannot know whether the
instance is generated or a real DataContractSerializer, so the suppression would be unsound and
would turn build warnings into runtime failures in someone else's app.

---

How it was verified

Two disciplines did most of the work, and both are worth keeping.

An oracle, compared byte for byte

86 corpus cases — 75 imported from the WCF test corpus plus 11 written for shapes it does not
reach — each with its exact serialized bytes recorded from the real DataContractSerializer.
Generated output is compared to those bytes, never semantically.

That matters because the hard part is not the element tree, it is the namespace machinery. xmlns:z
sits on the root when the root contract is IsReference but is redeclared on every element when only
a nested member is; z:Id precedes the xmlns declarations in attribute order; a collection member
declares xmlns:b on the member element rather than the root. A semantic XML diff calls all of those
equal.

Per-TFM overrides record where runtimes genuinely differ — DateOnly writes an empty element before
.NET 10 and a value from .NET 10 on, so one test verifies both halves by running on both.

Fixtures are never regenerated to make the generator pass. A mismatch means the generator is
wrong.

The read side has its own oracle: read with generated code, write back with the reflection
serializer, compare to the fixture. A read bug shows up as a byte difference. It caught struct
contracts being read into a copy — ref was missing — which failed nowhere and lost every member.

Read upstream before implementing

System.Private.DataContractSerialization is MIT-licensed source. Reading it first, and citing the
file wherever a non-obvious rule is implemented, repeatedly beat inference:

• ReadElementContentAsTimeOnly goes through XmlConvert.ToDateTimeOffset, not the
  ParseTimeOnly helper defined next to it — which is dead code. Copying the helper would have
  narrowed what the reader accepts.
• A z:Ref never points forward, so IsReference needs an id table and not a fixup pass. Upstream
  says so outright: "BinaryFormatter supports this by fixing up such references later. These
  XmlObjectSerializer implementations do not currently support fix-ups. Hence we throw." What makes
  a cycle work is recording the instance before reading its members.
• Member ordering: unordered members precede ordered ones, including Order = 0, compared
  ordinally — settled by ClassDataContract.DataMemberComparer rather than by guessing.

What that combination caught

A sample, all of which passed casual inspection:

• sbyte is "byte" on the wire while byte is "unsignedByte"; char, Guid and TimeSpan are
  named in the serialization namespace because XML Schema has nothing to call them.
• writer.WriteValue(ulong) is ambiguous, not missing — CS0121 — so it surfaced as a compiler
  error in generated code rather than as wrong output.
• A null XmlQualifiedName member element does not get the q: prefix a non-null one does,
  because the prefix belongs to the path that writes a value. This was a live write-side bug found by
  a fixture added for the read side.
• A root holding a derived instance was written through the declared contract's writer, dropping every
  derived member with no i:type and no error — a silent-data-loss bug on the write path, found by
  building the read side.

---

What the AOT smoke test found

src/CoreWCF.DataContractSerialization.AotSmokeTest publishes a real service with PublishAot and
calls it with a raw HttpClient over a hand-written envelope. System.ServiceModel is not usable as
the client — it does not support AOT either, so a failure there would say nothing about the service.
It is not part of dotnet test; its README says how to run it.

  ok   runtime is AOT - IsDynamicCodeSupported=false
  ok   switch is left at its default - unset, so the no-dynamic-code default applies
  ok   generated serializer resolves and round-trips - 436 bytes, read back identical
  ok   service answers over HTTP - 569 bytes back, contents match
  ok   reflection serializer does not silently truncate - throws NullReferenceException,
       so the generated path is load-bearing here

Three findings the unit tests could not have shown.

The serializer this replaces loses data silently, not loudly. Same contract, same binary. Before
the contract types were rooted with [DynamicDependency], DataContractSerializer did not throw — it
wrote 95 bytes where the generated one wrote 436: a graph missing most of its members, returned as
though nothing were wrong. That is the concrete argument for warning on a fallback.

CoreWCF needs contracts rooted for the trimmer. TypeLoader finds operations by reflecting over
the contract interface and nothing calls those methods statically, so without [DynamicDependency]
the interface arrives with zero operations and the host refuses to start. An annotation gap in
CoreWCF, not something an application should have to know.

A warning-free publish is far off: 339 trim/AOT warnings, essentially all from CoreWCF — 207
IL3050, 72 IL2026, 56 assorted reflection patterns, and 4 IL3054 for generic recursion aborted in the
message filter tables, which throws if reached. They come from the security stack, the channel proxy
and the dispatcher. A service runs under AOT for this shape; it does so without the guarantees a
clean publish would give.

---

Still to do

The rest of the seam. CreateSerializer is not a complete injection point. Even with a perfect
generator, CoreWCF still constructs a reflection-based serializer directly in
PrimitiveOperationFormatter (selected instead of the DataContract formatter for simple contracts,
so the simplest services never reach any of this), FaultContractInfo, DeserializeHeaderContents,
the Message/MessageFault/MessageHeader(s)/AddressHeader family, and the WS-Trust and SCT token
serializers.

CoreWCF's own trim annotations. The 339 warnings above, and the TypeLoader rooting gap.

Two behavioural differences from reflection, both recorded in the risk register:

• an object member holding a collection throws where reflection succeeds — it cannot be a fallback,
  because by the time the runtime type is known the element is already open;
• contracts with no parameterless constructor cannot be read.

Two things nothing verifies. Incremental caching — the whole spec design exists to keep it
working and there is no test; it fails by costing build time. And CoversKnownTypes is exercised by a
generator test but not through GeneratedDataContractSerializerOperationBehavior.

---

Open decisions

These want a maintainer's call, not more code.

1. Public API names. AotXmlObjectSerializer, DataContractSerializerContext,
   DataContractSerializableAttribute become public API on first release. There is no public-API
   baseline in this repo, so nothing stops a rename now and nothing forgives one later. Aot in a
   type name may not age well — the property is "needs no dynamic code", which is also true under
   plain trimming.

2. Where the user's context lives. Today it sits in the test project, so a generator bug cannot
   break the corpus build that the reflection oracle depends on. That trade reverses the moment an
   in-slice case needs private member access.

3. Warning severity and noise. COREWCF_0403/0404 fire once per listed contract that falls
   back. On a large existing service that could be a lot of warnings on first adoption. Warning is
   the right default; whether to ship an opt-in escalation to error, or an opt-out, is a product call.

4. Should this be CoreWCF-specific at all? The generator reads System.Runtime.Serialization
   attributes and mirrors System.Private.DataContractSerialization — nothing about the hard part is
   CoreWCF. Three type names couple it. Splitting those into a neutral package would make it usable
   by System.ServiceModel clients and by plain DataContractSerializer users. Out of scope here,
   but the API decision in (1) is easier to make with an answer to this.

---

Reviewing this

178 files, +21,300/−9. Most of it is corpus, fixtures and generated-code snapshots. A reading
order that makes it tractable:

1. Documentation/DesignDocs/aot-datacontractserializer-risks.md — the design record: what the wire
   format actually does, every decision and why, the risk register, and what each upstream source
   settled. Written first and kept current; the best single entry point.
2. src/CoreWCF.Primitives/src/CoreWCF/Runtime/Serialization/ and the PartInfo changes in
   DataContractSerializerOperationFormatter.cs — the seam, and the only changes to existing CoreWCF
   behaviour.
3. …Generator/src/DataContractSerializerGenerator{,.Parser,.Emitter}.cs — the generator.
4. …Generator/tests/Snapshots/ — the generated code itself, if you would rather read the
   output than the emitter.
5. src/CoreWCF.DataContractSerialization/tests/ — the harness. GoldenRecordTests,
   ReadObjectTests and FixtureStore are how everything above is held to the recorded bytes.
6. src/CoreWCF.DataContractSerialization.AotSmokeTest/ — the end-to-end proof.

The commits are ordered by capability and each states what it verified, so git log --reverse reads
as the development narrative if that is more useful than the diff.

[github-actions]

✅ Test & Coverage Report

Result	Count
✅ Passed	32,002
❌ Failed	0
⚠️ Skipped	1,332
Total	33,334

Line coverage: 35.9% · Branch coverage: 36.4%

📋 Detailed test report · 📈 Coverage report

_{Updated for commit 878e002 from PR workflow run. Reports are regenerated on every push to the PR.}