model-building

---
name: model-building
description: 'Implementation details for EF Core model building. Use when changing ConventionSet, ModelBuilder, IConvention implementations, ModelRuntimeInitializer, RuntimeModel, or related classes.'
user-invocable: false
---

# Model Building, Conventions & Initialization

Covers model construction (conventions, fluent API, metadata hierarchy) and model initialization (runtime annotation propagation, compiled model filtering).

## Convention System

`ConventionSet` (`src/EFCore/Metadata/Conventions/ConventionSet.cs`) holds `List<I*Convention>` for every metadata event. Key conventions in `src/EFCore/Metadata/Conventions/`:

- `DbSetFindingConvention` — discovers entities from `DbSet<T>`
- `PropertyDiscoveryConvention` — discovers properties from CLR types
- `KeyDiscoveryConvention` — finds PKs (`Id`, `TypeId`)
- `RelationshipDiscoveryConvention` — infers FKs from navigations
- `RuntimeModelConvention` — creates optimized `RuntimeModel` from mutable model

Override `ConfigureConventions(ModelConfigurationBuilder)` to add/remove conventions.

## Metadata Interface Hierarchy

`IReadOnly*` → `IMutable*` → `IConvention*` → `IRuntime*`

Applies to: Model, EntityType, Property, Key, ForeignKey, Navigation, Index, etc. Builders follow: `*Builder` → `IConvention*Builder`.

## Model Lifecycle

1. **Mutable Model** — built by `ModelBuilder` during `OnModelCreating`, made read-only by `FinalizeModel()`
2. **Design-Time Model** — finalized read-only `Model` that also contains design-time-only annotations used in migrations
3. **Runtime Model** — an optimized read-only model created by `RuntimeModelConvention.ProcessModelFinalized()`, does not contain design-time-only annotations

`ModelRuntimeInitializer.Initialize()` (called by `DbContextServices.CreateModel()`):

```
Initialize(model, designTime, validationLogger)
├─ FinalizeModel() if mutable
├─ Set ModelDependencies, InitializeModel
└─ RuntimeModelConvention creates RuntimeModel, copies/filters annotations
```

## Complex Type Property Recursion

When processing properties in conventions or validation, remember that complex types can contain their own declared properties. Use `GetFlattenedProperties()` to iterate all properties (including on nested non-collection complex types) or manually recurse through `GetDeclaredComplexProperties()` → `complexProperty.ComplexType`.

## Adding a New Annotation

1. Add constant to `CoreAnnotationNames` and its `AllNames`
2. Filter in `RuntimeModelConvention.ProcessModelAnnotations` if it's a design-time-only annotation (only used in migration operations)
   1. If it was filtered out, add logic to the getters that throws an exception if accessed on the runtime model
3. Filter in `CSharpRuntimeAnnotationCodeGenerator.Generate` if it can be computed lazily at runtime (e.g. based on other annotations)
4. Propagate in `RelationalAnnotationProvider` if used in up-migrations or the relational model and `IMigrationsAnnotationProvider` if used in down-migrations

## Relational Model

`RelationalModel` (`src/EFCore.Relational/Metadata/Internal/RelationalModel.cs`) is a database-centric view of the EF model, mapping entity types to physical database objects: `Tables`, `Views`, `Functions`, `Queries`, and `DefaultTables`. `DefaultTables` are pseudo-table objects only used for `FromSql` queries.

Created lazily by `RelationalModelRuntimeInitializer`, accessed via `model.GetRelationalModel()`. Used by migrations (`MigrationsModelDiffer`), update and query pipelines.

`RelationalAnnotationProvider` populates annotations on relational model elements. Provider subclasses (e.g., `SqlServerAnnotationProvider`) add provider-specific annotations. `IMigrationsAnnotationProvider` controls annotations used in down-migration operations.

## Model Validation

`ModelValidator` (`src/EFCore/Infrastructure/ModelValidator.cs`) and `RelationalModelValidator` (`src/EFCore.Relational/Infrastructure/RelationalModelValidator.cs`) run after model finalization, during `ModelRuntimeInitializer.Initialize()` between the pre- and post-validation `InitializeModel` calls.

## Migration Snapshot Compatibility

Model-building changes can trigger spurious migrations for users who upgrade. Two causes:

1. **New metadata written to the snapshot** — old snapshots won't have it; `MigrationsModelDiffer` sees a diff. Fix: ensure absence of the annotation in an old snapshot is treated as the old default.
2. **Annotation renamed or reinterpreted** — old snapshots produce a different model. Fix: keep backward-compatible reading logic.

Inspect `CSharpSnapshotGenerator` (what gets written) and `MigrationsModelDiffer` (how absence is handled). Add a snapshot round-trip test in `test/EFCore.Design.Tests/Migrations/ModelSnapshotSqlServerTest.cs`.

## Testing

| Area | Location |
|------|----------|
| Convention unit tests | `test/EFCore.Tests/Metadata/Conventions/` |
| Metadata unit tests | `test/EFCore.Tests/Metadata/Internal/` |
| Model builder API tests | `test/EFCore.Specification.Tests/ModelBuilding/ModelBuilderTest*.cs` |
| Relationship discovery tests | `test/EFCore.Specification.Tests/ModelBuilding101*.cs` |
| Model validation tests | `test/EFCore.Tests/Infrastructure/ModelValidatorTest*.cs` |
| Compiled model tests | `test/EFCore.Specification.Tests/Scaffolding/CompiledModelTestBase.cs` |

## Validation

- Model builds without `InvalidOperationException` during finalization
- All new API is covered by tests
- Compiled model baselines update cleanly with `EF_TEST_REWRITE_BASELINES=1`
- `ToString()` on metadata objects shows concise contents without throwing exceptions
- No spurious migration is generated against a project with an existing snapshot