TCIS.MultiTenancy 1.0.0-rc.33

TCIS.MultiTenancy

The library providing the core architecture to manage and resolve Multi-Tenancy information within the TCIS system.

🌟 Overview

TCIS.MultiTenancy provides a robust and flexible framework for:

• Tenant Resolver: Identifies the current tenant through various Strategies such as: Host-based, Header-based (for gRPC/REST), custom Delegate, or Static.
• Tenant Stores: Stores and retrieves tenant configuration via: Static Configuration (IConfiguration), In-Memory, or distributed cache (IDistributedCache).
• Flexible Integration: Suitable for all isolation levels (Isolation Tier 1 - RLS, Tier 2 - Schema, Tier 3 - Database).

📦 Installation

dotnet add package TCIS.MultiTenancy

⚙️ Configuration (appsettings.json)

Example with ConfigurationStore (reading the tenant list from appsettings):

{
  "MultiTenancy": {
    "Stores": {
      "ConfigurationStore": {
        "Tenants": [
          {
            "Id": "tenant-1",
            "Identifier": "customer-a",
            "Name": "Customer A",
            "IsolationLevel": 2
          },
          {
            "Id": "tenant-2",
            "Identifier": "customer-b",
            "Name": "Customer B",
            "IsolationLevel": 3
          }
        ]
      }
    }
  }
}

"ConfigurationStore": {
  "Defaults": { "IsolationLevel": 1 },
  "Tenants": [ … ]
}

🚀 Usage

In Program.cs, register the MultiTenancy service using the Fluent Builder API:

using TCIS.MultiTenancy.Extensions;
using TCIS.MultiTenancy.Abstractions; // Contains the TenantInfo record

var builder = WebApplication.CreateBuilder(args);

// Register services
builder.Services.AddTMultiTenant<TenantInfo>()
    // 1. Configure the Tenant storage location (Store)
    .WithConfigurationStore()
    // Or a distributed cache
    // .WithDistributedCacheStore(TimeSpan.FromHours(1))
    
    // 2. Configure how to determine the Tenant (Strategy) from the request Context
    .WithDelegateStrategy(context => 
    {
        if (context is HttpContext httpContext)
        {
            // Extract from the "X-Tenant-Id" Http Header
            return Task.FromResult(httpContext.Request.Headers["X-Tenant-Id"].FirstOrDefault());
        }
        return Task.FromResult<string?>(null);
    });
    
var app = builder.Build();

// Add the Middleware to the pipeline (if using ASP.NET) to set the Tenant for the current Request
// app.UseMultiTenant(); 
app.Run();

💡 Basic Example

Có hai accessor, và chọn đúng cái là quan trọng:

using TCIS.Core.Abstractions.Context;
using TCIS.MultiTenancy.Abstractions;

public class MyService(
    IWorkContextAccessor workContextAccessor,
    IMultiTenantContextAccessor<TenantInfo> tenantAccessor)
{
    public void DoSomething()
    {
        // Nghiệp vụ: "tôi đang làm việc cho cảng nào"
        string? siteCode = workContextAccessor.WorkContext?.Tenant.SiteCode;

        // Hạ tầng: chỉ lấy từ đây. ITenantContext KHÔNG mang IsolationLevel.
        TenantInfo? tenant = tenantAccessor.MultiTenantContext?.TenantInfo;
        IsolationTier tier = tenant?.IsolationLevel ?? IsolationTier.Unknown;
    }
}

🧵 Kích hoạt tenant ở luồng KHÔNG phải HTTP

EventBus consumer, Hangfire worker, worker nền — những luồng này không đi qua MultiTenantMiddleware, nên phải tự nạp ngữ cảnh. Bộ ba hàm, và thứ tự lẫn tính đồng bộ đều bắt buộc:

var tenant = await sp.ResolveTenantAsync(siteCode, ct);   // async — chỉ tra Store
try
{
    if (!sp.ApplyTenant(tenant))                          // ĐỒNG BỘ — ghi ngữ cảnh
    {
        return;                                           // fail-closed: không chạy nghiệp vụ
    }

    // … công việc …
}
finally
{
    sp.ClearTenant();                                     // dọn CẢ HAI ngữ cảnh
}

ClearTenant dọn cả MultiTenantContext lẫn phần Tenant của WorkContext — đúng bằng những gì ApplyTenant đã ghi. Nó giữ nguyên User/Trace/Client/Business, vì những thứ đó thuộc về đơn vị công việc chứ không thuộc về tenant.

Với EventBus, đừng viết tay bộ ba này — gọi services.AddTEventBusTenantContext() của gói TCIS.EventBus.MultiTenancy, nó móc sẵn vào đúng chỗ trong vòng đời consumer.

📌 Provenance — fork point

TCIS.MultiTenancy, TCIS.MultiTenancy.AspNetCore và TCIS.MultiTenancy.EntityFrameworkCore là tác phẩm phái sinh của Finbuckle.MultiTenant, không phải mã gốc của TCIS.

⚠️ Finbuckle dùng Apache License 2.0, KHÔNG phải MIT. Apache-2.0 có bốn điều kiện ở §4 chứ không phải một như MIT — trong đó có hai điều kiện mà MIT không có: phải ghi chú rằng bạn đã sửa file, và phải giữ lại mọi thông báo attribution của bản gốc. Đừng áp thói quen xử lý TCIS.EventBus (fork của CAP, MIT) sang đây.

Điểm fork

Tái lập phép so sánh:

git clone https://github.com/Finbuckle/Finbuckle.MultiTenant.git && cd Finbuckle.MultiTenant
git log --oneline d69145b..origin/master | wc -l      # ta đang tụt lại bao nhiêu

Trạng thái đo ngày 2026-08-18

So với TCIS.EventBus (fork CAP, chỉ 10 commit sau upstream), fork này xa hơn nhiều — 8 tháng và 117 commit. Nếu định kéo bản vá upstream về thì chi phí ở đây lớn hơn hẳn.

Nghĩa vụ Apache-2.0 §4 và cách TCIS đáp ứng

Gói khai PackageLicenseExpression = MIT AND Apache-2.0: phần TCIS viết thêm theo MIT như mọi gói TCIS.* khác, phần kế thừa từ Finbuckle vẫn mang Apache-2.0.

File nào là phái sinh, file nào là của TCIS

38 file phái sinh mang header attribution — nhận ra bằng dòng // Derived from Finbuckle.MultiTenant.

9 file là mã gốc của TCIS, không mang header đó và không được thêm vào:

Cách làm việc với fork này

• Thêm hành vi mới thì đặt vào file của TCIS, đừng sửa file phái sinh. Mỗi dòng thêm vào file phái sinh là một xung đột merge trong tương lai, và làm ranh giới attribution mờ đi.
• Sửa file phái sinh thì giữ nguyên header — xoá nó là vi phạm Apache-2.0 §4(c).
• Thêm file phái sinh mới thì phải chép cả header sang, và cập nhật con số ở mục này.
• Cảnh báo bảo mật của Finbuckle áp cho ta và phải port tay.
• Giữ mục này cập nhật. Chạy lại lệnh ở phần "Điểm fork" khi đụng vào gói và sửa lại con số.