Document DI and STJ modernization plan

Author: niemyjski

docs/brainstorms/2026-07-12-modern-di-stj-brainstorm.md

@@ -0,0 +1,35 @@
+---
+date: 2026-07-12
+topic: modern-di-stj
+---
+
+# Modern DI and System.Text.Json
+
+## What We're Building
+
+Modernize the Exceptionless .NET client without requiring consumers to rewrite their existing setup. Replace the vendored internal Newtonsoft.Json fork with System.Text.Json while preserving the collector wire format, persisted queue compatibility, exclusions, depth limits, and arbitrary `DataDictionary` values. Replace TinyIoC with Microsoft.Extensions.DependencyInjection behind the existing `IDependencyResolver`, and add an `IServiceCollection` customization seam for new integrations.
+
+## Why This Approach
+
+A direct removal of `IDependencyResolver` would break configuration extensions, plugins, legacy platforms, isolated clients, and applications that do not use the Generic Host. Keeping TinyIoC indefinitely avoids that break but leaves the client with a private container implementation and prevents normal Microsoft DI customization. The staged adapter approach modernizes the implementation now, makes Microsoft DI the extensibility path, and leaves removal of the compatibility facade for a future major release.
+
+The STJ migration already exists as four focused commits on `niemyjski/drop-json-net-use-stj`. Reusing and rebasing that work is lower-risk than independently recreating its converters and regression fixes.
+
+## Key Decisions
+
+- Preserve `IDependencyResolver` and all existing `ExceptionlessClient` constructors in this release.
+- Back `DefaultDependencyResolver` with `Microsoft.Extensions.DependencyInjection` singleton registrations.
+- Preserve unregistered concrete-type activation and replacement registration behavior.
+- Allow explicit `IServiceCollection` customization before the resolver is used.
+- Keep Exceptionless' internally owned provider isolated from an application's root provider; hosted apps continue resolving `ExceptionlessClient` from application DI.
+- Treat serialized JSON as a compatibility contract, not merely valid JSON.
+- Keep STJ converters reflection-based for `netstandard2.0` and `net462` compatibility; source generation can be a later optimization.
+
+## Open Questions
+
+- Removing `IDependencyResolver` and making every internal service directly application-DI-owned is deferred to a future major version.
+- A separate performance benchmark can decide whether STJ source generation is worth the additional model metadata surface.
+
+## Next Steps
+
+Implement the plan in `docs/plans/2026-07-12-modern-di-stj-plan.md` and verify focused serializer, resolver, storage, hosting, and full non-Windows test coverage.

docs/plans/2026-07-12-modern-di-stj-plan.md

@@ -0,0 +1,39 @@
+# Modern DI and System.Text.Json implementation plan
+
+## Compatibility baseline
+
+1. Run the current non-Windows solution tests before editing.
+2. Inventory exact JSON assertions, storage round-trips, resolver semantics, hosting registrations, and package target frameworks.
+
+## System.Text.Json
+
+1. Rebase the existing `niemyjski/drop-json-net-use-stj` commits onto current `main`.
+2. Resolve package-version and current-main conflicts without weakening serializer tests.
+3. Retain exact collector property names, enum strings, null/default output, `DataDictionary` raw-value markers, settings coercion, POST data behavior, exclusions, maximum depth, and stream ownership.
+4. Run focused serializer, storage, configuration exclusion, submission, and MessagePack tests.
+
+## Dependency injection
+
+1. Add Microsoft.Extensions.DependencyInjection to the core package for all supported targets.
+2. Replace TinyIoC in `DefaultDependencyResolver` with an `IServiceCollection`-backed provider.
+3. Preserve the existing registration lifetimes: interface/abstract mappings are singletons, concrete mappings and factories are transient, and explicit instances remain externally owned singletons.
+4. Preserve isolated resolvers, constructor injection, singleton resolution, unregistered concrete activation, null argument behavior, disposal, and registrations made after an initial resolution.
+5. Add a constructor/customization seam that accepts an `IServiceCollection` so new code can use normal Microsoft DI registrations without depending on the legacy methods.
+6. Add focused tests for service collection customization, replacement registration, late registration, and disposable singleton ownership.
+
+## Validation and readiness
+
+1. Build the non-Windows solution with warnings as errors.
+2. Run the complete non-Windows test suite.
+3. Pack the core and modern platform projects to catch dependency/package metadata issues.
+4. Inspect the final diff for accidental API breaks and remaining Newtonsoft/TinyIoC references.
+5. Document Windows-only validation that still needs CI when it cannot be run on macOS.
+
+## Execution results
+
+- Baseline: 300 core tests and 10 MessagePack tests passed; 18 existing tests were skipped.
+- Final non-Windows suite: 313 core tests and 10 MessagePack tests passed; 0 failed; the same 18 tests were skipped.
+- Focused DI coverage now includes singleton and transient compatibility, constructor injection, isolated containers, late replacement, `IServiceCollection` overrides, open generics, container disposal, external instance ownership, and host-provider disposal of the default client.
+- Serializer coverage retains exact wire-format assertions and adds regressions for exclusions, depth limits, `DataDictionary` structured/raw values, settings coercion, and MessagePack marker round-trips.
+- `net462` core and `net472` test assemblies build with 0 warnings and 0 errors when Windows targeting is forced on macOS. Runtime execution of the .NET Framework tests still belongs in Windows CI.
+- The non-Windows solution packs successfully. A Windows-shaped core package containing both `net462` and `netstandard2.0` assets also packs successfully with explicit `SolutionDir`.