Getting started
View as MarkdownThis guide takes you from an empty project to a working multi-tenant ASP.NET Core app with EF Core data isolation. If you are not using ASP.NET Core, read Non-HTTP hosts after the first two sections.
1. Install the packages
For an ASP.NET Core app backed by EF Core:
dotnet add package Tenantry.AspNetCore
dotnet add package Tenantry.EfCoreTenantry.Core comes in transitively; reference it directly only if you want the core types in a
project that has neither of the above.
Tenantry is built for .NET 10, and still ships for .NET 8 and 9 (Compatibility). Each build of
Tenantry.EfCore uses the EF Core major of its target framework (8.x, 9.x or 10.x).
2. Choose your tenant key type
TKey is the type of your tenant ids. Guid, int, long and string all work
(Core concepts has the constraints). Use the same type in your entities, store
and registration. This guide uses Guid.
3. Register Tenantry
Registration needs no Tenantry using directive: AddTenantry and its builder methods are extension methods in
Microsoft.Extensions.DependencyInjection, and UseTenantry, RequireTenant and AllowMissingTenant in
Microsoft.AspNetCore.Builder. Types such as TenantDescriptor<TKey> are in the Tenantry namespace.
using Microsoft.EntityFrameworkCore;
using Tenantry;
var builder = WebApplication.CreateBuilder(args);
// Introductory setup: any caller can select any tenant with the header. For production, add
// authentication and tenant access validation (see access-control.md and the SecureApi sample).
builder.Services.AddTenantry<Guid>(tenant =>
{
// (a) Resolution: how the tenant is identified on each request.
tenant.ResolveFromHeader("X-Tenant-Id");
// (b) Storage: which tenants exist. Replace with a DB-backed store in production.
tenant.UseInMemoryStore(
[
new TenantDescriptor<Guid> { TenantId = Guid.Parse("00000000-0000-0000-0000-000000000001"), Name = "Acme" },
new TenantDescriptor<Guid> { TenantId = Guid.Parse("00000000-0000-0000-0000-000000000002"), Name = "Globex" },
]);
});Builder methods chain, so this can also be one chain:
tenant => tenant.ResolveFromHeader("X-Tenant-Id").UseInMemoryStore(tenants). app.UseTenantry() (step 7) throws
at startup if no resolver or no store is registered. The rules are in Registration.
4. Mark your tenant-owned entities
An entity becomes tenant-owned by implementing ITenantEntity<TKey>. The convenience base class
TenantEntity<TKey> implements it for you:
using Tenantry;
public class Order : TenantEntity<Guid> // adds a `Guid TenantId { get; set; }` property
{
public int Id { get; set; }
public string Description { get; set; } = string.Empty;
}Entities that do not implement ITenantEntity<TKey> are shared by all tenants (product catalogues, reference
tables) and are never filtered or stamped. Leave TenantId unset: Tenantry stamps it on insert
(Core concepts).
5. Keep your DbContext as it is
Your DbContext needs no base class, no interface and no Tenantry calls. Configure it as you normally would,
in any order, including your own query filters:
using Microsoft.EntityFrameworkCore;
public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
public DbSet<Order> Orders => Set<Order>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
// Every query filters on TenantId, so lead your indexes with it.
modelBuilder.Entity<Order>().HasIndex(o => new { o.TenantId, o.Id });
}
}6. Register the DbContext with UseTenantry()
UseTenantry() isolates the context: it adds the tenant query filter to every ITenantEntity<Guid> entity after
OnModelCreating, and attaches the interceptor that stamps and checks TenantId on SaveChanges. It works the
same with AddDbContextPool, AddDbContextFactory and AddPooledDbContextFactory.
builder.Services.AddDbContext<AppDbContext>(options => options
.UseSqlServer(connectionString)
.UseTenantry());7. Add the middleware
var app = builder.Build();
app.UseTenantry(); // resolves the tenant; place after UseAuthentication() if resolving from claimsUseTenantry() must run before any endpoint that needs a tenant. The ordering rules are in
ASP.NET Core integration.
8. Use the tenant in your endpoints
app.MapGet("/orders", async (AppDbContext db) =>
// No Where(o => o.TenantId == …) needed: the query filter adds it.
await db.Orders.ToListAsync())
.RequireTenant();
app.MapPost("/orders", async (AppDbContext db, string description) =>
{
db.Orders.Add(new Order { Description = description }); // TenantId stamped on save
await db.SaveChangesAsync();
return Results.Created();
}).RequireTenant();
app.Run();9. Try it
# Acme creates and lists an order
curl -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000001" -X POST "…/orders?description=Widgets"
curl -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000001" "…/orders" # shows the order
# Globex sees none of Acme's data
curl -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000002" "…/orders" # empty
# Missing/unknown/invalid tenant
curl "…/orders" # 400 (RequireTenant)
curl -H "X-Tenant-Id: not-a-guid" "…/orders" # 404 (names no tenant)
curl -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000099" "…/orders" # 404 (not in store)The rejections have an empty body. Add builder.Services.AddProblemDetails() to get application/problem+json
bodies instead; see ASP.NET Core integration.
Next steps
- Replace the in-memory store with a real one: Tenant stores.
- Resolve tenants from subdomains, routes or claims: Tenant resolution.
- Restrict which users may use which tenants: Access control.
- The isolation policy, admin queries and migrations: EF Core integration.