Eternet.Crud.Relational 3.1.9

Eternet.Crud.Relational

Relational CRUD runtime, generated relational bridge conventions, bulk primitives, and relational outbox support for Eternet.Mediator.

Installation

dotnet add package Eternet.Crud.Relational

Current Package Shape

As of April 2026, the supported authoring model is:

• request-first relational CRUD, where the public contract stays on the contracts/public handler and the internal relational request becomes the semantic source of truth
• aggregate-root semantics for single-entity create, update, delete, and upsert lanes
• first-class homogeneous bulk create, bulk delete, and bulk update lanes
• generated relational bridges that bind deterministic request/runtime inputs and publish reserved downstream outputs
• explicit IDomainEvent plus relational outbox projection as the default outbox model
• legacy CreateEntityCommand<Response> / UpdateEntityCommand<Response> / DeleteEntityCommand<Response> and [HandlerForEntity<TEntity>] only as compatibility paths

The modern relational lane is centered on a single explicit relational request type:

public sealed partial class UpdateJournalEntryHandler :
    UpdateJournalEntry,
    IRelationalUpdateImplementation<UpdateJournalEntryRelational.Request>
{
    public override Response Handle(Request request) => request.StepsResults!.Response!;
}

public static partial class UpdateJournalEntryRelational
{
    public sealed partial record Request
        : RelationalUpdateEntityCommand<AccountingContext, JournalEntry, int>
    {
        public override int GetKey() => Id;
    }
}

For update work, the internal relational request above is the supported replacement for authoring new features on UpdateEntityCommand<Response>.

Recent Changes

The last two weeks materially changed both Eternet.Crud.Relational and Eternet.Crud.Relational.Generator:

• bulk delete, bulk create, and bulk update are now first-class relational lanes instead of bespoke custom-write patterns
• relational CRUD moved to the request-first API where IRelational*Implementation<TRelationalRequest> declares one explicit internal relational request type
• create/update/delete/upsert semantics are documented and enforced at the aggregate-root boundary
• generated bridge steps now return StepResult<T> and preserve compatible custom relational result types for single-entity lanes
• GeneratedPipelineRuntime is no longer the public runtime anchor for generated bridge glue; generated code now stays behind assembly-local helpers backed by GeneratedBindingRuntime
• relational outbox authoring now defaults to explicit IDomainEvent emission plus registered projector translation; the old legacy outbox compatibility APIs were removed
• generated bridge policy is emitted as assembly metadata so test/runtime discovery can reason about handlers across files and referenced assemblies
• nested relational handlers now get deterministic unique bridge artifact names
• [RelationalEntityBinding("Alias")] can publish an additional downstream alias for the aggregate entity while keeping the default Entity output
• scalar binding in generated bridges was tightened so request members bind deterministically by member name and type

Preferred Authoring Model

For new relational features:

1. Keep the public request/contract in the contracts or public server layer and express API semantics with IEndpointCreate, IEndpointUpdate, IEndpointDelete, IEndpointUpsert, or the relevant query contract.
2. Keep the public handler on that contract and implement one of the IRelationalCreate/Update/Delete/UpsertImplementation<TRelationalRequest> interfaces.
3. Declare an app-owned internal relational request that inherits the appropriate relational request base: RelationalCreateEntityCommand<...>, RelationalUpdateEntityCommand<...>, RelationalDeleteEntityCommand<...>, or RelationalUpsertEntityCommand<...>.
4. Let Eternet.Crud.Relational.Generator augment that request, generate the bridge, and publish the reserved downstream outputs.
5. Keep domain materialization/mutation and IDomainEvent emission in the app-owned relational business handler or pipeline steps.

For homogeneous set writes, keep the same request-first model and switch the internal relational request to one of the bulk bases:

• RelationalBulkCreateCommand<...>
• RelationalBulkDeleteCommand<...>
• RelationalBulkUpdateCommand<...>

Compatibility And Roadmap

Legacy relational surfaces still compile, but they are no longer the design target for new code:

• [HandlerForEntity<TEntity>] remains compatibility-only
• CreateEntityCommand<Response>, UpdateEntityCommand<Response>, and DeleteEntityCommand<Response> remain compatibility-only
• ConfigureGeneratedRelationalCommand(...) remains deprecated migration scaffolding
• legacy *RelationalHooks are already unsupported
• Eternet.Crud.Relational.Generator discovers the relational key path from deterministic EF metadata and explicit relational contracts instead of naming heuristics (Id, <EntityName>Id, [Key]) or IIntIdentity/IStringIdentity; the remaining cleanup is the runtime/public-surface identity coupling

The relational identity decoupling work is tracked in docs/plans/relational/identity-decoupling-plan.md:

• remove nondeterministic key and lookup heuristics from the relational lane (done)
• stop treating IIntIdentity and IStringIdentity as part of the modern relational authoring model
• decouple the modern relational lane from IIdentity
• obsolete legacy relational authoring entry points and back that stance with analyzer diagnostics and migration guidance

That future wave is intentionally scoped to Crud.Relational first; it does not require broad immediate cleanup across all of Eternet.Mediator.

Related Docs

• docs/README.md for the organized documentation index
• docs/guides/behaviors.md for the current runtime model, bridge conventions, compatibility notes, and examples
• docs/guides/bulk-operations.md for lane selection and bulk primitive guidance
• docs/guides/outbox.md for the explicit relational outbox model
• docs/guides/include-configuration.md for legacy include configuration and the modern eager-loading alternative
• docs/plans/relational/identity-decoupling-plan.md for the next cleanup wave

Migration Note: ScopedStates Retirement

Eternet.Crud.Relational 3.0.0 aligned with the ScopedStates retirement in Eternet.Mediator.

• GeneratedRelationalCommandBinder no longer depends on a public ScopedStates service or constructor argument.
• Relational bridge binding now resolves values through GeneratedBindingRuntime and the ambient generated runtime scope.
• Tests or custom infrastructure that previously created ScopedStates manually should migrate to GeneratedBindingRuntime.EnterScope() and GeneratedBindingRuntime.Publish(...) when they need runtime state in-process.

Migration guide: ../../Eternet.Mediator/docs/scoped-states-breaking-change-v3.md