TCIS.Pluggable.Persistence.EntityFrameworkCore 1.0.0-rc.19

TCIS.Pluggable.Persistence.EntityFrameworkCore

The multi-tenant data layer of the Pluggable architecture: a tenant-aware DbContext, per-site EF model composition, connection-level isolation, and automatic audit stamping.

Do not register a DbContext with this package directly. Use a provider package — SqlServer, PostgreSql or Oracle.

Table of contents

1. The three isolation tiers

A tenant's tier comes from TenantInfo.IsolationLevel in the Tenant Store and decides everything below it.

Connection strings come from the Tenant Store per request, never from appsettings. That is what allows one process to serve tenants that live on different servers.

2. Registration

builder.Services.AddPluggableSqlServer<TosDbContext>(commandTimeoutSeconds: 30);

The provider call registers the connection provider (scoped), calls AddPluggableDbContext with the command timeout, and registers IDbConnectionFactory for the Dapper read path.

What you get in DI

IModelCacheKeyFactory is replaced by SiteModelCacheKeyFactory — see section 9.

3. TBaseDbContext<TContext>

Derive your context from it to inherit tenant isolation, per-site model composition and audit stamping:

public sealed class TosDbContext(DbContextOptions<TosDbContext> options, IWorkContextAccessor accessor)
    : TBaseDbContext<TosDbContext>(options, accessor)
{
    public DbSet<GateTransaction> GateTransactions => Set<GateTransaction>();
}

OnModelCreating composes the model in this order:

1. Load every Platform module (SiteCode = DEFAULT)
2. Load the plugin modules of the current site
3. Scan entities from each module's assembly
4. Call ISiteCoreModule.ConfigureDatabase on modules that implement it
5. Apply the global query filter (tenant + soft delete)

4. The global query filter is fail-closed

The last row is deliberate. A background job running without tenant context and sweeping across every tenant is a data leak, not a convenience.

If a job legitimately needs data, give it a tenant context — Hangfire and EventBus both restore WorkContext through context propagation.

5. Reading soft-deleted rows

EF Core keeps one query filter per entity, so the tenant predicate and the soft-delete predicate must live in the same expression. The consequence: IgnoreQueryFilters() removes both at once.

// ❌ WRONG — the intent was "show the recycle bin", the effect is "show EVERY tenant's orders"
var deleted = await db.Orders.IgnoreQueryFilters().Where(o => o.IsDeleted).ToListAsync();

// ✅ RIGHT — see deleted rows, tenant filter still intact
using (db.IncludeSoftDeleted())
{
    var deleted = await db.Orders.Where(o => o.IsDeleted).ToListAsync();
}

The scope is reference-counted and nests safely; it closes when the using block ends. If a whole DbContext exists for archive/restore work, override AllowSoftDeletedQuery => true instead of opening the scope at each call site.

6. Cross-tenant reporting

When a query legitimately spans tenants, say so explicitly:

public sealed class ReportingDbContext(DbContextOptions<ReportingDbContext> options, IWorkContextAccessor accessor)
    : TBaseDbContext<ReportingDbContext>(options, accessor)
{
    // Group-wide reporting / sync jobs — bypass the tenant filter CONSCIOUSLY
    protected override bool AllowCrossTenantQuery => true;
}

AllowCrossTenantQuery is evaluated at query time, not baked into the model cache, so it can point at a flag you control rather than a constant.

7. Audit and TenantId stamping

TBaseDbContext overrides SaveChanges(bool) and SaveChangesAsync(bool, CancellationToken) — the two canonical EF Core extension points. All four entry points (SaveChanges(), SaveChanges(bool), SaveChangesAsync(ct), SaveChangesAsync(bool, ct)) therefore get audit stamps and an automatic TenantId.

Two audit contracts exist, serving existing products and new products side by side:

Pick exactly one per entity, according to the product it belongs to.

Timestamps come from a TimeProvider, so tests can freeze the clock instead of asserting on a range.

8. Per-site entities

A site that needs its own tables implements ISiteCoreModule:

public sealed class CatLaiModule : ISiteCoreModule
{
    public string SiteCode => "CATLAI";

    public void RegisterServices(IServiceCollection services, IConfiguration configuration) { }

    public void ConfigureDatabase(ModelBuilder builder)
        => builder.ApplyConfigurationsFromAssembly(GetType().Assembly);
}

A plugin that does not change the database schema should not implement ISiteCoreModule — leaving it out lets the site reuse the core EF model cache entry and saves memory.

9. ⚠️ The EF model cache

SiteModelCacheKeyFactory builds the key from (DbContext type, sorted module set, designTime, tier).

The key does not contain the site code — only the module set. Two sites loading the same modules share one model. That is deliberate, and it imposes two invariants:

Never reach for static or ambient state inside ConfigureDatabase: module instances are created once and kept like singletons, so anything read there sticks to every site.

Plugin modules are free to vary — their presence is part of the key.

Tier 2 in particular: the schema name belongs to the connection, not the model. Moving it into the model via HasDefaultSchema(siteCode) would require adding the site code to the cache key; without that it leaks across tenants.

10. Connection lifetime

Because the two paths use separate sessions, Dapper reads run in parallel with EF writes without competing for a connection. The flip side is that Dapper does not join an EF transaction — see section 11.

GetConnection() is guarded by a lock and throws ObjectDisposedException once the scope has been disposed. Both matter under load: the previous lock-free version could build two connections when several threads asked at once, and the second one was never disposed — a connection leak that only surfaces later, somewhere else, as "Timeout expired… prior to obtaining a connection from the pool".

11. Transactions

Explicit transactions work through the tenant-aware connection:

await uow.BeginTransactionAsync(ct);
try
{
    // … several SaveChanges calls …
    await uow.CommitTransactionAsync(ct);
}
catch
{
    await uow.RollbackTransactionAsync(ct);
    throw;
}

Most of the time you do not need one — SaveChangesAsync is already atomic. Reach for an explicit transaction only when several SaveChanges calls must succeed or fail together. Full guidance: TCIS.Persistence.EntityFrameworkCore.

For a Pluggable pipeline, open the transaction around the whole pipeline at the call site; steps keep calling SaveChangesAsync as usual. Transactions do not nest — a second BeginTransactionAsync throws, which forces ownership to be explicit.

Raw SQL inside a transaction must borrow EF's connection, because IDapperContext opens its own:

var conn = db.Database.GetDbConnection();
var tx   = db.Database.CurrentTransaction?.GetDbTransaction();
await conn.ExecuteAsync(sql, param, transaction: tx);

12. Pitfalls