62 lines
1.9 KiB
Markdown
62 lines
1.9 KiB
Markdown
# Source-Generated Mapping
|
|
|
|
## Purpose And Business Outcome
|
|
|
|
Generate compile-time mapping code to reduce runtime overhead and reflection risk for serialization paths.
|
|
|
|
## Scope And Non-Goals
|
|
|
|
Scope:
|
|
- Entity metadata analysis
|
|
- Mapper source generation
|
|
- Collection initialization helpers
|
|
|
|
Non-goals:
|
|
- Runtime dynamic mapping for unknown schemas
|
|
- Support for unsupported C# patterns outside generator design
|
|
|
|
## User And System Workflows
|
|
|
|
1. Consumer defines entities and context patterns.
|
|
2. Build invokes source generator.
|
|
3. Generated mapper code is compiled into target project.
|
|
4. Runtime serialization path uses generated code.
|
|
|
|
## Interfaces And APIs
|
|
|
|
- Source generator project under `src/CBDD.SourceGenerators`
|
|
- Attributes in BSON and data-annotation mapping surface
|
|
- Generated initialization methods for context collections
|
|
|
|
## Permissions And Data Handling
|
|
|
|
- Generated code can expose field-level mapping behavior.
|
|
- Repository write permissions should be limited to trusted contributors.
|
|
|
|
## Dependencies And Failure Modes
|
|
|
|
Dependencies:
|
|
- Roslyn source generator execution during build
|
|
- Entity schema conventions
|
|
|
|
Failure modes:
|
|
- Missing generation due to invalid entity declarations
|
|
- Serialization mismatch caused by attribute/model changes
|
|
|
|
## Monitoring, Alerts, And Troubleshooting
|
|
|
|
- Monitor build output for generator diagnostics.
|
|
- Use [`../runbook.md`](../runbook.md) for escalation.
|
|
- Follow [`../security.md`](../security.md) for review and control expectations.
|
|
- Use [`../troubleshooting.md`](../troubleshooting.md#source-generation-issues) for remediation steps.
|
|
|
|
## Rollout And Change Considerations
|
|
|
|
- Generator behavioral changes require broad regression tests across entities.
|
|
- Document any new constraints or unsupported patterns in release notes.
|
|
|
|
## Validation Guidance
|
|
|
|
- Run source generator and serialization tests in `tests/CBDD.Tests`.
|
|
- Validate mapper generation with clean `dotnet build` in CI.
|