Docs
Tenantry Core

Tenantry documentation

View as Markdown

Tenantry 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

  1. Getting started: install the packages and build a tenant-aware app end to end.
  2. Core concepts: the tenant key, ITenantDescriptor, ITenantContext vs. ITenantScope, and the AsyncLocal model that ties them together.
  3. Tenant stores: the in-memory store, writing a custom ITenantStore, service lifetimes, and caching tenants.
  4. ASP.NET Core integration: AddTenantry, the resolution middleware, pipeline ordering, HTTP status codes, and resolution events.
  5. Tenant resolution: header, subdomain, host, route, claim, and query-string resolvers, resolver ordering, custom resolvers, and identifiers other than the tenant id.
  6. Access control: requiring tenants per-endpoint or globally, access validators, and claim-based validation.
  7. Calling other services: sending the current tenant with HttpClient and gRPC calls (Tenantry.Http), and resolving it in the called service.
  8. Caching per tenant: HybridCache entries and output-cached responses kept per tenant (Tenantry.Caching, IsolateOutputCache()), shared entries, and invalidation.
  9. Options per tenant: IOptionsSnapshot<T> and IOptionsMonitor<T> values per tenant (Tenantry.Options), built from your configuration and the tenant, and cleared when the tenant changes.
  10. Authentication per tenant: JWT bearer, OpenID Connect and cookie settings per tenant, with UseTenantResolution() before authentication, and a scheme per tenant.
  11. 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.
  12. EF Core integration: query filters, the SaveChanges interceptor, isolation options, pooling, a database per tenant, migrations, and cross-tenant queries.
  13. 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.
  14. Non-HTTP hosts: AddTenantry for console apps, worker services, and background jobs.
  15. Testing: tests that use Tenantry's real services, with tenant scopes, WebApplicationFactory and EF Core isolation.
  16. Diagnostics: log event ids, the tenant.id trace tag and log scope, and the resolution metric.
  17. AOT & trimming: what is supported, per package, and why EF Core differs.
  18. Compatibility: supported .NET and EF Core versions, databases, and dependency ranges.
  19. Troubleshooting: common pitfalls and how to diagnose them.
  20. Migrating from Finbuckle.MultiTenant: how Finbuckle's concepts and EF Core setup map to Tenantry, and what changes.
  21. Analyzers: the warnings Tenantry.EfCore and Tenantry.AspNetCore give for code that leaves tenant data unprotected, and how to configure them.
  22. 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.
  23. 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:

ResponsibilityQuestion it answersConfigured with
ResolutionWho is the tenant for this request/operation?ResolveFromHeader(...), ResolveFromClaim(...), … (ASP.NET Core), or ITenantScopeFactory (non-HTTP)
StorageWhich tenants exist, and what are their details?UseInMemoryStore(...), UseStore<T>()
IsolationHow 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 TenantId

In 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.

On this page