Vorn.Entities.Common 8.2.0-rc6

Vorn.Entities.Common

Vorn.Entities.Common centralizes the lightweight contracts that flow between the server, clients, and background jobs. The project keeps persistence-agnostic DTOs, descriptor shapes, and notification primitives in one place so every layer agrees on paging, auditing, and change tracking semantics.

Packages that should reference it

Add the package anywhere you expose entity projections or descriptors:

dotnet add package Vorn.Entities.Common

Pair it with the core library (Vorn.Entities) for handlers/services and with the presentation packages (Vorn.Entities.Server, Vorn.Entities.Client, Vorn.Entities.Interface) when you need UI or SignalR helpers.

Key building blocks

These primitives are intentionally nullable-friendly and serialization-ready so they work with ASP.NET Core Minimal APIs, SignalR, or background workers.

Modeling custom descriptors and DTOs

Inherit from the base records to capture domain-specific fields while retaining the shared paging/audit shape:

public sealed record DocumentDescriptorDto : EntityDescriptorDto
{
    public Guid? FolderId { get; init; }
    public string? Owner { get; init; }
}

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

Because the base types are records, you can use with expressions to clone instances as filters evolve in the UI.

Working with paged responses

The PartedResult<T> record is the cross-project contract for paginated queries. Combine it with descriptor filters to keep list views in sync:

public sealed class DocumentService : IEntityService<DocumentDto, DocumentDescriptorDto>
{
    public Task<PartedResult<DocumentDto>> GetAsync(DocumentDescriptorDto descriptor, CancellationToken ct)
    {
        // Fetch a page from your data store and hydrate DTOs.
        IReadOnlyList<DocumentDto> items = ...;
        int total = ...;
        return Task.FromResult(new PartedResult<DocumentDto>(items, total));
    }
}

Downstream consumers (Blazor grids, SignalR clients) can render the page while still showing the total number of records for paging controls.

Publishing notifications

EntityNotification and EntityNotificationArgs travel across MediatR, SignalR, or event buses so all listeners agree on the event shape:

EntityNotification notification = new(
    new EntityNotificationArgs(
        entityName: nameof(DocumentDto),
        id: document.Id.ToString(),
        operation: EntityOperation.Updated,
        occurredAt: clock.UtcNow,
        correlationId: activityId,
        changes: new Dictionary<string, (object? Old, object? New)>
        {
            [nameof(DocumentDto.Title)] = (oldTitle, document.Title)
        }));

Clients can inspect Changes to drive toast messages or highlight updated rows. When paired with the server package the same shape is emitted automatically from the EF Core interceptor.

Tips

• Keep DTOs serialization-friendly: avoid behaviors or services on the records.
• Treat descriptors as immutable request models; build helpers that return new instances rather than mutating the existing one when applying filters.
• Use the shared enums/records in automated tests to ensure your domain and presentation layers agree on the payload shape.