Tyto.Materializer.EntityFrameworkCore 0.1.0-alpha.7

Tyto.Materializer.EntityFrameworkCore

This package provides a robust IViewStore<TView, TKey> implementation using Entity Framework Core. It allows you to persist your read models as structured tables in a relational database (SQL Server, PostgreSQL, SQLite, etc.) while seamlessly integrating with EF Core's change tracking and native optimistic concurrency mechanisms.

🚀 Features

• Relational Persistence: Store your materialized views in SQL databases, enabling complex querying, filtering, and reporting capabilities outside of the event loop.
• Optimistic Concurrency: Leverages EF Core's native concurrency tokens (RowVersion / Timestamp) to prevent data overwrite during concurrent updates.
• Change Tracking: Efficiently updates only modified fields using EF Core's change tracker.
• Automatic Conventions: Includes helper methods to automatically configure Tyto types (like ProjectableVersion) within your DbContext.

📦 Installation

dotnet add package Tyto.Materializer.EntityFrameworkCore

⚡ Usage

Using this provider involves two steps: configuring your DbContext correctly and enabling the provider in your application startup.

1. Configure Your DbContext

Your EF Core DbContext must be configured to map your view entity. This includes defining a Primary Key and a Concurrency Token.

using Microsoft.EntityFrameworkCore;
using Tyto.Materializer;
using Tyto.Materializer.EntityFrameworkCore; // Required for conventions

public class MyAppContext : DbContext
{
    public DbSet<UserBalanceView> UserBalances { get; set; }

    public MyAppContext(DbContextOptions<MyAppContext> options) : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        
        // 1. Apply Tyto conventions
        // This automatically configures value converters for types like ProjectableVersion.
        modelBuilder.ApplyTytoMaterializerConventions();

        var view = modelBuilder.Entity<UserBalanceView>();

        // 2. CRITICAL: Define the primary key.
        // For single-column keys:
        view.HasKey(v => v.UserId);

        // For composite keys (e.g., IdentifiedAs<RecipientKey>):
        // The properties in the composite key must match the EF Core primary key components by name.
        // modelBuilder.Entity<RecipientView>().HasKey(v => new { v.ApplicationId, v.RecipientId });

        // 3. CRITICAL: Configure the 'Version' property as a concurrency token.
        // This tells EF Core to include this column in the WHERE clause during updates
        // (e.g., UPDATE ... WHERE Id = x AND Version = y).
        view.Property(v => v.Version).IsConcurrencyToken();
    }
}

Composite Keys Support

If your read model is partitioned across multiple tenants or identifiers (e.g. (ApplicationId, RecipientId)), define a record struct as the key and declare composite keys in EF Core:

public readonly record struct RecipientKey(long ApplicationId, string RecipientId);

public class RecipientView : IProjectableView
{
    public long ApplicationId { get; set; }
    public string RecipientId { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
    public ProjectableVersion Version { get; set; }
}

// In DbContext:
modelBuilder.Entity<RecipientView>(b =>
{
    b.HasKey(v => new { v.ApplicationId, v.RecipientId });
    b.Property(v => v.Version).IsConcurrencyToken();
});

// In Program.cs:
endpoint.Materialize(views => views
    .ForView<RecipientView>()
    .IdentifiedAs<RecipientKey>(id => id.From<RecipientCreated>(e => new RecipientKey(e.ApplicationId, e.RecipientId)))
    .Store.UseEntityFrameworkCore().InContext<MyAppContext>());

The EF Core store validates all key components against the model on startup and orders values automatically for FindAsync.

2. Register in Program.cs

Configure Tyto to use the EF Core provider for your specific view.

var builder = WebApplication.CreateBuilder(args);

// Standard EF Core Registration
builder.Services.AddDbContext<MyAppContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

// Tyto Configuration: the view is declared on the endpoint that receives its events
builder.AddTyto(tyto => tyto.Endpoints(endpoints => endpoints.Add("users", endpoint =>
{
    endpoint.UseTransactions<MyAppContext>(tx => tx.UseInbox());
    endpoint.Materialize(materializer =>
    {
        materializer.ForView<UserBalanceView>()
            .IdentifiedAs<Guid>(c => c.From<UserCreated>(e => e.UserId))
            
            // Configure Storage
            // The view and key come from the chain; only the context is written.
            .Store.UseEntityFrameworkCore().InContext<MyAppContext>();
            
            // Note: This replaces any previously configured store for this view.
    });
})));

On an endpoint with UseTransactions<MyAppContext>, the view is written into the transaction's own context and commits with the inbox row, or not at all. A view in another DbContext than the transaction's is refused rather than saved separately.

🔧 How It Works Internally

Runtime Validation

When the application starts, the EntityFrameworkCoreViewStore performs a safety check. It inspects your DbContext metadata to ensure:

1. The TView entity is registered in the context.
2. A Primary Key is defined and matches the key type expected by Tyto.
3. The Version property is explicitly configured as a Concurrency Token.

If any of these checks fail, it throws an InvalidOperationException immediately, preventing silent data consistency bugs.

Concurrency Handling

1. Read: Uses DbSet<T>.FindAsync to load the entity.
2. Write:
   • The SaveAsync method attaches the entity and sets the state to Modified.
   • It increments the Version property in memory.
   • It calls SaveChangesAsync.
   • EF Core generates an SQL statement like: UPDATE Views SET Bal = 100, Version = 2 WHERE Id = 1 AND Version = 1.
   • If no rows are affected (meaning the version in DB was not 1), EF Core throws DbUpdateConcurrencyException.
3. Retry: This provider catches that exception and re-throws it as a Tyto...ConcurrencyException, which triggers the core library's automatic retry policy (Reload → Re-project → Save).