One-to-Many Relationships

Analogy categoryAnalogies

Modeling a One-to-Many Relationship

A one-to-many relationship - one Category having many Products - is EF Core's most common relationship shape. You model it with a collection navigation property (ICollection<Product> Products) on the 'one' side and a reference navigation property (Category Category) plus a foreign key property (int CategoryId) on the 'many' side; EF Core's conventions detect this pattern automatically without any Fluent API needed.

🏏

Cricket analogy: A one-to-many relationship is like one IPL franchise such as Chennai Super Kings having many contracted players - the franchise holds a collection navigation to its squad, while each player holds a single foreign key back to their one franchise.

EF Core's convention scans for a property on the dependent (Product) matching <PrincipalName>Id (i.e., CategoryId) or <NavigationPropertyName>Id, and treats it as the foreign key backing the relationship. If both a collection navigation on Category and a reference navigation plus FK property on Product are present, EF Core wires up a fully bidirectional one-to-many without any explicit configuration.

🏏

Cricket analogy: EF Core scanning for CategoryId on Product is like a scorer automatically matching a batsman's entry to their team by cross-referencing the player's registered team code, without anyone manually linking each record.

Required vs Optional Relationships and Delete Behavior

Whether a relationship is required or optional depends on the nullability of the FK property: int CategoryId (non-nullable) makes the relationship required, while int? CategoryId makes it optional. Required relationships default to DeleteBehavior.Cascade (deleting a Category deletes all its Products), while optional relationships default to DeleteBehavior.ClientSetNull (the FK is set to null in memory when the principal is deleted).

🏏

Cricket analogy: A required relationship is like a bowler who must be assigned to a specific team before playing - if the team folds, the bowler's contract is voided too, similar to cascade delete removing dependents when the principal disappears.

You don't need navigation properties on both sides for EF Core to build a relationship - a unidirectional one-to-many (collection only, or FK only) works fine and is often cleaner when the 'many' side never needs to navigate back to its parent.

Configuring Explicitly with Fluent API

When conventions can't infer the relationship - for example, multiple FK properties on Product pointing to Category (like PrimaryCategoryId and AlternateCategoryId) - you must configure it explicitly with modelBuilder.Entity<Product>().HasOne(p => p.Category).WithMany(c => c.Products).HasForeignKey(p => p.PrimaryCategoryId).OnDelete(DeleteBehavior.Restrict), which also lets you override the default delete behavior.

🏏

Cricket analogy: Explicit Fluent API configuration is like a franchise needing to clarify contractually which of two team affiliations (IPL squad vs. national squad) governs a player's primary allegiance, since the ambiguity can't be resolved by convention alone.

csharp

public class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = null!;
    public ICollection<Product> Products { get; set; } = new List<Product>();
}

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = null!;
    public int CategoryId { get; set; }        // required FK
    public Category Category { get; set; } = null!;
}

// Explicit configuration when convention can't infer the relationship
modelBuilder.Entity<Product>()
    .HasOne(p => p.Category)
    .WithMany(c => c.Products)
    .HasForeignKey(p => p.CategoryId)
    .OnDelete(DeleteBehavior.Restrict);

The default DeleteBehavior.Cascade on required relationships can silently wipe out large amounts of related data in production; explicitly set .OnDelete(DeleteBehavior.Restrict) for relationships where accidental cascading deletes would be costly, and handle the cleanup in application code instead.

One-to-many uses a collection navigation on the principal and a reference navigation plus FK on the dependent.
EF Core's convention detects <PrincipalName>Id as the foreign key property automatically.
A non-nullable FK makes the relationship required; a nullable FK makes it optional.
Required relationships default to DeleteBehavior.Cascade; optional ones default to ClientSetNull.
Multiple possible FK paths between two types require explicit Fluent API configuration.
HasOne().WithMany().HasForeignKey() is the Fluent API pattern for explicit one-to-many setup.