Getting Started

MultiTenant is designed to be easy to use and follows standard .NET conventions as much as possible. This introduction assumes a typical ASP.NET Core use case, but any application using .NET dependency injection can work with the library.

Installation

MultiTenant is split into focused NuGet packages so you only reference what you need. For a typical ASP.NET Core app install Finbuckle.MultiTenant.AspNetCore:

dotnet add package Finbuckle.MultiTenant.AspNetCore

Basic Configuration

MultiTenant is simple to get started with. Below is a sample app configured to use the subdomain as the tenant identifier and the app's configuration ( most likely from an appsettings.json file) as the source of tenant details.

using Finbuckle.MultiTenant;

var builder = WebApplication.CreateBuilder(args);

// add app services...

// add MultiTenant services
builder.Services.AddMultiTenant<TenantInfo>()
    .WithHostStrategy()
    .WithConfigurationStore();

var app = builder.Build();

// add the MultiTenant middleware
app.UseMultiTenant();

// add other middleware...

app.Run();

That's all that is needed to get going. Let's break down each line:

builder.Services.AddMultiTenant<TenantInfo>()

This line registers the base services and designates TenantInfo as the class that will hold tenant information at runtime.

The type parameter for AddMultiTenant<TTenantInfo> must be an instance of TenantInfo or a derived class and holds basic information about the tenant such as its name and an identifier. TenantInfo is provided as a basic implementation record, but a derived record can be used if more properties are needed.

See Core Concepts for more information on TenantInfo.

.WithHostStrategy()

The line tells the app that our "strategy" to determine the request tenant will be to look at the request host, which defaults to the extracting the subdomain as a tenant identifier.

See Strategies for more information.

.WithConfigurationStore()

This line tells the app that information for all tenants are in the appsettings.json file used for app configuration. If a tenant in the store has the identifier found by the strategy, the tenant will be successfully resolved for the current request.

A minimal configuration entry looks like this:

{
  "Finbuckle:MultiTenant:Stores:ConfigurationStore": {
    "Tenants": [
      {
        "Id": "93f330717e5d4f039cd05da312d559cc",
        "Identifier": "initech",
        "Name": "Initech"
      }
    ]
  }
}

See Stores for more information.

MultiTenant comes with a collection of strategies and store types that can be mixed and matched in various ways.

app.UseMultiTenant()

This line configures the middleware which resolves the tenant using the registered strategies, stores, and other settings. Be sure to call it before other middleware which will use per-tenant functionality, such as UseAuthentication() or UseAuthorization() so those components see the resolved tenant.

Basic Usage

With the services and middleware configured, access information for the current tenant from the TenantInfo property on the MultiTenantContext<TTenantInfo> object accessed from the GetMultiTenantContext<TTenantInfo> extension method:

var tenantInfo = HttpContext.GetMultiTenantContext<TenantInfo>().TenantInfo;

if(tenantInfo != null)
{
    var tenantId = tenantInfo.Id;
    var identifier = tenantInfo.Identifier;
    var name = tenantInfo.Name;
}

The type of the TenantInfo property depends on the type passed when calling AddMultiTenant<TTenantInfo> during configuration. If the current tenant could not be determined then TenantInfo will be null.

The TenantInfo instance and the typed instance are also available using the IMultiTenantContextAccessor<TTenantInfo> interface which is available via dependency injection.

See Configuration and Usage for more information.

Advanced Usage

The library builds on this basic functionality to provide a variety of higher level features. See the documentation for more details:

Samples

A variety of sample projects are available in the samples directory.