EFCore.FluentIncludes 1.2.0

EFCore.FluentIncludes

Simplify Entity Framework Core Include/ThenInclude chains with clean, readable path-based syntax.

Why?

EF Core's eager loading syntax becomes hard to read with nested navigation properties:

// Hard to read - what's actually being loaded?
var order = await context.Orders
    .Include(o => o.Customer)
        .ThenInclude(c => c.Address)
    .Include(o => o.Customer)
        .ThenInclude(c => c.PaymentMethods)
    .Include(o => o.LineItems)
        .ThenInclude(li => li.Product)
            .ThenInclude(p => p.Category)
    .FirstOrDefaultAsync(o => o.Id == id);

With EFCore.FluentIncludes, the same query becomes:

// Clear and scannable
var order = await context.Orders
    .IncludePaths(
        o => o.Customer.To().Address,
        o => o.Customer.To().PaymentMethods,
        o => o.LineItems.Each().Product.To().Category)
    .FirstOrDefaultAsync(o => o.Id == id);

Installation

dotnet add package EFCore.FluentIncludes

Requirements: EF Core 8.0+, .NET 8.0+

using EFCore.FluentIncludes;

Quick Reference

Simple rule: Use To() for "has one", use Each() for "has many".

Usage

Basic Paths

// Single property
.IncludePaths(o => o.Customer)

// Chain with To() for references
.IncludePaths(o => o.Customer.To().Address)

// Chain with Each() for collections
.IncludePaths(o => o.LineItems.Each().Product)

// Combine both
.IncludePaths(o => o.LineItems.Each().Product.To().Category)

// Multiple paths at once
.IncludePaths(
    o => o.Customer.To().Address,
    o => o.LineItems.Each().Product.To().Category,
    o => o.Payments.Each().PaymentMethod)

Filtering and Ordering Collections

Filter and order collections during eager loading:

// Filter: only active items
.IncludePaths(o => o.LineItems.Where(li => li.IsActive).Each().Product)

// Order: by display order
.IncludePaths(o => o.LineItems.OrderBy(li => li.DisplayOrder).Each().Product)

// Combine: filter then order
.IncludePaths(o => o.LineItems
    .Where(li => li.IsActive)
    .OrderBy(li => li.DisplayOrder)
    .Each()
    .Product)

// Multiple sort keys
.IncludePaths(o => o.LineItems
    .OrderBy(li => li.Category)
    .ThenByDescending(li => li.DisplayOrder)
    .Each())

Alternative: The ! Operator

You can use ! instead of To() for nullable navigation:

.IncludePaths(o => o.Customer!.Address)  // Same as o => o.Customer.To().Address

Both are safe - the lambda is never executed. To() is more readable and consistent with Each().

Advanced Features

Conditional Includes

Include paths based on runtime conditions:

var order = await context.Orders
    .IncludePaths(o => o.Customer)
    .IncludePathsIf(includeProducts,
        o => o.LineItems.Each().Product.To().Category)
    .IncludePathsIf(includePayments,
        o => o.Payments.Each().PaymentMethod)
    .FirstOrDefaultAsync(o => o.Id == id);

Use cases: feature flags, user permissions, API query parameters.

Grouping Paths with IncludeFrom

When multiple paths share the same base, avoid repetition:

// Instead of repeating the filter:
.IncludePaths(
    o => o.LineItems.Where(li => li.IsActive).Each().Product,
    o => o.LineItems.Where(li => li.IsActive).Each().Discounts)

// Group them:
.IncludeFrom(
    o => o.LineItems.Where(li => li.IsActive).Each(),
    li => li.Product,
    li => li.Discounts.Each())

Also works with IncludeFromIf() for conditional grouped includes.

Reusable Specifications

Create reusable include patterns:

public class OrderDetailSpec : IncludeSpec<Order>
{
    public OrderDetailSpec()
    {
        Include(o => o.Customer.To().Address);
        Include(o => o.LineItems.Each().Product.To().Category);
    }
}

// Use it
var orders = await context.Orders
    .WithSpec<Order, OrderDetailSpec>()
    .ToListAsync();

Compose specs:

public class OrderFullSpec : IncludeSpec<Order>
{
    public OrderFullSpec()
    {
        IncludeFrom<OrderDetailSpec>();  // Include everything from another spec
        Include(o => o.Payments.Each());
    }
}

Multiple specs: .WithSpecs<Order, OrderDetailSpec, OrderAuditSpec>()

Conditional: .WithSpecIf<Order, OrderDetailSpec>(condition)

API Reference

Before & After

Performance

EFCore.FluentIncludes generates identical SQL to standard EF Core includes. Expression parsing adds microseconds of overhead - negligible compared to database query time.

On .NET 10+, source generation eliminates parsing overhead entirely using C# interceptors.

Works with AsSplitQuery() and AsSingleQuery().

Compile-Time Analysis

The included Roslyn analyzer catches common errors at compile time:

• FI0001 - Property does not exist
• FI0002 - Missing Each() on collection
• FI0003 - Each() on non-collection
• FI0007 - Nullable navigation without To() or !

Auto-fixes are available for common issues.

Sample Project

See samples/EFCore.FluentIncludes.Sample for a complete ASP.NET Core example.

dotnet run --project samples/EFCore.FluentIncludes.Sample

License

Apache 2.0 - See LICENSE for details.