|
| 1 | +# Ploch.Data Repository Research |
| 2 | + |
| 3 | +This note captures a maintainer-focused map of the repository: packages, structure, build/test tooling, conventions, and external dependencies needed to work locally. |
| 4 | + |
| 5 | +## Layout |
| 6 | + |
| 7 | +- `src/` – library projects: |
| 8 | + - `Data.Model` – standard entity interfaces and base types (audit, hierarchical, tags/categories, properties). |
| 9 | + - `Data.EFCore` – EF Core utilities (connection string helper, `IDbContextConfigurator`, `BaseDbContextFactory`, data seeding). |
| 10 | + - `Data.EFCore.{SqLite,SqlServer}` – provider configurators and factories (SQLite also applies the `DateTimeOffset` converter fix). |
| 11 | + - `Data.GenericRepository` – provider-agnostic repository/UoW interfaces and audit handler abstractions. |
| 12 | + - `Data.GenericRepository.EFCore` – EF Core implementations plus DI registration; `.Specification` adds Ardalis.Specification helpers; provider-specific DI wrappers under `.EFCore.{SqLite,SqlServer}`; `.IntegrationTesting` has repository/UoW test base. |
| 13 | + - `Data.EFCore.IntegrationTesting` – EF Core integration test base (`DataIntegrationTest<TDbContext>`). |
| 14 | + - `Data.StandardDataSets`, `Data.Utilities` – datasets and utility helpers. |
| 15 | +- `tests/` – integration and unit tests for EF Core, providers, GenericRepository, datasets. |
| 16 | +- `docs/` – main documentation set (getting-started, architecture, data-model, generic-repository, dependency-injection, integration-testing, extending, data-project-setup). |
| 17 | +- `samples/SampleApp/` – standalone consumer example with dual build modes (package vs project refs) showing modelling, DI, provider switching, migrations, and integration tests. |
| 18 | +- `docfx_project/`, `DocumentationSite/` – doc generation/site output. |
| 19 | +- Build scripts: `build.sh`/`build.ps1` (NUKE), `build-dotnet-commands.ps1`, `azure-pipelines.yml`, `qodana.yaml`, `docker-compose.yml`. |
| 20 | + |
| 21 | +## Design Highlights |
| 22 | + |
| 23 | +- Clear layering: `Model` (interfaces/POCOs) → `EFCore` utilities → provider packages → `GenericRepository` (interfaces) → `GenericRepository.EFCore` (impl/DI) → specification/integration testing helpers. |
| 24 | +- DI entrypoints: `AddDbContextWithRepositories<TDbContext>()` (provider-specific packages) or `AddRepositories<TDbContext>()` for manual DbContext registration; lifecycle plugin via `IDbContextCreationLifecycle` injected into DbContext. |
| 25 | +- Repository interfaces emphasise interface segregation (`IReadRepositoryAsync`, `IReadWriteRepositoryAsync`, `IQueryableRepository`, `IUnitOfWork`); audit handling via `IAuditEntityHandler` + `IUserInfoProvider`. |
| 26 | +- Testing support: `DataIntegrationTest<TDbContext>` (in-memory SQLite) and `GenericRepositoryDataIntegrationTest<TDbContext>` with helpers; sample app tests demonstrate repository and UoW behaviours. |
| 27 | + |
| 28 | +## Build, Test, and Tooling |
| 29 | + |
| 30 | +- Target frameworks: libraries default to `net10.0` (some multi-target `net8.0`); nullable enabled; analyzers on with `TreatWarningsAsErrors` for test projects. |
| 31 | +- Versioning/packaging: Nerdbank.GitVersioning (`version.json`), SourceLink, central package management (`Directory.Packages.props`). |
| 32 | +- Builds/tests typically via `dotnet test Ploch.Data.slnx` or NUKE (`./build.sh`), but the solution uses conditional project references to a sibling **ploch-common** repo and shared props under `../mrploch-development/dependencies`. Without those checkouts, Debug/default builds fail with missing project/props files. Use `-p:UseProjectReferences=false` or Release with packaged dependencies when the shared repos are unavailable (packages must be in the feed). |
| 33 | +- Baseline in this workspace: `dotnet test Ploch.Data.slnx` currently fails because `../ploch-common` projects are absent. |
| 34 | + |
| 35 | +## Sample Application Rules (critical) |
| 36 | + |
| 37 | +- Treat SampleApp as an external consumer: csproj files must keep `PackageReference` to Ploch.Data packages; switching to `ProjectReference` happens automatically via `ProjectReferences.props` (do not edit csproj to swap). |
| 38 | +- SampleApp `Directory.Build.props`/`Directory.Packages.props` are self-contained; do not import from parents. |
| 39 | +- Update `ProjectReferences.props` when adding new Ploch.Data packages; bump `PlochDataPackagesVersion` in SampleApp package props after publishing new versions. |
| 40 | + |
| 41 | +## Conventions to Note |
| 42 | + |
| 43 | +- Default `UseProjectReferences=true` in non-Release builds (set in `Directory.Build.props`); makes local debugging depend on sibling repos. |
| 44 | +- Tests use xUnit + FluentAssertions; coverlet included for coverage. |
| 45 | +- Central connection-string helper (`ConnectionString.FromJsonFile`) expects `appsettings.json` copied to output. |
| 46 | +- Auditing: entities implementing `IHasAuditProperties`/`IHasAuditTimeProperties` get timestamps set by `AuditEntityHandler`; `IUserInfoProvider` defaults to `NullUserInfoProvider`. |
| 47 | + |
| 48 | +## Useful Commands |
| 49 | + |
| 50 | +- Restore/build/tests (packages available, no sibling repos): `dotnet test Ploch.Data.slnx -p:UseProjectReferences=false` |
| 51 | +- NUKE pipeline: `./build.sh` (uses `build/_build.csproj`) |
| 52 | +- SampleApp: `dotnet build Ploch.Data.SampleApp.slnx` (standalone package mode) or `dotnet build Ploch.Data.slnx -p:UsePlochProjectReferences=true` (solution mode) |
0 commit comments