Muonroi.Tenancy.SiteProfile 1.0.0-alpha.16

Muonroi.Tenancy.SiteProfile

Per-site DI registration pattern for schema-divergent multi-tenancy — wire the correct DbContext, services, and mappers for each site deployment from a single binary.

In multi-tenant SaaS deployments each site can carry a divergent database schema, its own EF Core DbContext subclass, and site-specific business logic. This package solves that by introducing ISiteProfile — a per-site DI registration contract — and the extension methods to activate one or many profiles at startup. A scoped ISiteProfileResolver makes the active profile available inside every HTTP request, background job, or test.

The package sits between Muonroi.Tenancy.Core (ambient TenantContext) and the higher-level Muonroi.Tenancy.SiteProfile.Web (EF Core / Dapper per-site infrastructure, middleware, hot-reload).

Installation

dotnet add package Muonroi.Tenancy.SiteProfile --prerelease

Quick Start

Single-site deployment (1 binary = 1 site)

// Program.cs
builder.Services.AddSiteProfile<Sg01Profile>(builder.Configuration);

// Sg01Profile.cs
public class Sg01Profile : ISiteProfile
{
    public string SiteId => "sg01";

    public void RegisterServices(IServiceCollection services, IConfiguration configuration)
    {
        services.AddDbContext<Sg01DbContext>(o =>
            o.UseNpgsql(configuration.GetConnectionString("Sg01")));

        services.AddKeyedScoped<IOrderService, Sg01OrderService>("sg01");
    }
}

Multi-site deployment (1 binary = N sites, reflection discovery)

// Program.cs — scans assemblies for ISiteProfile implementations
builder.Services.AddMultiSiteProfiles(
    builder.Configuration,
    siteCodeAccessor: sp => sp.GetRequiredService<IHttpContextAccessor>()
                              .HttpContext?.Request.Headers["x-site-code"],
    assemblies:
    [
        typeof(DefaultSiteProfile).Assembly,
        typeof(AlphaSiteProfile).Assembly,
        typeof(BravoSiteProfile).Assembly,
    ]);

// Wire a per-request service resolved by site key
builder.Services.AddSiteResolvedService<IOrderService>();

Each ISiteProfile.RegisterServices() registers its implementation as a keyed service:

services.AddKeyedScoped<IOrderService, AlphaOrderService>("ALPHA");

AddSiteResolvedService<IOrderService>() then adds a scoped factory that calls GetKeyedService<IOrderService>(siteId) at runtime, falling back to "default" if the site key is not found.

Source-generated profile (AOT-safe)

[GenerateSiteProfile("ALPHA", typeof(AlphaOrderContext))]
public partial class AlphaSiteProfile : ISiteProfile
{
    public string SiteId => "ALPHA";
    // RegisterServices() is generated by Muonroi.Tenancy.SiteProfile.SourceGenerators
}

Add the generator package alongside this one:

dotnet add package Muonroi.Tenancy.SiteProfile.SourceGenerators --prerelease

Features

• ISiteProfile contract — implement once per site; RegisterServices() wires DbContext, repos, services, and mappers for that site.
• AddSiteProfile<T>() — single-site registration; one binary, one profile.
• AddMultiSiteProfiles() — reflection-based discovery of all ISiteProfile implementations across supplied assemblies; wires per-request ISiteProfileResolver.
• AddMultiSiteProfilesCore() — AOT-safe overload; accepts pre-instantiated ISiteProfile[] from generated manifests.
• AddSiteResolvedService<TService>() — registers a scoped factory that dispatches to the keyed service matching the current SiteId.
• AddSiteConventionServices<TServiceInterface>() — convention-based scan: pairs each ISiteProfile with a matching TServiceInterface implementation by namespace proximity and registers them as keyed scoped services.
• SiteProfileScope — AsyncLocal-backed scope that overrides the resolved profile for tests and background jobs.
• SiteProfileOptions.StrictMode — when true, an unknown site code throws MInternalException instead of falling back to "default".
• ISiteProfileBehavior + [SiteProfileBehavior(typeof(T))] — cross-cutting behaviors (e.g. audit logging) applied declaratively to a profile class.
• ISiteEntityProfile<TCore, TSite> — compile-time constraint that enforces TSite : TCore for site entity hierarchies.
• [GenerateSiteProfile(siteId, dbContextType)] — marks a partial ISiteProfile class for source-generator scaffolding of RegisterServices().
• [SiteProfileAlias(targetSiteId)] — declares one site as an alias of another, reusing its service registrations.
• [SiteEntityMap(coreType, siteType, table)] — runtime attribute carrying core↔site entity mapping metadata for source generators.
• SiteProfileStartupValidator — hosted service that validates all registered site profiles at startup and logs failures.
• AddSiteProfileRuleEngineIntegration() — opt-in bridge that registers ISiteProfileFactBagEnricher; injects __site.id and __site.profile into FactBag before rule orchestrator execution.

Configuration

builder.Services.ConfigureSiteProfile(o =>
{
    // Throw on unknown site codes instead of falling back to "default"
    o.StrictMode = true;

    // Assemblies to scan for ISiteProfile implementations (used by SiteProfileStartupValidator)
    o.SiteAssemblies = [typeof(AlphaSiteProfile).Assembly];
});

ConfigureSiteProfile calls services.Configure<SiteProfileOptions>(). Options can also be bound from appsettings.json via the standard services.Configure<SiteProfileOptions>(configuration.GetSection(...)) pattern.

Disable startup validation (testing / dev)

builder.Services.SkipSiteProfileStartupValidation();

Must be called after AddSiteProfile or AddMultiSiteProfiles.

Test isolation with SiteProfileScope

using (SiteProfileScope.ForSite(myTestProfile))
{
    // ISiteProfileResolver.Current returns myTestProfile for this async context
    var result = await sut.CreateOrderAsync(request);
}

API Reference

Samples

• TestProject.Service — multi-site service with Alpha / Bravo / Charlie / Default profiles, [GenerateSiteProfile], [SiteProfileAlias], convention services, and gRPC site resolution

Compatibility

• Target framework: net8.0
• License: Apache-2.0 (OSS)

Related Packages

• Muonroi.Tenancy.Core — provides TenantContext (ambient CurrentTenantId), DefaultTenantIdResolver, and TenantSchemaSelector that SiteProfile builds on top of
• Muonroi.Tenancy.SiteProfile.Web — adds per-site EF Core / Dapper infrastructure, SiteProfileStateMiddleware, hot-reload, and AddSiteDbInfrastructure()
• Muonroi.Tenancy.SiteProfile.SourceGenerators — source generator that scaffolds RegisterServices() for [GenerateSiteProfile]-annotated partial classes

License

Apache-2.0. See LICENSE-APACHE.