Model Building

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.