Clarification Request: AutoInclude Behavior for Nested Navigation Properties in EF Core

[simon-schweizer]

Question

Hello EF Core Team,

I have a question regarding the behavior of AutoInclude in Entity Framework Core that I could not find clearly documented.

Specifically:
• When configuring AutoInclude via the ModelBuilder for an entity, it works fine when querying directly from the DbSet of that entity.
• However, when that entity is a child (nested inside another entity), AutoInclude does not seem to automatically load the nested navigation properties unless the query starts from the DbSet of the child entity itself.

Could you clarify:
• Is this the intended behavior for AutoInclude?
• Is there any way to configure AutoInclude to work similarly to Include() + ThenInclude() automatically for nested navigations?
• Or is explicit Include/ThenInclude chaining still required when navigating through multiple levels?

Some official documentation or deeper guidance around this behavior would be very helpful, especially when designing domain models with aggregates and nested entities.

Thank you for your time and for your work on EF Core!

Your code

Stack traces

Verbose output

EF Core version

9.0.4

Database provider

Microsoft.EntityFrameworkCore.SqlServer

Target framework

.NET 9.0

Operating system

macOS

IDE

Rider 2025.1

[cincuranet]

Can you clarify what you mean by configuring AutoInclude via the ModelBuilder for an entity? Because auto-include is configured for navigation, not for entity.

[simon-schweizer]

Sure! I am talking about this part of your documentation:

https://learn.microsoft.com/en-us/ef/core/querying/related-data/eager
"Model configuration for auto-including navigations"

public class Order
{
    public int Id { get; set; }
    public List<OrderItem> Items { get; set; }
}

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

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
}

// This is how i would include whole chain in each query

var ordersWithProducts = await context.Orders
    .Include(o => o.Items)
    .ThenInclude(oi => oi.Product)
    .ToListAsync();

// Question: Is this the correct way to configure the same behaviour via modelbuilder??

modelBuilder.Entity<Order>()
    .Navigation(o => o.Items)
    .AutoInclude();
modelBuilder.Entity<OrderItem>()
    .Navigation(oi => oi.Product)
    .AutoInclude();

[cincuranet]

Yes, these two are functionally equivalent. You can see it yourself, using this piece of code for example.

using Microsoft.EntityFrameworkCore;

using var db = new MyContext();
var query1 = db.Set<Order>()
    .IgnoreAutoIncludes()
    .Include(o => o.Items)
    .ThenInclude(oi => oi.Product)
    .ToQueryString();
Console.WriteLine(query1);
Console.WriteLine();
var query2 = db.Set<Order>()
    .ToQueryString();
Console.WriteLine(query2);
Console.WriteLine();

class MyContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlite();
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>()
            .Navigation(o => o.Items)
            .AutoInclude();
        modelBuilder.Entity<OrderItem>()
            .Navigation(oi => oi.Product)
            .AutoInclude();
    }
}
public class Order
{
    public int Id { get; set; }
    public List<OrderItem> Items { get; set; }
}
public class OrderItem
{
    public int Id { get; set; }
    public Product Product { get; set; }
}
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
}

[simon-schweizer]

Great! Thanks for that answer! :-)