Vorn.Entities 8.2.0-rc3

Vorn.Entities

The core package supplies the entity base types, descriptor abstractions, MediatR requests, caching helpers, and source annotations that power the rest of the stack. It is transport-agnostic and designed for vertical slice architectures where each aggregate owns its handlers, DTOs, and persistence concerns.

What you get

• Entity base types – Entity, EntityDescriptor, EntityDescriptorDto, and EntityDto shape how aggregates expose identity, filtering, and transport-friendly projections.
• Command/query records – predefined MediatR requests cover CRUD and descriptor-driven operations so you can focus on handler logic.
• Caching & interception – EntityMemoryCache, EntityCacheInvalidationService, and the SaveChanges interceptor keep data fresh across reads.
• Notifications – EntityNotification/EntityNotificationCore describe the changes that occurred so downstream behaviors can react.
• Source generator hooks – attributes such as GenerateEntitiesRegistration let the Roslyn generator emit DI wiring for the whole feature slice.

Install

dotnet add package Vorn.Entities

Include Vorn.Entities.Generators if you want generated registration extensions and strongly typed mapping stubs.

Define an aggregate

[GenerateEntitiesRegistration]
public sealed class Document : Entity
{
    public string Title { get; init; } = string.Empty;
}

[EntityDescriptorFor(typeof(Document))]
public sealed record DocumentDescriptor : EntityDescriptor
{
    public string? SearchText { get; init; }
}

public sealed record DocumentDto : EntityDto
{
    public Guid Id { get; init; }
    public string Title { get; init; } = string.Empty;
}

Descriptors capture filters; DTOs shape what you return to clients. Pair them with mapping delegates in your service layer.

Implement handlers

Handlers translate commands/queries into persistence operations. The provided records make the intent explicit.

internal sealed class AddDocumentHandler(IDocumentDbContext db)
    : IRequestHandler<AddEntityCommand<Document, DocumentDescriptor>, Document?>
{
    public async Task<Document?> Handle(
        AddEntityCommand<Document, DocumentDescriptor> request,
        CancellationToken cancellationToken)
    {
        db.Documents.Add(request.Entity);
        await db.SaveChangesAsync(cancellationToken);
        return request.Entity;
    }
}

You can implement handlers with Entity Framework Core, Dapper, or any persistence mechanism.

Expose services

Wrap your handlers with EntityService<TEntity, TDescriptor, TDto, TDescriptorDto> to present a DTO-first contract.

public sealed class DocumentService(IMediator mediator)
    : EntityService<Document, DocumentDescriptor, DocumentDto, DocumentDescriptorDto>(
        mediator,
        DocumentDto.FromEntity,
        DocumentDto.ToEntity,
        DocumentDescriptorDto.ToDescriptor)
{ }

Consumers (minimal APIs, SignalR hubs, background jobs) call the service to trigger MediatR requests while staying unaware of the underlying storage.

Wire up caching & interception

services.AddSingleton<IEntityCache, EntityMemoryCache>();
services.AddSingleton<IEntityCacheInvalidationService, EntityCacheInvalidationService>();
services.AddSingleton<EntityManagementInterceptor>();
services.AddScoped<IEntityRepository<Document, DocumentDescriptor>, DocumentRepository>();

Register EntityManagementInterceptor with your DbContext so audit fields, soft deletes, and notifications work automatically.

Best practices

• Keep domain logic close to the handlers; the core library stays unopinionated about your aggregate internals.
• Use descriptors to represent tenant, feature flag, or contextual filters—every command/query accepts them.
• Combine with FluentValidation or pipeline behaviors to add validation and logging without touching the handler signatures.