Tenantry documentation
View as MarkdownTenantry keeps each tenant's data apart in EF Core applications, in a shared database or a database per tenant. In a
shared database, tenant-owned entities carry a TenantId that every query and save is scoped to; with a
database per tenant, each tenant's contexts connect to its own database.
Your entities need no base class, and Tenantry does not take over your request pipeline. Schema per tenant,
provisioning and migrations across tenant databases are in Tenantry.Pro.
If you are new, start with Getting started and Core concepts.
Guides
- Getting started: install the packages and build a tenant-aware app end to end.
- Core concepts: the tenant key,
ITenantDescriptor,ITenantContextvs.ITenantScope, and theAsyncLocalmodel that ties them together. - Tenant stores: the in-memory store, writing a custom
ITenantStore, service lifetimes, and caching tenants. - ASP.NET Core integration:
AddTenantry, the resolution middleware, pipeline ordering, HTTP status codes, and resolution events. - Tenant resolution: header, subdomain, host, route, claim, and query-string resolvers, resolver ordering, custom resolvers, and identifiers other than the tenant id.
- Access control: requiring tenants per-endpoint or globally, access validators, and claim-based validation.
- Calling other services: sending the current tenant with
HttpClientand gRPC calls (Tenantry.Http), and resolving it in the called service. - Caching per tenant:
HybridCacheentries and output-cached responses kept per tenant (Tenantry.Caching,IsolateOutputCache()), shared entries, and invalidation. - Options per tenant:
IOptionsSnapshot<T>andIOptionsMonitor<T>values per tenant (Tenantry.Options), built from your configuration and the tenant, and cleared when the tenant changes. - Authentication per tenant: JWT bearer, OpenID Connect and cookie settings per tenant, with
UseTenantResolution()before authentication, and a scheme per tenant. - ASP.NET Core Identity: users kept per tenant in a shared database, user names unique within a tenant, and sign-in cookies tied to their tenant.
- EF Core integration: query filters, the
SaveChangesinterceptor, isolation options, pooling, a database per tenant, migrations, and cross-tenant queries. - Owned and multi-table entities: how owned entities, entities split across tables and many-to-many join rows are checked, saves that succeed or fail as a whole, and models that cannot be isolated.
- Non-HTTP hosts:
AddTenantryfor console apps, worker services, and background jobs. - Testing: tests that use Tenantry's real services, with tenant scopes,
WebApplicationFactoryand EF Core isolation. - Diagnostics: log event ids, the
tenant.idtrace tag and log scope, and the resolution metric. - AOT & trimming: what is supported, per package, and why EF Core differs.
- Compatibility: supported .NET and EF Core versions, databases, and dependency ranges.
- Troubleshooting: common pitfalls and how to diagnose them.
- Migrating from Finbuckle.MultiTenant: how Finbuckle's concepts and EF Core setup map to Tenantry, and what changes.
- Analyzers: the warnings
Tenantry.EfCoreandTenantry.AspNetCoregive for code that leaves tenant data unprotected, and how to configure them. - For AI coding agents: the steps an agent follows to add Tenantry, a test that proves isolation, the common mistakes, and rules to copy into AGENTS.md.
- API reference: every public type and member, generated from the XML documentation comments.
How the pieces fit together
Tenantry has three responsibilities, each configured in the AddTenantry lambda:
| Responsibility | Question it answers | Configured with |
|---|---|---|
| Resolution | Who is the tenant for this request/operation? | ResolveFromHeader(...), ResolveFromClaim(...), … (ASP.NET Core), or ITenantScopeFactory (non-HTTP) |
| Storage | Which tenants exist, and what are their details? | UseInMemoryStore(...), UseStore<T>() |
| Isolation | How is each tenant's data kept separate? | options.UseTenantry() on each DbContext, or UseConnectionStrings(...) and AddDbContextPerTenantDatabase<TContext>(...) for a database per tenant |
The flow on an ASP.NET Core request:
HTTP request
│
▼
UseTenantry() ──► resolver(s) extract an identifier ──► ITenantStore finds the tenant it names (cached, optionally)
│ │
│ (optional) access validators run │
▼ ▼
ITenantContextSetter.MakeCurrent(tenant) sets the AsyncLocal tenant for the rest of the request
│
▼
Your endpoint + EF Core
├─ reads ──► global query filter restricts rows to ITenantContext.CurrentTenantId
└─ writes ──► SaveChanges interceptor stamps/validates TenantIdIn a console or worker app there is no request, so you make the tenant current yourself with
ITenantScopeFactory (or ITenantContextSetter.MakeCurrent); everything below that line behaves identically.