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.
Foreign Keys and Navigation Properties
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.
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.
Practice what you learned
1. On which side of a one-to-many relationship does the foreign key property live?
2. What determines whether a one-to-many relationship is required or optional?
3. What is the default delete behavior for a REQUIRED one-to-many relationship?
4. When must you use Fluent API instead of relying on convention for a one-to-many relationship?
Was this page helpful?
You May Also Like
Entity Classes and Conventions
Learn how EF Core discovers and maps plain C# classes to database tables using convention-based modeling, including primary keys, shadow properties, and backing fields.
Many-to-Many Relationships
Learn how EF Core models many-to-many relationships with skip navigations, implicit join tables, and explicit join entities that carry payload data.
Data Annotations vs Fluent API
Compare EF Core's two configuration approaches - inline Data Annotations and the more powerful Fluent API - and learn when each is the right tool.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics