Finbuckle.
A MultiTenant store is responsible for retrieving information about a tenant based on an identifier string determined
by MultiTenant strategies. The retrieved information is then used to create a TenantInfo object which
provides the current tenant information to your app.
MultiTenant supports several "out-of-the-box" stores for resolving the tenant. Custom stores can be created by
implementing IMultiTenantStore.
MultiTenant stores support custom TenantInfo derived classes, but complex implementations may require special
handling. For best results ensure the class works well with the underlying store approach—for example, that it can be
serialized from JSON for the configuration store if using JSON file configuration sources.
The examples in this documentation use the TenantInfo basic implementation.
If the provided MultiTenant stores are not suitable then a custom store can be created by
implementing IMultiTenantStore<TTenantInfo>. The library will set the type parameterTTenantInfo to match the type
parameter passed to AddMultiTenant<TTenantInfo> at compile time. The interface defines AddAsync, UpdateAsync,
RemoveAsync, GetByIdentifierAsync, GetAsync, and GetAllAsync methods. GetByIdentifierAsync
and GetAsync should return null if there is no suitable tenant match.
A custom implementation of IMultiTenantStore<TTenantInfo> can be registered by calling WithStore<TStore>
after AddMultiTenant<TTenantInfo> in the ConfigureServices method of the Startup class. WithStore<TStore> uses
dependency injection along with any passed parameters to construct the implementation instance. Alternative overloads
accept a service lifetime, a factory method, and/or other parameters for more customization. The library internally
decorates any IMultiTenantStore<TTenantInfo> at runtime with a wrapper providing basic logging and exception handling.
Custom store implementations should contain minimal logging or validation logic. These are handled via the wrapper store used during runtime for consistency.
// register a custom store with the templated method
builder.Services.AddMultiTenant<TenantInfo>()
.WithStore<MyStore>(ServiceLifetime.Singleton, myParam1, myParam2)...
// or register a custom store with the non-templated method which accepts a factory method
builder.Services.AddMultiTenant<TenantInfo>()
.WithStore(ServiceLifetime.Singleton, sp => new MyStore())...
Multiple stores can be used, and for each strategy returning a non-null identifier the stores are checked in the order registered until a matching tenant is resolved. Keep in mind that if multiple strategies are used it is possible for a store to be checked multiple times during tenant resolution.
MultiTenant stores are registered in the dependency injection system under the
IMultiTenantStore<TTenantInfo> service type.
If multiple stores are registered a specific one can be retrieved by requesting an
IEnumerable<IMultiTenantStore<TTenantInfo>> and filtering to the specific implementation type:
public MyService(IEnumerable<IMultiTenantStore<TenantInfo>> stores)
{
_configurationStore = stores.OfType<ConfigurationStore<TenantInfo>>().Single();
}
If implemented, GetAllAsync will return an IEnumerable<TTenantInfo> listing of all tenants in the store.
Currently InMemoryStore, ConfigurationStore, and EFCoreStore implement GetAllAsync.
An overload to GetAllAsync(int take, int skip) exists to optionally allow take and skip parameters for pagination
support if needed when iterating through a large number of tenants or retrieving from a remote source.
NuGet package: Finbuckle.MultiTenant
Uses a ConcurrentDictionary<string, TenantInfo> as the underlying store. See the
web api sample project for an example of
using the in-memory store.
Configure by calling WithInMemoryStore after AddMultiTenant<TTenantInfo>. By default, the store is empty and the
tenant identifier matching is case-insensitive. Case-insensitive is generally preferred. An overload
of WithInMemoryStore accepts an Action<InMemoryStoreOptions> delegate to configure the store further:
// set up a case-insensitive in-memory store.
builder.Services.AddMultiTenant<TenantInfo>()
.WithInMemoryStore()...
// or make it case sensitive and/or add some tenants.
builder.Services.AddMultiTenant<TenantInfo>()
.WithInMemoryStore(options =>
{
options.IsCaseSensitive = true;
options.Tenants.Add(new TenantInfo{...});
options.Tenants.Add(new TenantInfo{...});
options.Tenants.Add(new TenantInfo{...});
})...
NuGet package: Finbuckle.MultiTenant
Uses an
app's configuration as
the underlying store. See
the multi-tenant Identity sample project for
an example of using this store with appsettings.json.
This store is case-insensitive when retrieving tenant information by tenant identifier.
This store is read-only and calls to AddAsync, UpdateAsync, and RemoveAsync will throw
a NotImplementedException. However, if the app is configured to reload its configuration if the source changes,
e.g. appsettings.json is updated, then the MultiTenant store will reflect the change.
Configure by calling WithConfigurationStore after AddMultiTenant<TTenantInfo>. By default, it will use the root
configuration object and search for a section named "Finbuckle:MultiTenant:Stores:ConfigurationStore". An overload
of WithConfigurationStore allows for a different base
configuration object or section name if needed.
// register to use the default root configuration and section name.
builder.Services.AddMultiTenant<TenantInfo>()
.WithConfigurationStore()...
// or use a different configuration path key
builder.Services.AddMultiTenant<TenantInfo>()
.WithConfigurationStore("customConfigurationPathKey)...
The configuration section should use this JSON format shown below. Any fields in the Defaults section will be
automatically copied into each tenant unless the tenant specifies its own value. For a custom implementation
of TenantInfo properties are mapped from the JSON automatically.
{
"Finbuckle:MultiTenant:Stores:ConfigurationStore": {
"Defaults": {
"ConnectionString": "default_connection_string"
},
"Tenants": [
{
"Id": "unique-id-0ff4daf",
"Identifier": "tenant-1",
"Name": "Tenant 1 Company Name",
"ACustomProperty": "VIP Customer"
},
{
"Id": "unique-id-ao41n44",
"Identifier": "tenant-2",
"Name": "Name of Tenant 2",
"ConnectionString": "tenant_specific_connection_string"
}
]
}
}
NuGet package: Finbuckle.MultiTenant.EntityFrameworkCore
Uses an Entity Framework Core database context as the backing store.
Case sensitivity is determined by the underlying EF Core database provider.
The database context must derive from EFCoreStoreDbContext. Note that TTenantInfo is a record type and EF Core
does not support tracking for record types. The EFCoreStore carefully avoids tracking issues, but if your app uses the
EFCoreStoreDbContext directly it should be aware of these issues.
This database context is not itself multi-tenant, but rather contains the details of all tenants. It will often be a standalone database separate from any tenant database(s) and will have its own connection string.
Configure by calling WithEFCoreStore<TEFCoreStoreDbContext,TenantInfo> after AddMultiTenant<TTenantInfo> and
provide types for the store's database context generic parameter:
// configure dbcontext `MultiTenantStoreDbContext`, which derives from `EFCoreStoreDbContext`
builder.Services.AddMultiTenant<TenantInfo>()
.WithEFCoreStore<MultiTenantStoreDbContext,TenantInfo>()...
NuGet package: Finbuckle.MultiTenant
Sends the tenant identifier, provided by the multitenant strategy, to an http(s) endpoint to get a TenantInfo object
in return.
This store is usually case-insensitive when retrieving tenant information by tenant identifier, but the remote server might be more restrictive.
Make sure the tenant info type will support basic JSON serialization and deserialization via System.Text.Json.
This strategy will attempt to deserialize the tenant using
the System.Text.Json web defaults.
For a successful request, the store expects a 200 response code and a json body with properties Id, Identifier
, Name, and other properties which will be mapped into a TenantInfo object with the type
passed to AddMultiTenant<TTenantInfo>.
Any non-200 response code results in a null TenantInfo.
This store is read-only and calls to AddAsync, UpdateAsync, and RemoveAsync will throw
a NotImplementedException.
Configure by calling WithHttpRemoteStore after AddMultiTenant<TTenantInfo> uri template string must be passed to the
method. At runtime the tenant identifier will replace the substring {__tenant__} in the uri template. If the template
provided does not contain {__tenant__}, the identifier is appended to the template. An overload
of WithHttpRemoteStore allows for a lambda function to further configure the internal HttpClient:
// append the identifier to the provided url
builder.Services.AddMultiTenant<TenantInfo>()
.WithHttpRemoteStore("https://remoteserver.com/)...
// or template the identifier into a custom location
builder.Services.AddMultiTenant<TenantInfo>()
.WithHttpRemoteStore("https://remoteserver.com/{__tenant__}/getinfo)...
// or modify the underlying `HttpClient` with a custom message handler and settings
builder.Services.AddMultiTenant<TenantInfo>()
.WithHttpRemoteStore("https://remoteserver.com/", httpClientBuilder =>
{
httpClientBuilder.AddHttpMessageHandler<MyCustomHeaderHandler>();
httpClientBuilder.ConfigureHttpClient( client =>
{
client.Timeout = TimeSpan.FromSeconds(10);
});
});
// or add Polly support
// via https://www.hanselman.com/blog/AddingResilienceAndTransientFaultHandlingToYourNETCoreHttpClientWithPolly.aspx
builder.Services.AddMultiTenant<TenantInfo>()
.WithHttpRemoteStore("https://remoteserver.com/", httpClientBuilder =>
{
httpClientBuilder.AddTransientHttpErrorPolicy(policyBuilder => policyBuilder.RetryAsync(2));
});
NuGet package: Finbuckle.MultiTenant
Uses the distributed cache
mechanism. The distributed cache can use Redis, SQl Server, NCache, or an in-memory (for testing purposes)
implementation. A sliding expiration is also supported. The store does not interact with any other stores by default.
Make sure the tenant info type will support basic JSON serialization and deserialization via System.Text.Json.
This strategy will attempt to deserialize the tenant using
the System.Text.Json web defaults.
Each tenant info instance is actually stored twice in the cache, once using the Tenant ID as the key and another using
the Tenant Identifier as the key. Calls to AddAsync, UpdateAsync, and RemoveAsync will keep these dual
cache entries synced.
This store does not implement GetAllAsync.
Configure by calling WithDistributedCacheStore after AddMultiTenant<TTenantInfo>. By default, entries do not expire,
but a TimeSpan can be passed to be used as a sliding
expiration:
// use the default configuration with no sliding expiration.
services.AddMultiTenant<TenantInfo>()
.WithDistributedCacheStore()...
// or set a 5 minute sliding expiration.
services.AddMultiTenant<TenantInfo>()
.WithDistributedCacheStore(TimeSpan.FromMinutes(5));
NuGet package: Finbuckle.MultiTenant
The Echo Store serves as a simple, read-only store that directly returns a new tenant instance based on the given identifier without any additional settings. It's particularly suited for applications that require a simple, immediate method for tenant identification without the need for persistence, such as during testing phases or in environments where tenant information is static and predefined elsewhere.
This store is read-only and calls to AddAsync, UpdateAsync, and RemoveAsync will throw
a NotImplementedException. Because no stores are saved, a call to GetAllAsync will also throw an Exception.
Configure by calling WithEchoStore after AddMultiTenant<TTenantInfo>.
services.AddMultiTenant<TenantInfo>()
.WithEchoStore();