(MAJOR): Make Reflection.Emit the only runtime patch class builder

[PaulTrampert]

Closes #126

Cause

Since #130 and #136 the library has had two builders for the same patch class. One is the original builder, which generates C# with CodeDom and compiles it with Roslyn. The other is a Reflection.Emit builder, behind the experimental PatchClassBuilder.UseExperimentalDynamicClassBuilder flag that shipped in v1.5.0. The process-wide switch adds runtime complexity, and the Roslyn path has limits that the Emit path doesn't have. It can't patch internal write models, and it breaks under single-file publishing because it builds metadata references from Assembly.Location.

Fix

• PatchClassBuilder.GetPatchClassFor now always delegates to EmitPatchClassBuilder.Instance. Emit is the only builder used at runtime.
• PatchClassBuilder.UseExperimentalDynamicClassBuilder is removed outright, and so are its tests. Its GetPatchClassFor <exception> docs now describe when Emit throws.
• RoslynPatchClassBuilder is kept as internal, unused, tested code, pending Generate patch classes at compile time with a source generator #144. That issue decides whether it becomes a compile-time source generator. This departs from Remove the Roslyn-based patch class builder in favour of Reflection.Emit #126's scope, which asked for the Roslyn path to be deleted, because the maintainer wants it kept until Generate patch classes at compile time with a source generator #144 is decided.
  • The class remarks say it isn't used at runtime and is kept pending Generate patch classes at compile time with a source generator #144.
  • Its "not public" error no longer mentions the removed flag.
  • The Microsoft.CodeAnalysis.CSharp and System.CodeDom package references remain, so consumers still get them transitively. The .csproj has a comment explaining why.
• Tests:
  • PatchClassBuilderTest is still parameterized over both builders through PatchClassBuilders, calling the internal builders directly, so the two can't drift apart.
  • RoslynPatchClassBuilderTest is kept. Its shared-cache test, which asserted that PatchClassBuilder hands out Roslyn types, is now a plain Roslyn cache test.
  • New PatchClassBuilderDelegationTest covers the public entry point:
    • PatchClassBuilder (including the obsolete constructor) hands out the Emit builder's types.
    • An internal model round-trips through IPatchObject<T> with validation.
    • A private nested type throws NotSupportedException.
  • EmitPatchClassBuilderTest gains a concurrent-first-use test.
  • The Swashbuckle and OpenApi ExperimentalDynamicClassBuilderTest files are renamed to InternalWriteModelTest, without the flag, TearDown or [NonParallelizable].
• Docs:
  • README: "Non-public write models (experimental)" is now "Internal write models", and there is a new "Deployment" section.
  • docs/getting-started.md matches the README.
  • AGENTS.md "How it works" describes Emit as the runtime builder, and the Roslyn builder as unused, tested code pending Generate patch classes at compile time with a source generator #144.

Single-file publishing (investigated, as #126 asks)

I published PTrampert.SimplePatch.Sample with -r linux-x64 --self-contained false -p:PublishSingleFile=true and sent a PATCH to /People/1:

• release/2.0 (Roslyn): HTTP 500. CS0518: Predefined type 'System.Object' is not defined or imported and CS0234 for IPatchObject<>. Roslyn gets no metadata references because the bundled assemblies have no Location.
• This branch (Emit): HTTP 200 with the patched person. I re-checked this after restoring the Roslyn builder. The Roslyn assemblies are still bundled, but nothing on the runtime path calls into them.

The README's new Deployment section says single-file publishing is supported, and that Native AOT and trimming aren't. I didn't add an automated single-file test or sample. It would need a publish-and-run step in CI, which is a larger change than this PR should carry.

Observable behaviour changes for consumers

• PatchClassBuilder.UseExperimentalDynamicClassBuilder is gone. Code that sets it no longer compiles, and existing binaries fail with MissingMethodException.
• Generated types change:
  • They are named <Namespace>.Optionals.<Type>_Optionals, without the random suffix.
  • They live in a dynamic assembly named PTrampert.SimplePatch.Emitted, so Assembly.IsDynamic is true and there is no Location.
• Internal write models now work when their assembly declares [InternalsVisibleTo("PTrampert.SimplePatch.Emitted")]. Without that grant, they still throw NotSupportedException, and the message names the grant and the assembly that needs it.
• Private and protected nested types still throw NotSupportedException.
• If generation fails, the error surfaces from Reflection.Emit (TypeLoadException / InvalidProgramException), not as Roslyn diagnostics.
• Single-file published apps now work.
• Unchanged: Microsoft.CodeAnalysis.* and System.CodeDom still arrive transitively, until Generate patch classes at compile time with a source generator #144 is decided.

Alternatives rejected

• Delete the Roslyn builder and its dependencies now, as Remove the Roslyn-based patch class builder in favour of Reflection.Emit #126 originally scoped. I did this in this PR's first commit, then reverted it, because the maintainer wants the code kept until Generate patch classes at compile time with a source generator #144 decides whether it becomes a source generator.
• Keep UseExperimentalDynamicClassBuilder as an [Obsolete] no-op. Remove the Roslyn-based patch class builder in favour of Reflection.Emit #126 rules this out. The removal ships in the same major as the other breaking changes, and a compile error is the clearest signal.
• Keep the flag so the Roslyn builder stays selectable. That would keep the process-wide switch and the unsupported single-file path reachable. The dead code is exercised by tests instead.

Coordination with parallel 2.0 PRs

• Retype PatchClassBuilder.Instance to IPatchClassBuilder #135 (retype PatchClassBuilder.Instance to IPatchClassBuilder): this PR leaves Instance and its type alone. When both land, Retype PatchClassBuilder.Instance to IPatchClassBuilder #135's Instance getter will need to resolve to EmitPatchClassBuilder.Instance.
• Make PatchClassBuilder's constructor internal #75 (constructor visibility): this PR doesn't touch the obsolete public constructor. PatchClassBuilderDelegationTest calls it under #pragma warning disable CS0618, and will keep compiling if the constructor becomes internal, because the test project has InternalsVisibleTo.

Test results

• dotnet build: 0 errors, 21 warnings, the same count as release/2.0.
• dotnet test:
  • PTrampert.SimplePatch.Test (net8.0): 128 passed. That is 129 on release/2.0, minus 5 flag tests, plus 4 new ones.
  • PTrampert.SimplePatch.Swashbuckle.Test (net8.0): 18 passed.
  • PTrampert.SimplePatch.OpenApi.Test (net10.0): 12 passed.
• Only the .NET 10 runtime is installed locally, so I ran the net8.0 test hosts with DOTNET_ROLL_FORWARD=Major.
• CI won't run these tests on this PR. The main pipeline only runs on PRs to main, so PRs into release/2.0 get only the title check. The net8.0 suites will first run in CI when release/2.0 is merged to main.

🤖 Generated with Claude Code

[github-actions]

✅ PR Title Formatted Correctly

The title of this PR has been updated to match the correct format. Thank you!