klod68/ef-core-standards

---

name: ef-core-standards description: "Use when designing EF Core entities, relationships, value objects, owned types, inheritance strategies, Fluent API configuration, migrations, schema changes, DbContext design, data access patterns, repository implementations, or querying strategies. Provides domain-specific rules layered on top of base architectural standards."

Skill: EF Core Standards

Identity

| Field | Value | |---|---| | Name | EF Core Standards | | Domain | Domain Modeling, ORM, Data Access, Persistence | | Level | Feature | | Tags | ef-core, entities, fluent-api, relationships, value-objects, migrations, dbcontext, repository, data-access |

When to Apply

Activate this skill when the task involves:

• Designing or refactoring EF Core entity classes
• Configuring relationships (one-to-many, many-to-many, one-to-one)
• Fluent API configuration via IEntityTypeConfiguration<T>
• Value objects and owned types (OwnsOne / OwnsMany)
• Inheritance mapping (TPH, TPT, TPC)
• Value conversions, shadow properties, or indexes
• DbContext or Dapper data modeling
• Creating, editing, or reviewing EF Core migrations
• Running dotnet ef commands or migration scripts
• DbContext registration, lifetime, or configuration
• Repository pattern implementation
• Query optimization (AsNoTracking, projections, includes)

Rules

These rules layer on top of base architectural standards. On conflict, these win.

<!-- SHARED:rules/ef-core.md -->

EF Core — Standards

Applicability: EF Core is a secondary persistence mechanism in this architecture. Use it for lite sites, demos, mocks, and rapid prototypes. For production enterprise applications, the primary persistence strategy is stored-procedure-first via Truenorth.Components.Persistence (see persistence.md). The rules below apply when EF Core is the chosen mechanism for a given project.

Apply these rules in addition to _base.md for projects using Entity Framework Core.

---

DbContext Design

• One DbContext per bounded context — never a god context for the entire application.
• DbContext is always registered as Scoped — never Singleton or Transient.
• Never expose DbContext outside the Infrastructure layer; wrap it behind a repository interface.
• DbSet<T> properties are internal — only the Infrastructure layer queries them directly.

Entity Design

• Entities are plain C# classes — no base class required unless sharing audit fields.
• Use private setters or init for properties that should not change after creation.
• Required navigation properties are non-nullable; optional ones are nullable (Order? Order).
• Entity constructors: parameterless private constructor for EF, public constructor with required parameters for application code.
• Never expose DbSet<T> or DbContext outside the data/infrastructure layer.

Entity Configuration

• All entity configurations live in dedicated IEntityTypeConfiguration<T> classes — never OnModelCreating inline.
• File naming: {Entity}Configuration.cs in an EntityConfigurations/ folder.
• Explicit table and column names on every entity — never rely on EF convention for production schema.
• All string columns must specify HasMaxLength — no unbounded nvarchar(max) without justification.
• Owned types and value objects use OwnsOne / OwnsMany, never a separate table unless required.

Fluent API Over Attributes

• Configure all mappings in IEntityTypeConfiguration<T> implementations — never use data annotations on entities.
• One configuration class per entity: OrderConfiguration : IEntityTypeConfiguration<Order>.
• Register configurations in OnModelCreating via modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly).
• Keep entities clean of persistence concerns — no [Table], [Column], [Key], [Required] attributes.

Relationships

• Always configure relationships explicitly in Fluent API — don't rely on EF conventions for non-trivial cases.
• Configure cascade delete behavior explicitly: OnDelete(DeleteBehavior.Restrict) is safer than the default Cascade.
• For many-to-many: prefer explicit join entity over implicit skip navigation when the join carries payload (e.g., OrderItem with Quantity).
• Avoid circular navigation properties — if Order → Customer → Orders, break the cycle by omitting one back-reference.

| Relationship | Configuration Pattern | |---|---| | One-to-Many | .HasMany(o => o.Items).WithOne(i => i.Order).HasForeignKey(i => i.OrderId) | | One-to-One | .HasOne(o => o.ShippingAddress).WithOne().HasForeignKey<ShippingAddress>(a => a.OrderId) | | Many-to-Many (simple) | .HasMany(s => s.Courses).WithMany(c => c.Students) | | Many-to-Many (with payload) | Explicit join entity with two one-to-many relationships |

Value Objects & Owned Types

• Model value objects as owned types using OwnsOne / OwnsMany.
• Owned types are stored in the same table by default — use ToTable() to split if needed.
• Value objects should be record types or override Equals/GetHashCode.
• Common value objects: Address, Money, DateRange, EmailAddress, PhoneNumber.

// Entity
public class Customer
{
    public int Id { get; private set; }
    public string Name { get; private set; } = string.Empty;
    public Address ShippingAddress { get; private set; } = null!;
}

// Value Object
public record Address(string Street, string City, string State, string ZipCode);

// Configuration
builder.OwnsOne(c => c.ShippingAddress, a =>
{
    a.Property(x => x.Street).HasMaxLength(200).IsRequired();
    a.Property(x => x.City).HasMaxLength(100).IsRequired();
    a.Property(x => x.State).HasMaxLength(2).IsRequired();
    a.Property(x => x.ZipCode).HasMaxLength(10).IsRequired();
});

Inheritance Strategies

| Strategy | When to Use | Trade-off | |---|---|---| | TPH (Table-Per-Hierarchy) | Few subtypes, similar columns, query across types | Nullable columns for subtype-specific fields | | TPT (Table-Per-Type) | Many subtypes, different columns, normalized schema | JOIN per query — slower reads | | TPC (Table-Per-Concrete) | Independent tables per type, no cross-type queries | No shared table — duplicate columns, fastest reads |

• Default to TPH unless you have a strong reason otherwise.
• Always configure the discriminator explicitly: .HasDiscriminator<string>("Type").HasValue<PremiumCustomer>("Premium").

Value Conversions

• Use HasConversion for enums, strongly-typed IDs, and custom types.
• Prefer HasConversion<string>() for enums stored in the database (readable, queryable).
• For strongly-typed IDs: HasConversion(id => id.Value, value => new OrderId(value)).
• Register global conversions for types used across multiple entities.

Shadow Properties & Backing Fields

• Use shadow properties for audit fields that don't belong on the domain entity: CreatedAt, UpdatedAt, CreatedBy.
• Configure in OnModelCreating: builder.Property<DateTime>("CreatedAt").
• Set shadow property values in SaveChangesAsync override.
• Use backing fields for encapsulated collections: private readonly List<OrderItem> _items = new();

Indexes

• Add indexes for every foreign key column (EF does not create them automatically on all providers).
• Add composite indexes for frequent multi-column query predicates.
• Use unique indexes for business keys: .HasIndex(u => u.Email).IsUnique().
• Name indexes explicitly: .HasIndex(o => o.Status).HasDatabaseName("IX_Orders_Status").

Migrations

• Migrations are code artifacts — review them like production code before merging.
• Never edit a migration that has been applied to any environment (dev, staging, prod).
• Migration names are descriptive: AddUserEmailIndex, not Migration_20240101.
• Down migrations must be implemented unless the change is intentionally irreversible (document why).
• Seed data goes in a dedicated IDataSeeder implementation — never in a migration.
• Schema changes and data changes are separate migrations.

Querying

• Use AsNoTracking() for all read-only queries — never track entities you will not modify.
• Never use Include() chains deeper than two levels in a single query; use projections instead.
• Project to DTOs with Select() at the query level — never load full entities then map in memory.
• Never use ToList() / ToArray() inside a loop — batch at the query layer.
• Raw SQL (FromSqlRaw, ExecuteSqlRaw) requires a comment explaining why LINQ was insufficient.

Repository Pattern

• Repositories accept and return domain interfaces or DTOs — never IQueryable<T> leaking out.
• A repository method maps to a single, well-named query — no generic Get(Expression<Func<T,bool>>).
• Repositories are never called directly from controllers or UI — only from Application layer handlers.

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Data annotations on entities ([Required], [MaxLength]) | Use Fluent API in IEntityTypeConfiguration<T> | | Exposing DbSet<T> as public outside data layer | Access via repository or query service | | Default cascade delete on all relationships | Explicitly set OnDelete(DeleteBehavior.Restrict) | | Lazy loading enabled globally | Use eager loading (.Include()) or explicit projections | | Anemic entities with only getters/setters | Add domain behavior methods; use private setters | | Navigation property cycles (A → B → A) | Remove one back-reference or use .Ignore() | | Missing indexes on foreign keys | Always add indexes for FK columns | | string columns without HasMaxLength | Always specify max length — prevents nvarchar(max) | | Enum stored as int without conversion | Use HasConversion<string>() for readability | | context.SaveChanges() called inside a loop | Batch and save once outside the loop | | Entity returned directly to API layer | Map to DTO before crossing layer boundary | | Include() for data only sometimes needed | Use separate query or projection | | Migration modifying previously applied migration | Create a new corrective migration | | DbContext injected into domain or application services | Inject repository interface instead |

---

See Also

• design-patterns.md — Approved GoF patterns: Factory, Repository, Decorator, Strategy, Specification
• cqrs.md — CQRS via MediatR, command/query separation, pipeline behaviors
• naming.md — Naming conventions for types, methods, properties, namespaces
• nullability.md — Nullable reference types, suppression discipline, collection rules
• persistence.md — Stored-procedure persistence layer, CrudPersistenceHelper patterns