Multi Tenancy

Wikipedia defines multi-tenancy as like that:

Volo.Abp.MultiTenancy package defines fundamental interfaces to make your code “multi-tenancy ready”. So, install it to your project using the package manager console (PMC):

Then you can add AbpMultiTenancyModule dependency to your module:


using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    [DependsOn(typeof(AbpMultiTenancyModule))]
    public class MyModule : AbpModule
    {
        //...
    }
}

Define Entities

You can implement IMultiTenant interface for your entities to make them multi-tenancy ready. Example:

using System;
using Volo.Abp.Domain.Entities;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    public class Product : AggregateRoot, IMultiTenant
    {
        public Guid? TenantId { get; set; } //IMultiTenant defines TenantId property
        public string Name { get; set; }
        public float Price { get; set; }
    }
}

IMultiTenant requires to define a TenantId property in the implementing entity (See entity documentation for more about entities).

Obtain Current Tenant’s Id

Your code may require to get current tenant’s id (regardless of how it’s retrieved actually). You can inject and use ICurrentTenant interface for such cases. Example:

using Volo.Abp.DependencyInjection;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    public class MyService : ITransientDependency
    {
        private readonly ICurrentTenant _currentTenant;
        public MyService(ICurrentTenant currentTenant)
        {
            _currentTenant = currentTenant;
        }
        public void DoIt()
        {
            var tenantId = _currentTenant.Id;
            //use tenantId in your code...
        }
    }
}

Change Current Tenant

TODO: …

Determining Current Tenant

Volo.Abp.AspNetCore.MultiTenancy package has implementation to determine the current tenant from current web request (from subdomain, header, cookie, route… etc.). See Volo.Abp.AspNetCore.MultiTenancy Package section later in this document.

Custom Tenant Resolvers

You can add your custom tenant resolver to AbpTenantResolveOptions in your module’s ConfigureServices method as like below:

using Volo.Abp.Modularity;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    [DependsOn(typeof(AbpMultiTenancyModule))]
    public class MyModule : AbpModule
    {
        public override void ConfigureServices(ServiceConfigurationContext context)
        {
            Configure<AbpTenantResolveOptions>(options =>
                options.TenantResolvers.Add(new MyCustomTenantResolveContributor());
            });
            //...
        }
    }
}

MyCustomTenantResolveContributor must implement ITenantResolveContributor as shown below:

A tenant resolver can set TenantIdOrName if it can determine it. If not, just leave it as is to allow next resolver to determine it.

Tenant Store

Volo.Abp.MultiTenancy package defines ITenantStore to abstract data source from the framework. You can implement ITenantStore to work with any data source (like a relational database) that stores information of your tenants.

…

Configuration Data Store

There is a built in (and default) tenant store, named ConfigurationTenantStore, that can be used to store tenants using standard configuration system (with package). Thus, you can define tenants as hard coded or get from your appsettings.json file.

Example: Define tenants as hard-coded

using System;
using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.Data;
using Volo.Abp.Modularity;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    [DependsOn(typeof(AbpMultiTenancyModule))]
    public class MyModule : AbpModule
    {
        public override void ConfigureServices(ServiceConfigurationContext context)
        {
            Configure<AbpDefaultTenantStoreOptions>(options =>
            {
                options.Tenants = new[]
                {
                    new TenantConfiguration(
                        Guid.Parse("446a5211-3d72-4339-9adc-845151f8ada0"), //Id
                        "tenant1" //Name
                    ),
                    new TenantConfiguration(
                        Guid.Parse("25388015-ef1c-4355-9c18-f6b6ddbaf89d"), //Id
                        "tenant2" //Name
                    )
                    {
                        //tenant2 has a seperated database
                        ConnectionStrings =
                        {
                            {ConnectionStrings.DefaultConnectionStringName, "..."}
                        }
                    }
                };
            });
        }
    }
}

Example: Define tenants in appsettings.json

First create your configuration from your appsettings.json file as you always do.

using System.IO;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.Modularity;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    [DependsOn(typeof(AbpMultiTenancyModule))]
    public class MyModule : AbpModule
    {
        {
            Configure<AbpDefaultTenantStoreOptions>(configuration);
        }
        private static IConfigurationRoot BuildConfiguration()
        {
            return new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())
                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                .Build();
        }
    }
}

Then add a “Tenants“ section to your appsettings.json:

"Tenants": [
    {
      "Id": "446a5211-3d72-4339-9adc-845151f8ada0",
      "Name": "tenant1"
    },
    {
      "Id": "25388015-ef1c-4355-9c18-f6b6ddbaf89d",
      "Name": "tenant2",
      "ConnectionStrings": {
        "Default": "...write tenant2's db connection string here..."
      }
    }
  ]

Volo.Abp… Package (TODO)

TODO: This package implements ITenantStore using a real database…

Tenant Information

Id: Unique Id of the tenant.
Name: Unique name of the tenant.
ConnectionStrings: If this tenant has dedicated database(s) to store it’s data, then connection strings can provide database connection strings (it may have a default connection string and connection strings per modules - TODO: Add link to Abp.Data package document).

A multi-tenant application may require additional tenant properties, but these are the minimal requirements for the framework to work with multiple tenants.

Change Tenant By Code

TODO…

Volo.Abp.AspNetCore.MultiTenancy Package

Volo.Abp.AspNetCore.MultiTenancy package integrate multi-tenancy to ASP.NET Core applications. To install it to your project, run the following command on PMC:

Install-Package Volo.Abp.AspNetCore.MultiTenancy

Then you can add AbpAspNetCoreMultiTenancyModule dependency to your module:

Multi-Tenancy Middleware

Volo.Abp.AspNetCore.MultiTenancy package includes the multi-tenancy middleware…

app.UseMultiTenancy();

TODO:…

Determining Current Tenant From Web Request

Volo.Abp.AspNetCore.MultiTenancy package adds following tenant resolvers to determine current tenant from current web request (ordered by priority). These resolvers are added and work out of the box:

CurrentUserTenantResolveContributor: Gets the tenant id from claims of the current user, if the current user has logged in. This should always be the first contributor for security.
QueryStringTenantResolveContributor: Tries to find current tenant id from query string parameter. Parameter name is “__tenant” by default.
RouteTenantResolveContributor: Tries to find current tenant id from route (URL path). Variable name is “__tenant” by default. So, if you defined a route with this variable, then it can determine the current tenant from the route.
HeaderTenantResolveContributor: Tries to find current tenant id from HTTP header. Header name is “__tenant” by default.
CookieTenantResolveContributor: Tries to find current tenant id from cookie values. Cookie name is “__tenant” by default.

“__tenant” parameter name can be changed using AbpAspNetCoreMultiTenancyOptions. Example:

services.Configure<AbpAspNetCoreMultiTenancyOptions>(options =>
{
    options.TenantKey = "MyTenantKey";
});

Domain Tenant Resolver

In a real application, most of times you will want to determine current tenant either by subdomain (like mytenant1.mydomain.com) or by the whole domain (like mytenant.com). If so, you can configure AbpTenantResolveOptions to add a domain tenant resolver.

Example: Add a subdomain resolver

using Microsoft.Extensions.DependencyInjection;
using Volo.Abp.AspNetCore.MultiTenancy;
using Volo.Abp.Modularity;
using Volo.Abp.MultiTenancy;
namespace MyCompany.MyProject
{
    [DependsOn(typeof(AbpAspNetCoreMultiTenancyModule))]
    public class MyModule : AbpModule
    {
        public override void ConfigureServices(ServiceConfigurationContext context)
        {
            Configure<AbpTenantResolveOptions>(options =>
            {
                //Subdomain format: {0}.mydomain.com 
                //Adding as the second highest priority resolver after 'CurrentUserTenantResolveContributor' to
                //ensure the user cannot impersonate a different tenant.
                options.TenantResolvers.Insert(1, new DomainTenantResolveContributor("{0}.mydomain.com"));
            });
            //...
        }
    }
}

Instead of options.TenantResolvers.Insert(1, new DomainTenantResolveContributor("{0}.mydomain.com")); you can use this shortcut: