Relationships

A relational database connects rows with foreign keys: a column in one table holding the key of a row in another. C# connects objects with references. A relationship in EF Core is the mapping between those two ideas.

Three terms are used constantly from here on. The principal is the entity that exists independently — a Department. The dependent is the entity that holds the foreign key and cannot stand alone — an Employee. A navigation property is a reference or collection that lets you move from one to the other in code.

Three shapes cover almost everything: one-to-many, many-to-many and one-to-one. One-to-many is by far the most common, and the other two are easier once you have seen it.

public class Department
{
    public int Id { get; set; }
    public string Name { get; set; } = "";

    // Collection navigation: the many side
    public List<Employee> Employees { get; set; } = new();
}

public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; } = "";

    // Foreign key, and the reference navigation it backs
    public int DepartmentId { get; set; }
    public Department Department { get; set; } = null!;
}

// Configuration — EF Core would infer this, but stating it is clearer
builder.HasOne(e => e.Department)
    .WithMany(d => d.Employees)
    .HasForeignKey(e => e.DepartmentId)
    .OnDelete(DeleteBehavior.Restrict);

• Employee holds DepartmentId, so Employee is the dependent. Only one table gains a column, which is what makes this shape cheap.
• Exposing the foreign key as a property is worth doing. You can set an employee's department with an integer you already have, with no need to load the Department first — one fewer round trip.
• The two navigations are optional in principle: EF Core needs only one side to understand the relationship. Include the side you will actually navigate, and leave out a collection you never read, because every navigation is another route by which code can accidentally load data.
• null! on Department tells the compiler the reference will be set, without claiming it is set at construction. EF Core assigns it when the relationship is loaded; until then it is genuinely null, which the exclamation mark hides. It is a compiler concession, not a guarantee.
• OnDelete is spelled out here to make the delete rule a decision rather than a default. The section below explains the options.

public class Order
{
    public int Id { get; set; }
    public int CustomerId { get; set; }
    public DateTime PlacedOn { get; set; }

    public List<OrderItem> Items { get; set; } = new();
}

public class OrderItem
{
    public int Id { get; set; }

    public int OrderId { get; set; }
    public Order Order { get; set; } = null!;

    public int ProductId { get; set; }
    public Product Product { get; set; } = null!;

    // The reason this join is an entity of its own
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }
}

• This is a many-to-many relationship expressed as two one-to-many relationships meeting at OrderItem. Order has many items; Product has many items; each item points at one of each.
• OrderItem carries Quantity and UnitPrice, so it has to be a class you can see and query. Data that belongs to the pairing rather than to either side is what makes a join entity necessary.
• UnitPrice is deliberately duplicated from Product. An order must record the price charged on the day. If you read the price through Product at display time, last year's invoices change whenever someone updates a price.
• When a join genuinely carries nothing extra, EF Core can create and manage the join table for you: give each side a collection navigation to the other and configure it with HasMany and WithMany. You gain simpler code and lose the ability to query the join directly or add a column to it later.
• Start with the explicit join entity when there is any chance the pairing will need its own data. Adding a payload to an EF-managed join table later means introducing the entity anyway, plus a migration.

public class EmployeeContract
{
    // The primary key is also the foreign key
    public int EmployeeId { get; set; }
    public Employee Employee { get; set; } = null!;

    public DateOnly StartDate { get; set; }
    public int NoticePeriodDays { get; set; }
    public decimal AnnualSalary { get; set; }
}

// On Employee
public EmployeeContract? Contract { get; set; }

// In EmployeeContractConfiguration.Configure
builder.HasKey(c => c.EmployeeId);

builder.HasOne(c => c.Employee)
    .WithOne(e => e.Contract)
    .HasForeignKey<EmployeeContract>(c => c.EmployeeId)
    .OnDelete(DeleteBehavior.Cascade);

• One-to-one is the shape EF Core cannot infer on its own. Both sides have a single reference, so nothing in the classes says which one holds the foreign key — HasForeignKey with an explicit type argument tells it.
• Using EmployeeId as both primary key and foreign key is what makes the relationship one-to-one at the database level. A unique key cannot repeat, so no employee can have two contracts.
• The nullable Contract on Employee makes the relationship optional: an employee may exist without a contract record. Remove the question mark and EF Core still cannot require the row, because there is nothing to enforce it on the Employee side. Required one-to-one is genuinely awkward, which is one reason this shape is less common than it first appears.
• Cascade is the right delete behaviour here, unlike the earlier example. A contract has no meaning without its employee, so it should not outlive one.