skip to content

In EF Core 10, what does Navigation(t => t.Album).AutoInclude() configure in OnModelCreating, and how does a single query opt out of it?

level: middleimportance: nice to knowfreq 20%

answer

  1. eager loading declared in the model
  2. modelBuilder.Entity<Track>().Navigation(...)
  3. applies wherever the entity appears in a result
  4. IgnoreAutoIncludes() on the query
  5. owned navigations are always included

basics

~20 s

AutoInclude marks a navigation to load as if every query returning that entity had included it, however the entity reached the result. A query opts out with IgnoreAutoIncludes(), which drops all configured auto-includes for that query; owned navigations still load.

solid answer

~40 s

`modelBuilder.Entity<Track>().Navigation(t => t.Album).AutoInclude()` is model-level eager loading: any query whose results contain `Track` entities loads their `Album` too - whether the tracks are the root, came in through `Include(p => p.Tracks)`, or arrived another way. `db.Tracks.IgnoreAutoIncludes()` switches off every auto-include for that one query; there is no per-navigation opt-out at query level, so `AutoInclude(false)` in the model is how you remove one. Navigations to owned types are auto-included by convention and `IgnoreAutoIncludes()` does not stop them. The cost is visibility: the load shape no longer appears in the query, so a list endpoint can drag in data nobody asked for, and two auto-includes that point at each other make queries throw a cycle error.

code

csharp · 9 lines
csharp
// Model: every Track result brings its Album
modelBuilder.Entity<Track>().Navigation(t => t.Album).AutoInclude();

// A search endpoint that needs titles only: skip all auto-includes
var titles = await db.Tracks
    .IgnoreAutoIncludes()
    .Where(t => t.Title.StartsWith(prefix))
    .AsNoTracking()
    .ToListAsync();

go deeper

for a junior

Recall that AutoInclude in OnModelCreating loads a navigation in every query returning the entity, and IgnoreAutoIncludes() turns it off for one query.

for a middle

Explain where it applies - roots, included entities, derived types - why projections are unaffected, and why owned navigations ignore the opt-out.

for a senior

Judge where AutoInclude pays off, spot the hidden joins it adds to list endpoints, and resolve cycle errors between two auto-included navigations.

for a principal

Decide as a team whether model-level load shape is allowed at all, and how to keep its cost visible as more endpoints query the same entities.

## Model-level eager loading **Eager loading** normally lives in each query: `Include` names what to fetch with the root. **AutoInclude** moves that decision into the **model** - the mapping EF Core builds in `OnModelCreating` - so it applies to every query without being written again. The EF Core docs describe it as having the same effect as specifying `Include` for the navigation in every query where the entity type is returned. ## Configuring it 1. In `OnModelCreating`, select the entity: `modelBuilder.Entity<Track>()`. 2. Select the navigation with `.Navigation(t => t.Album)`, which returns a `NavigationBuilder`. 3. Call `.AutoInclude()`; the parameter `autoInclude` defaults to `true`. 4. To undo a convention or an earlier call, use `.AutoInclude(false)`. ```csharp protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder.Entity<Track>() .Navigation(t => t.Album) .AutoInclude(); } ``` The relationship itself is configured as usual; `Navigation(...)` only adds settings to an existing navigation. ## Where it applies - **Root queries:** `db.Tracks.ToListAsync()` loads each track's album. - **Included entities:** `db.Playlists.Include(p => p.Tracks)` loads the tracks and, because each one is a `Track` in the result, their albums. - **Derived types:** auto-includes configured on a derived entity type apply to its instances wherever they appear. - **Not in projections:** a `Select` into a DTO returns no `Track` entity, so nothing is auto-included; the projection reads what it names. ## Opting out | Tool | Scope | Effect | |---|---|---| | `IgnoreAutoIncludes()` | one query | skips every auto-include configured by the user for that query | | `AutoInclude(false)` | the model | that navigation is no longer auto-included anywhere | | `Select` projection | one query | no entities returned, so there is nothing to auto-include | | owned navigations | - | always included; `IgnoreAutoIncludes()` does not affect them | There is no query-level switch for a single navigation: `IgnoreAutoIncludes()` is all or nothing for that query, and you then add back what you need with explicit `Include` calls. ## Costs and traps - **Hidden load shape.** A reviewer reading `db.Tracks.Where(...)` cannot see that albums come along. On a list endpoint that only needs titles, the auto-include reads a joined table for nothing. - **Collections multiply rows.** Auto-including a collection navigation turns every query of that entity into a join that repeats the parent per child row; keep AutoInclude for small references. - **Cycles throw.** If `Track.Album` and `Album.Tracks` are both auto-included, EF Core detects the cycle when such a query runs and throws: "Cycle detected while auto-including navigations... either don't configure at least one navigation in the cycle as auto included in 'OnModelCreating' or call 'IgnoreAutoInclude' method on the query." (The message says `IgnoreAutoInclude`; the method is `IgnoreAutoIncludes()`.) - **Surprises in tests and tools.** Every query in every handler pays for the join, including ones written long after the configuration was added. ## A worked example In the music-streaming admin, every screen that shows a track also shows its album title, so `Track.Album` is auto-included. The playlist page writes `db.Playlists.Include(p => p.Tracks)` and still gets albums, because every `Track` in the result is covered. The track-search box, which needs titles only, writes `db.Tracks.IgnoreAutoIncludes()` and avoids the join. Six months later someone adds `Album.Tracks` as an auto-include for an album page - and every track query starts throwing the cycle error, which is the moment to move that load back into the album page's own query. ## When it is a reasonable choice AutoInclude fits a small, almost always needed reference - a track's album for display, a value-like lookup the entity is meaningless without. For anything larger, or anything needed only on some pages, per-query `Include` or a projection keeps the cost where it is visible. A useful interview line: AutoInclude trades explicitness for convenience, so use it only where nearly every query wants the navigation and opting out with `IgnoreAutoIncludes()` is rare.

  • What happens if Track.Album and Album.Tracks are both configured with AutoInclude?
    Queries returning either type hit a cycle and EF Core throws an `InvalidOperationException` starting "Cycle detected while auto-including navigations". Remove `AutoInclude` from at least one side, or call `IgnoreAutoIncludes()` on the affected queries. Usually only the small reference side deserves it.
  • Can a query keep one auto-included navigation and drop another?
    Not directly. `IgnoreAutoIncludes()` drops every user-configured auto-include for the query; you then add back the ones you want with explicit `Include` calls. To drop a navigation everywhere, change the model with `AutoInclude(false)`.

  • AutoInclude only affects queries that start from that entity's DbSet.
  • IgnoreAutoIncludes() also stops owned navigations from loading.
  • IgnoreQueryFilters() is how a query skips auto-included navigations.
  • Auto-included navigations still load when the query projects into a DTO.
  • AutoInclude is a good default for every collection navigation.