# Tenantry documentation

The docs of Tenantry 0.7 (Core v0.7.0, Pro v0.7.0), the newest release. Web page: https://tenantry.dev/docs/core

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](https://tenantry.dev/docs/core/efcore-integration.md#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](https://tenantry.dev/docs/pro.md).

If you are new, start with [Getting started](https://tenantry.dev/docs/core/getting-started.md) and [Core concepts](https://tenantry.dev/docs/core/core-concepts.md).

## Guides

1. [Getting started](https://tenantry.dev/docs/core/getting-started.md): install the packages and build a tenant-aware app end to end.
2. [Core concepts](https://tenantry.dev/docs/core/core-concepts.md): the tenant key, `ITenantDescriptor`, [`ITenantContext`](https://tenantry.dev/docs/core/api/tenantry-itenantcontext.md) vs. [`ITenantScope`](https://tenantry.dev/docs/core/api/tenantry-itenantscope.md), and the `AsyncLocal` model that ties them together.
3. [Tenant stores](https://tenantry.dev/docs/core/tenant-stores.md): the in-memory store, writing a custom [`ITenantStore`](https://tenantry.dev/docs/core/api/tenantry-itenantstore.md), service lifetimes, and caching tenants.
4. [ASP.NET Core integration](https://tenantry.dev/docs/core/aspnetcore-integration.md): `AddTenantry`, the resolution middleware, pipeline ordering, HTTP status codes, and resolution events.
5. [Tenant resolution](https://tenantry.dev/docs/core/tenant-resolution.md): header, subdomain, host, route, claim, and query-string resolvers, resolver ordering, custom resolvers, and identifiers other than the tenant id.
6. [Access control](https://tenantry.dev/docs/core/access-control.md): requiring tenants per-endpoint or globally, access validators, and claim-based validation.
7. [Calling other services](https://tenantry.dev/docs/core/http-propagation.md): sending the current tenant with `HttpClient` and gRPC calls (`Tenantry.Http`), and resolving it in the called service.
8. [Caching per tenant](https://tenantry.dev/docs/core/caching.md): `HybridCache` entries and output-cached responses kept per tenant (`Tenantry.Caching`, `IsolateOutputCache()`), shared entries, and invalidation.
9. [Options per tenant](https://tenantry.dev/docs/core/per-tenant-options.md): `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](https://tenantry.dev/docs/core/authentication-per-tenant.md): JWT bearer, OpenID Connect and cookie settings per tenant, with `UseTenantResolution()` before authentication, and a scheme per tenant.
11. [ASP.NET Core Identity](https://tenantry.dev/docs/core/aspnetcore-identity.md): 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](https://tenantry.dev/docs/core/efcore-integration.md): query filters, the `SaveChanges` interceptor, isolation options, pooling, a database per tenant, migrations, and cross-tenant queries.
13. [Owned and multi-table entities](https://tenantry.dev/docs/core/efcore-advanced.md): 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](https://tenantry.dev/docs/core/non-http-hosts.md): `AddTenantry` for console apps, worker services, and background jobs.
15. [Testing](https://tenantry.dev/docs/core/testing.md): tests that use Tenantry's real services, with tenant scopes, `WebApplicationFactory` and EF Core isolation.
16. [Diagnostics](https://tenantry.dev/docs/core/diagnostics.md): log event ids, the `tenant.id` trace tag and log scope, and the resolution metric.
17. [AOT & trimming](https://tenantry.dev/docs/core/aot-and-trimming.md): what is supported, per package, and why EF Core differs.
18. [Compatibility](https://tenantry.dev/docs/core/compatibility.md): supported .NET and EF Core versions, databases, and dependency ranges.
19. [Troubleshooting](https://tenantry.dev/docs/core/troubleshooting.md): common pitfalls and how to diagnose them.
20. [Migrating from Finbuckle.MultiTenant](https://tenantry.dev/docs/core/migrating-from-finbuckle.md): how Finbuckle's concepts and EF Core setup map to Tenantry, and what changes.
21. [Analyzers](https://tenantry.dev/docs/core/analyzers.md): 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](https://tenantry.dev/docs/core/ai-agents.md): 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](https://tenantry.dev/docs/core/api.md): 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`](https://tenantry.dev/docs/core/api/tenantry-itenantscopefactory.md) (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 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.
