Vorn.EntityManagement 4.0.0-gamma

Vorn.EntityManagement

Vorn.EntityManagement provides a thin domain layer for CRUD-heavy applications that rely on Entity Framework Core and MediatR. The library supplies audited entity base types, descriptor-driven queries, repository and service abstractions, cache invalidation helpers, and a Roslyn source generator that wires everything together through dependency injection so that your application code can stay focused on the domain instead of infrastructure plumbing.

Table of contents

• Features
• Installation
• Getting started
  • 1. Declare entities and descriptors
  • 2. Implement a repository
  • 3. Register MediatR handlers
  • 4. Issue CRUD requests
  • 5. Add higher level services (optional)
  • 6. Plug into Entity Framework Core
  • 7. Cache entities
  • 8. React to domain notifications
• Descriptor-driven querying
• NuGet package layout
• Development

Features

• Audited aggregate root base class – derive from Entity to get identifiers, created/updated/deleted timestamps and soft-delete helpers out of the box.
• Descriptor based filtering – express query filters, paging and soft-delete options through EntityDescriptor/EntityDescriptorDto records and the QueryExtensions.Apply helper.
• Repository abstraction – reuse the generic EntityRepository base to implement repositories backed by EF Core DbContexts, or implement the IEntityRepository interface for other stores.
• Mediator powered CRUD – ready-made MediatR commands, queries and handlers cover add, update, delete, list, count and paged scenarios so you can orchestrate persistence with a single IMediator dependency.
• Service façade – EntityService wraps the mediator pipeline with DTO mapping helpers, descriptor conversions and convenience APIs for single item, bulk and paged operations.
• Cache support – memory cache helpers and invalidators keep entities warm in IMemoryCache while automatically evicting stale data during EF Core SaveChanges intercepts.
• Auditing & notifications – the EntityManagementInterceptor updates audit fields, performs soft delete handling, invalidates caches and publishes EntityNotification messages after each successful save.
• Source generator registration – annotate your assembly and descriptors and the Roslyn generator will emit an EntityManagementRegistration helper that registers handlers, caches and interceptors in the DI container automatically.

Installation

Install the library from NuGet:

dotnet add package Vorn.EntityManagement --version 2.2.1

The package ships with the generator analyzer so you only need a single dependency.

Getting started

1. Declare entities and descriptors

Derive your domain entity from Entity and create a descriptor that inherits from EntityDescriptor. Apply the generator attributes so the source generator can discover the relationship between the two types:

using Vorn.EntityManagement;
using Vorn.EntityManagement.Generators;

[assembly: GenerateEntityManagementRegistration]

[EntityDescriptorFor(typeof(Customer))]
public sealed record CustomerDescriptor : EntityDescriptor;

public sealed class Customer : Entity
{
    public Customer() => Id = Guid.NewGuid();
    public string Name { get; set; } = string.Empty;
}

The example mirrors the test entity used in this repository – the entity automatically inherits audit fields while the descriptor advertises the filterable properties and ties into the generator.

2. Implement a repository

For EF Core scenarios subclass EntityRepository<TEntity, TDescriptor, TDbContext> and override behavior as needed. Alternatively, implement IEntityRepository manually for non-EF persistence; the in-memory test double illustrates the required methods.

3. Register MediatR handlers

Once the generator runs it emits a static EntityManagementRegistration.AddGeneratedEntityHandlers helper. Call it when building your service provider, add MediatR, and register your repository implementation:

ServiceCollection services = new();
services.AddSingleton<ServiceFactory>(p => p.GetService!);
services.AddTransient<IMediator, Mediator>();
EntityManagementRegistration.AddGeneratedEntityHandlers(services);
services.AddSingleton<IEntityRepository<Customer, CustomerDescriptor>, CustomerRepository>();

This matches the pattern exercised in the integration tests and ensures every command, query, cache and interceptor dependency is wired automatically.

4. Issue CRUD requests

With DI configured you can route persistence through IMediator. Use the generated commands and queries to add, update, fetch, list or remove entities:

Customer customer = new() { Name = "Initial" };
Customer? added = await mediator.Send(new AddEntityCommand<Customer, CustomerDescriptor>(customer));
Customer? fetched = await mediator.Send(new GetEntityByIdQuery<Customer, CustomerDescriptor>(customer.Id));
customer.Name = "Updated";
await mediator.Send(new UpdateEntityCommand<Customer, CustomerDescriptor>(customer));
await mediator.Send(new RemoveEntityCommand<Customer, CustomerDescriptor>(customer));
int count = await mediator.Send(new CountEntitiesQuery<Customer, CustomerDescriptor>(new CustomerDescriptor()));

The integration tests demonstrate the same end-to-end flow against the in-memory repository.

5. Add higher level services (optional)

EntityService wraps the mediator with mapping delegates so that application layers can work with DTOs instead of entities, handle bulk operations, convert descriptor DTOs and retrieve paged results from a single abstraction.

6. Plug into Entity Framework Core

Register the EntityManagementInterceptor as a SaveChangesInterceptor for your DbContext. The interceptor stamps audit fields, converts hard deletes into soft deletes, triggers cache invalidation and publishes notifications after the save succeeds. It also clears pending notifications when a transaction fails.

7. Cache entities

Use the provided EntityMemoryCache<TEntity> to warm frequently accessed aggregates and pair it with EntityCacheInvalidator<TEntity> (or your own IEntityCacheInvalidator implementation) to keep cache entries synchronized with persistence operations.

8. React to domain notifications

Every intercepted save emits EntityNotification<TId> instances describing the affected entity, operation type and captured field deltas. Subscribe to them with MediatR notification handlers to orchestrate downstream workflows or integration events.

Descriptor-driven querying

Descriptors double as request models for complex filters. Populate properties like CreatedFrom, UpdatedBy, IsDeleted, Skip and Take, then pass them into any GetEntitiesQuery or repository call. The shared QueryExtensions.Apply routine applies the filters, paging and soft-delete rules to the EF Core queryable, automatically toggling IgnoreQueryFilters when deleted records are requested.

NuGet package layout

The package exposes the runtime library, links the generator attributes into the main assembly, and includes the analyzer output so consumers receive handler registrations without extra references.

Development

• Run the automated test suite with dotnet test to validate repository, cache and interceptor behavior.
• Create a NuGet package locally via dotnet pack -c Release, which respects the project metadata and bundles the analyzer bits alongside the library.