Dosaic.Plugins.Persistence.EfCore.Abstractions 1.2.8

Dosaic.Plugins.Persistence.EfCore.Abstractions

Dosaic.Plugins.Persistence.EfCore.Abstractions is a Dosaic plugin that provides the foundational Entity Framework Core building blocks for all EF Core–based database access in the Dosaic ecosystem. It delivers a strongly-typed IDb context abstraction, NanoId-based primary keys, a before/after trigger pipeline, automatic audit tracking with full change history, event sourcing primitives, business-logic interception, and a set of ModelBuilder extensions for consistent schema conventions.

Installation

dotnet add package Dosaic.Plugins.Persistence.EfCore.Abstractions

or add as a package reference to your .csproj:

<PackageReference Include="Dosaic.Plugins.Persistence.EfCore.Abstractions" Version="" />

Features

• IDb abstraction — a thin, testable interface wrapping an EF Core DbContext
• EfCoreDbContext — abstract base context that wires up the trigger/interceptor pipeline automatically on every SaveChangesAsync
• NanoId primary keys — IModel / Model base types backed by NanoId; DbNanoIdPrimaryKeyAttribute configures length and optional prefix
• IModel & Model — common base for all persisted entities
• Auditing — IAuditableModel / AuditableModel add CreatedBy, CreatedUtc, ModifiedBy, ModifiedUtc automatically
• Full change history — IHistory marker + auto-generated History<T> tables via HistoryTrigger<T> and ApplyHistories()
• Before/After trigger pipeline — IBeforeTrigger<T> / IAfterTrigger<T> with ordering via [TriggerOrder]
• Business logic interception — IBusinessLogic<TModel> hooks into create/update/delete lifecycle
• Event sourcing — AggregateEvent, AggregateEvent<TEnum>, IEventProcessor<T>, IEventMapper, IEventProjector<T>, and AggregatePatch
• ModelBuilder conventions — ApplyKeys(), ApplySnakeCaseNamingConventions(), ApplyEnumFields(), ApplyHistories(), ApplyEventSourcing(), ApplyAuditFields()
• Queryable helpers — ProcessAsync, ProcessAndGetAsync, UpdateGraphAsync
• Automatic health checks — every registered DbContext is registered as a readiness health check
• Background migrator — DbMigratorService<T> retries EF Core migrations until the database is reachable
• OpenTelemetry tracing — EF Core instrumentation wired up through IEfCoreConfigurator

Types

Models

Audit

Database

Identifiers

Triggers

Interceptors

Transactions

Event Sourcing

Plugin & Configuration

ModelBuilderExtensions

ServiceCollectionExtensions

Usage

1. Define an entity

using Dosaic.Extensions.NanoIds;
using Dosaic.Plugins.Persistence.EfCore.Abstractions.Identifiers;
using Dosaic.Plugins.Persistence.EfCore.Abstractions.Models;

[DbNanoIdPrimaryKey(NanoIdConfig.Lengths.NoLookAlikeDigitsAndLetters.L10)]
public class Order : Model
{
    public required string CustomerName { get; set; }
    public decimal Total { get; set; }
}

2. Define an auditable entity with history

using Dosaic.Plugins.Persistence.EfCore.Abstractions.Audit;
using Dosaic.Plugins.Persistence.EfCore.Abstractions.Identifiers;

[DbNanoIdPrimaryKey(NanoIdConfig.Lengths.NoLookAlikeDigitsAndLetters.L10)]
public class Product : AuditableModel, IHistory
{
    public required string Name { get; set; }
    public decimal Price { get; set; }

    [ExcludeFromHistory]
    public string InternalNote { get; set; }
}

3. Create a DbContext

using Dosaic.Plugins.Persistence.EfCore.Abstractions.Database;
using Microsoft.EntityFrameworkCore;

public class ShopDbContext(DbContextOptions<ShopDbContext> options) : EfCoreDbContext(options)
{
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("shop");
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ShopDbContext).Assembly);

        // Apply NanoId key lengths and FK sizes
        modelBuilder.ApplyKeys();

        // Apply audit field defaults and foreign keys (pass the "user" entity type)
        modelBuilder.ApplyAuditFields(typeof(User), typeof(User));

        // Create history tables for all IHistory entities
        modelBuilder.ApplyHistories(typeof(User));

        // Rename all tables and columns to snake_case
        modelBuilder.ApplySnakeCaseNamingConventions();

        base.OnModelCreating(modelBuilder);
    }
}

4. Register the DbContext in your plugin

using Dosaic.Hosting.Abstractions.Plugins;
using Dosaic.Hosting.Abstractions.Attributes;
using Dosaic.Plugins.Persistence.EfCore.Abstractions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;

[Configuration("shop:db")]
public class ShopDbConfiguration
{
    public string ConnectionString { get; set; } = null!;
}

public class ShopPlugin(ShopDbConfiguration config) : IPluginServiceConfiguration, IPluginApplicationConfiguration
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<ShopDbContext>(options =>
            options.UseNpgsql(config.ConnectionString));

        // Register the background migrator service instead of calling Migrate() on startup
        services.AddDbMigratorService<ShopDbContext>();
    }

    public void ConfigureApplication(IApplicationBuilder app)
    {
        // Or migrate eagerly at startup:
        // app.MigrateEfContexts<ShopDbContext>();
    }
}

Note: EfCorePlugin must also be in scope (i.e., registered via DosaicPluginTypes.All) so that the trigger/interceptor infrastructure is wired up automatically.

5. Query data via IDb

public class OrderService(IDb db)
{
    // Read-only query (AsNoTracking, expression-optimised)
    public Task<List<Order>> GetOpenOrdersAsync(CancellationToken ct)
        => db.GetQuery<Order>()
             .Where(o => o.Total > 0)
             .ToListAsync(ct);

    // Tracked set for mutations
    public async Task CreateOrderAsync(Order order, CancellationToken ct)
    {
        await db.Get<Order>().AddAsync(order, ct);
        await db.SaveChangesAsync(ct);
    }
}

6. Stream and process large result sets

// Process rows one-by-one without loading all into memory
var count = await db.GetQuery<Order>()
    .Where(o => o.Total > 100)
    .ProcessAsync(async (order, ct) =>
    {
        await SendInvoiceAsync(order, ct);
    }, cancellationToken);

7. Implement a before/after trigger

Triggers are discovered and registered automatically by EfCorePlugin.

using Dosaic.Plugins.Persistence.EfCore.Abstractions.Triggers;

[TriggerOrder(Order = 10)]
public class OrderValidationTrigger : IBeforeTrigger<Order>
{
    public Task HandleBeforeAsync(ITriggerContext<Order> context, CancellationToken cancellationToken)
    {
        foreach (var change in context.ChangeSet)
        {
            if (change.Entity.Total < 0)
                throw new InvalidOperationException("Order total cannot be negative.");
        }
        return Task.CompletedTask;
    }
}

[TriggerOrder(Order = 20)]
public class OrderNotificationTrigger(INotificationService notifications) : IAfterTrigger<Order>
{
    public async Task HandleAfterAsync(ITriggerContext<Order> context, CancellationToken cancellationToken)
    {
        foreach (var change in context.ChangeSet.Where(c => c.State == ChangeState.Added))
            await notifications.SendOrderConfirmationAsync(change.Entity, cancellationToken);
    }
}

8. Implement business logic interception

IBusinessLogic<T> implementations are discovered automatically.

using Dosaic.Plugins.Persistence.EfCore.Abstractions.Interceptors;

public class ProductBusinessLogic : IBusinessLogic<Product>
{
    public Task BeforeCreateAsync(Product model, CancellationToken cancellationToken)
    {
        model.CreatedUtc = DateTime.UtcNow;
        return Task.CompletedTask;
    }

    public Task BeforeUpdateAsync(Product model, CancellationToken cancellationToken)
    {
        if (model.Price < 0)
            throw new InvalidOperationException("Price cannot be negative.");
        return Task.CompletedTask;
    }
}

9. Implement event sourcing

using Dosaic.Plugins.Persistence.EfCore.Abstractions.Eventsourcing;
using Dosaic.Plugins.Persistence.EfCore.Abstractions.Identifiers;

public enum InventoryEventType { Received, Shipped, Adjusted }

[DbNanoIdPrimaryKey(NanoIdConfig.Lengths.NoLookAlikeDigitsAndLetters.L10)]
public class InventoryEvent : AggregateEvent<InventoryEventType>
{
    [EventMatcher] public string ProductId { get; set; }
}

// Processor is auto-registered by EfCorePlugin
public class InventoryEventProcessor : IEventProcessor<InventoryEvent>
{
    public async Task ProcessEventsAsync(IDb db, ImmutableArray<InventoryEvent> events, CancellationToken ct)
    {
        foreach (var evt in events)
        {
            var patch = AggregatePatch.FromJson(evt.EventData);
            // apply patch to read model ...
        }
    }
}

// Query all valid events for a given product
var events = await db.GetEvents(
    new InventoryEvent { Id = NanoId.Empty, ProductId = "product-123", EventData = "", ValidFrom = DateTime.UtcNow },
    dateTimeProvider);

10. Customise OpenTelemetry tracing

using Dosaic.Plugins.Persistence.EfCore.Abstractions;
using OpenTelemetry.Trace;

public class ShopEfCoreConfigurator : IEfCoreConfigurator
{
    public void ConfigureEntityFrameworkCoreInstrumentation(
        Action<EntityFrameworkInstrumentationOptions> options)
    {
        options(new EntityFrameworkInstrumentationOptions
        {
            SetDbStatementForText = true
        });
    }

    public void ConfigureOtelWithTracing(TracerProviderBuilder builder)
    {
        builder.AddSource("ShopService");
    }
}

Appsettings.yml example (PostgreSQL)

shop:
  db:
    connectionString: "Host=localhost;Port=5432;Database=shop;Username=postgres;Password=postgres"