Trellis.EntityFrameworkCore 3.0.0-alpha.505

Trellis.EntityFrameworkCore

EF Core conventions and helpers for Trellis value objects, Maybe<T>, and Result-based persistence.

Installation

dotnet add package Trellis.EntityFrameworkCore

Quick Example

using Microsoft.EntityFrameworkCore;
using Trellis;
using Trellis.EntityFrameworkCore;

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder) =>
    configurationBuilder.ApplyTrellisConventions(typeof(AppDbContext).Assembly);

// Reflection-free alternative — generated at compile time, no assembly scan:
//   configurationBuilder.ApplyTrellisConventionsFor<AppDbContext>();

Maybe<Customer> customer = await dbContext.Customers.FirstOrDefaultMaybeAsync(cancellationToken);
Result<int> saved = await dbContext.SaveChangesResultAsync(cancellationToken);

Key Features

• Commit ownership: EfUnitOfWork.BeginScope() returns IUnitOfWorkScope; IsOwner is true only for the outer scope. Nested commands defer persistence and event dispatch until the owning command succeeds; DTO/Unit outer responses retain nested aggregate events. Automatic event dispatch under a manually owned outer scope is rejected; use explicit post-commit dispatch instead.
• Apply Trellis value converters and owned-type conventions with one registration point.
• Owned-collection (OwnsMany) children that declare their own primary key are treated as domain-assigned: the key is marked ValueGenerated.Never, so an application-supplied Guid/long/int key persists on every provider (no SQL Server IDENTITY 544 error, no spurious 409 when adding a child to an already-loaded parent). Opt back into store generation with an explicit ValueGeneratedOnAdd() or [DatabaseGenerated(DatabaseGeneratedOption.Identity)].
• Query Maybe<T> naturally instead of dropping to storage-specific null handling.
• Return Result<int> or Result from save operations instead of throwing on expected failures.
• Idempotent inserts on a unique constraint via db.TryInsertUniqueAsync(entity, ct) — duplicate-key violations surface as a failed Result<TEntity> carrying an Error.Conflict with reason code "duplicate.key" and the provider-extracted ConstraintName / ConstraintTableName telemetry fields, so worker outboxes and "save unless exists" deduplication never throw on redelivery.
• Typed cursor pagination via IQueryable<T>.ToPageAsync(request, seek, …) — SeekDefinition keeps single/composite, ascending/descending ordering and seek predicates together; malformed client state returns Error.InvalidInput.
• RepositoryBase<TAggregate, TId> — staging-only base class (Add/Remove/Query/Exists/Count).
• IUnitOfWork / EfUnitOfWork<TContext> — single commit boundary for staged changes.
• TransactionalCommandBehavior — Mediator pipeline behavior that auto-commits after successful command handlers (requires Mediator pipeline registration). Also commits on Result.FailAfterCommit<T>(error) outcomes so persist-on-failure handlers (e.g., a worker recording a permanent-failure transition) can stage state alongside the failed result.

Typed predicates over optional values

var overdue = await dbContext.Orders
    .WhereHasValue(o => o.SubmittedAt, value => value < cutoff)
    .ToListAsync(cancellationToken);

Breaking change: WhereLessThan, WhereLessThanOrEqual, WhereGreaterThan, and WhereGreaterThanOrEqual are replaced by WhereHasValue(selector, predicate). Move <, <=, >, or >= into the value lambda. The overload accepts an Expression<Func<TInner, bool>>, including reusable expression variables, not a compiled delegate. Absent values are always excluded, even for a constant-true predicate. Presence-only WhereHasValue(selector), equality, and ordering helpers are unchanged.

C# checks the predicate's operators; the configured provider must translate them. String/GUID ordering follows provider semantics, and unsupported translations (such as DateTimeOffset relational comparisons on SQLite) throw without a client-side fallback. The helper targets storage directly; scalar value-object .Value access still requires AddTrellisInterceptors(). For shared domain specifications, continue using Maybe<T>.HasValueWhere with an inline lambda and AddTrellisInterceptors() for EF execution.

Typed seek pagination

var seek = SeekDefinition.Descending<Order, DateTimeOffset>(o => o.CreatedAt)
    .ThenAscending(o => o.Id.Value);

Result<Page<Order>> page = await PageRequest.TryCreate(cursor, limit)
    .BindAsync(request => authorizedOrders.AsNoTracking()
        .ToPageAsync(request, seek, cancellationToken: ct));

Supply an authorized, pre-filtered IQueryable<Order>. PageRequest distinguishes missing input from invalid empty cursors/non-positive limits; above-cap limits clamp by default (PageSizeLimitPolicy.Reject opts into rejection). The helper decodes typed state, seeks before Take(Applied + 1), and assembles a forward page. Boundary values are projected with the database query using the same key expressions, not recomputed in C# after materialization. Provider-translated functions are supported when the provider translates the complete query.

End with a stable unique key. Null keys are unsupported; verify your provider's translation and comparison/collation semantics. .Id.Value projection requires AddTrellisInterceptors(). There is no client-side fallback or snapshot guarantee, and descending traversal is not previous-page support. Cancellation and provider failures propagate rather than becoming malformed-cursor errors.

Use explicit key codecs or seek.WithCodec(...) for custom/context-bound/protected state. Built-ins are versioned and unsigned; old unversioned tokens are rejected. The single-key ascending ToPageAsync(pageSize, cursor, keySelector, …) convenience remains. For non-translatable computed ordering, use an explicitly bounded application algorithm with Core codecs and PageBuilder instead.

Documentation

• Full documentation
• API Reference
• Pagination guide

Part of Trellis

This package is part of the Trellis framework.