Troolio.Projection.Redis 10.0.2

Troolio.Projection.Redis

Redis derived read models, entity indexes and bounded partition change feeds for Troolio applications. Requires .NET 10 and Troolio.Core 10.0.8. Redis is a derived cache; keep authoritative business events in the actor's event store.

dotnet add package Troolio.Projection.Redis --version 10.0.2

Register an owned connection

Register one provider for each application configuration. The connection is reusable and belongs to that provider's DI lifetime; separate provider instances retain their own configuration.

services.AddSingleton<IRedisConnectionProvider>(_ =>
    new RedisConnectionProvider(configuration.GetConnectionString("Redis")!));
services.AddSingleton<RedisProvider<TaskCard>>();
services.AddSingleton<IRedisReadProvider<TaskCard>>(sp =>
    sp.GetRequiredService<RedisProvider<TaskCard>>());
services.AddSingleton<IRedisWriteProvider<TaskCard>>(sp =>
    sp.GetRequiredService<RedisProvider<TaskCard>>());

Use a secured production connection string supplied through host configuration. The host disposes the singleton connection provider.

Create, update and read an entity

The entity ID identifies one cached object. The partition ID identifies an index and a change feed, such as one user's task board. Provider transactions commit the mutation, index change and feed entry together on a single Redis server.

public sealed class TaskCard
{
    public Guid Id { get; set; }
    public string? Title { get; set; }
}

var card = new TaskCard { Id = taskId, Title = "Buy milk" };
string cursor = await provider.CreateEntity(taskId, card, boardId);
card.Title = "Buy oat milk";
await provider.UpdateEntity(taskId, card, boardId, x => x.Title!);
TaskCard? current = await provider.GetEntityAsync(taskId);

Use asynchronous reads inside async actor and HTTP handlers. Each successful write returns its own change cursor, including concurrent writes. Failures propagate; a cursor is not returned for an uncommitted transaction.

Partition membership and deletion

Membership indexes can share one entity across partitions. Removing membership leaves the entity itself available.

await provider.AddEntityKeyToPartition(taskId, secondBoardId);
await provider.UpdateEntityKeyInPartition(taskId, secondBoardId);
await provider.RemoveEntityKeyFromPartition(taskId, secondBoardId);
// Delete removes the shared entity plus this partition's index entry.
await provider.DeleteEntity(taskId, boardId);

If an entity belongs to several partitions, remove its other memberships before globally deleting it. Entity keys currently use the CLR type's simple name, so choose distinct read-model class names across your application. Existing key layout is retained. Multi-key transactions are intended for a single Redis server; this adapter does not configure Redis Cluster hash slots.

Read a bounded change page

Absolute offsets are independent from Troolio correlation/causation IDs. A page reads at most 1000 feed entries; 100 is the default. Advance only after processing the page.

long offset = savedOffset;
RedisChangePage page = await provider.GetChangePageAsync(boardId, offset, 100);
foreach (ChangeHashEntry change in page.Entries)
{
    // Read the current entity, or remove it locally when the entity is absent.
    await RefreshCard(change.EntityKey);
}
savedOffset = page.NextOffset;

HasMore means the page filled its requested limit; the next page can be empty. Legacy GetChangeEntries checks only the latest 1000 entries and rejects a cursor outside that window. Offset paging assumes retained feed entries have not been trimmed. Configure retention and snapshot/reload behavior together; Redis feed entries are cache synchronization hints, not a durable delivery ledger.

Event-driven projection

A projection can map each live event to RedisEventEntityCreate, RedisEventEntityUpdate, partition membership changes or deletion. RedisPersistence<TEntity>.Persist awaits the mapped mutations and rejects unsupported mapping types. The application supplies live event subscription and durable recovery strategy. Pure actor replay never updates Redis or sends notifications.

Mapper.AddMap<EventEnvelope<TaskRenamed>, Task<RedisEventEntityUpdate<TaskCard>>>(e =>
    Task.FromResult(new RedisEventEntityUpdate<TaskCard>(e.Event.TaskId,
        new TaskCard { Id = e.Event.TaskId, Title = e.Event.Title },
        e.Event.BoardId, card => card.Title!)));
// A RedisPersistence<TaskCard> handler awaits Update(e).

Authorization remains with the application: resolve partition IDs from the verified caller and enforce access before exposing cards or feeds.

Redis projection guide · Samples