Vorn.EntityManagement.Client 5.0.0-rc4

Vorn.EntityManagement.Client

Vorn.EntityManagement.Client contains a Blazor component base that wraps an IEntityClient<TDto, TDescriptorDto> implementation. Use it to build real-time CRUD experiences with minimal plumbing—the base class manages SignalR connection lifetime, loading/error state, CRUD helpers, and server notifications so your UI code can focus on rendering.

Why use it?

• Lifecycle aware – automatically starts the underlying SignalR client during OnInitializedAsync (configurable via AutoConnect) and tears it down when the component is disposed.
• Ready-made commands – exposes async helpers such as AddAsync, UpdateAsync, RemoveAsync, and GetListAsync that call the injected client, manage busy indicators, and bubble errors through an EventCallback<Exception>.
• Notification friendly – subscribes to EntityNotificationReceived and exposes an overridable OnNotificationAsync hook so derived components can refresh state, show toasts, or sync caches when other users make changes.
• Interception support – forwards the optional EntityInterceptionConfig to the SignalR client, ensuring user/time context flows to the server for audit logging and authorization behaviors.

Getting started

1. Install the packages

dotnet add package Vorn.EntityManagement.SignalR.Client
dotnet add package Vorn.EntityManagement.Client

Bring in Vorn.EntityManagement and Vorn.EntityManagement.Server if you have not already configured the backend service and hub.

2. Provide a connection factory and interception provider

Implement IEntityConnectionFactory to centralize the HubConnection configuration for your DTO type and register the ambient interception provider so user/time context can flow through AsyncLocal storage.

using Microsoft.AspNetCore.SignalR.Client;
using Vorn.EntityManagement.Common;
using Vorn.EntityManagement.SignalR.Client;

public sealed class DocumentConnectionFactory(Uri hubUri) : IEntityConnectionFactory
{
    public Task<HubConnection> CreateConnection<TDto>()
        where TDto : EntityDto
    {
        HubConnection connection = new HubConnectionBuilder()
            .WithUrl(hubUri)
            .WithAutomaticReconnect()
            .Build();

        return Task.FromResult(connection);
    }
}

builder.Services.AddScoped<IEntityConnectionFactory, DocumentConnectionFactory>();
builder.Services.AddScoped<IEntityInterceptionProvider, AmbientEntityInterceptionProvider>();

3. Register a typed SignalR client

Create a concrete client that inherits from EntityClient<TDto, TDescriptorDto> and forwards constructor dependencies to the base class. Register it with dependency injection so the Blazor component can request it.

using Vorn.EntityManagement.SignalR.Client;

public sealed class DocumentClient(
    IEntityConnectionFactory connectionFactory,
    IEntityInterceptionProvider interceptionProvider)
    : EntityClient<DocumentDto, DocumentDescriptorDto>(connectionFactory, interceptionProvider)
{ }

builder.Services.AddScoped<DocumentClient>();

4. Derive a component

Inherit from EntityClientComponentBase<TClient, TDto, TDescriptorDto> to build a Blazor component with minimal code. The base class exposes the current descriptor, busy/error state, and CRUD helpers that wrap the injected DocumentClient.

@inherits DocumentListBase

@if (IsBusy)
{
    <p>Loading documents...</p>
}
else if (!string.IsNullOrEmpty(ErrorMessage))
{
    <p class="text-danger">@ErrorMessage</p>
}
else
{
    <ul>
        @foreach (var document in Documents)
        {
            <li>@document.Title</li>
        }
    </ul>
}

@code {
    public sealed class DocumentListBase
        : EntityClientComponentBase<DocumentClient, DocumentDto, DocumentDescriptorDto>
    {
        protected List<DocumentDto> Documents { get; } = new();

        protected override async Task OnInitializedAsync()
        {
            await base.OnInitializedAsync();
            Documents.AddRange(await Client.GetListAsync(Descriptor));
        }

        protected override async Task OnNotificationAsync(EntityNotification notification)
        {
            Documents.Clear();
            Documents.AddRange(await Client.GetListAsync(Descriptor));
        }
    }
}

5. Configure parameters

• Set AutoConnect="false" when you want to defer connection startup (for example, until after authentication completes).
• Provide an EntityInterceptionConfig to scope all calls made while the component is alive.
• Toggle StopClientOnDispose="true" if the client should be stopped and disposed when the component is removed from the render tree.
• Handle the Error callback to report exceptions through your preferred UI mechanism.

6. Call CRUD helpers

EntityClientComponentBase exposes async helpers (AddAsync, RemoveByIdAsync, GetListAsync, and more) that handle mutual exclusion, update IsBusy, and capture exceptions into ErrorMessage. Combine them with your UI events:

await AddAsync(new DocumentDto { Title = NewTitle });
Documents = (await Client.GetListAsync(Descriptor)).ToList();
StateHasChanged();

Additional tips

• Use the provided SafeRunAsync helper when performing read operations that should update IsBusy and emit errors without rethrowing.
• Override DisposeAsync in your derived component if you need to release additional resources; remember to call await base.DisposeAsync() so the hub connection is cleaned up.
• Pair the component base with source-generated DTOs/descriptors from Vorn.EntityManagement.Generators to keep type definitions consistent across server and client projects.

With Vorn.EntityManagement.Client, building real-time Blazor pages that talk to your SignalR-backed entity services becomes a matter of composing UI rather than rewriting plumbing.