Entity Classes and Conventions

Analogy categoryAnalogies

What Is an Entity Class?

In EF Core, an entity class is a plain C# class (a POCO) whose instances represent rows in a database table. You expose a DbSet<TEntity> property on your DbContext subclass for each entity type you want EF Core to track and query, and EF Core uses reflection over your model to build an in-memory model describing tables, columns, and keys.

🏏

Cricket analogy: A Product entity class is like a player's scorecard template used by every match official - the same shape (runs, balls faced, dismissals) is filled in fresh for each player like Virat Kohli, and EF Core reads that template via DbSet<Product> the way a scorer reads the scorecard format.

Convention-Based Discovery

EF Core's model-building conventions automatically include any entity type reachable from a DbSet<TEntity> property through navigation properties, even if that type has no explicit DbSet of its own. Property names map to column names, CLR types map to SQL types (e.g., int to int, string to nvarchar(max) by default), and [NotMapped] or Ignore() excludes members you don't want persisted.

🏏

Cricket analogy: Just as a franchise like Mumbai Indians automatically includes support staff (physios, analysts) in its squad list because they're reachable from the main roster, EF Core pulls in related entity types reachable via navigation properties even without their own DbSet.

Primary Key Conventions

By convention, EF Core treats a property named Id or <EntityName>Id as the primary key and configures it as an identity column for numeric types, generating values automatically on insert. For composite keys, conventions alone are insufficient - you must use the [Key] and [Column(Order = n)] data annotations or the Fluent API's HasKey(e => new { e.Prop1, e.Prop2 }) to declare a composite key explicitly.

🏏

Cricket analogy: A player's unique BCCI registration number is like an auto-generated identity Id - assigned automatically once, whereas a composite key of match number plus innings number needs both fields explicitly named, like HasKey(e => new { e.MatchId, e.InningsNo }).

csharp

public class Product
{
    public int Id { get; set; }              // convention: primary key, identity
    public string Name { get; set; } = null!; // maps to nvarchar(max) by default
    public decimal Price { get; set; }
    public int CategoryId { get; set; }        // convention: FK to Category
    public Category Category { get; set; } = null!; // navigation property
}

public class AppDbContext : DbContext
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Category> Categories => Set<Category>();
}

Conventions get you 80% of the way, but they're not always correct for production schemas - string lengths, required-ness, and delete behavior often need explicit configuration via Data Annotations or the Fluent API, covered in the next topic.

Shadow Properties and Field-Backed Properties

A shadow property is a value EF Core tracks in its model and maps to a column, but which doesn't exist as a CLR property on your class - common for foreign keys you don't want cluttering your domain model, configured via modelBuilder.Entity<Order>().Property<DateTime>("LastModified"). Backing fields let you keep a private field (e.g., _email) and expose only a read-only or validated public property, while EF Core still reads and writes the private field directly via reflection during materialization.

🏏

Cricket analogy: A shadow property is like a scorer's internal tally of no-balls that never appears on the printed scorecard but still affects the final total, just as EF Core tracks LastModified internally without it existing on your Order class.

Relying solely on conventions can silently create nvarchar(max) columns for every string property (hurting index performance) and cascade-delete foreign keys by default for required relationships - always review the generated migration before applying it to production.

An entity class is a POCO exposed via DbSet<TEntity> on your DbContext.
EF Core discovers entity types by convention, including types reachable only through navigation properties.
A property named Id or <TypeName>Id is conventionally treated as the primary key.
Composite keys require explicit configuration via [Key]/[Column(Order=)] or Fluent API HasKey.
Shadow properties are tracked by EF Core without existing as CLR properties on the class.
Backing fields let EF Core read/write a private field directly while your public API stays controlled.
Always inspect generated migrations - conventions can produce oversized columns or unwanted cascade deletes.