OrchardCore Tenants (Multi-tenancy)

This skill guides you through OrchardCore multi-tenancy following project conventions.

OrchardCore runs many isolated sites ("tenants") in one process. Each tenant = a shell: its own DI container, configuration, enabled features, and (optionally) its own database or table prefix. The Default tenant is special — it's created first and manages the others.

Core concepts

Tenant states

Uninitialized → (setup) → Running. Also Initializing, Disabled, Invalid. A tenant configured but not yet set up is Uninitialized and appears in the Tenants list awaiting setup.

Decide what you're doing

Workflow A: create a tenant programmatically

using var shellSettings = _shellSettingsManager
    .CreateDefaultSettings()
    .AsUninitialized()
    .AsDisposable();

shellSettings.Name = "acme";
shellSettings.RequestUrlPrefix = "acme";        // site at /acme
shellSettings.RequestUrlHost = "";              // or a host header

shellSettings["ConnectionString"] = connectionString;
shellSettings["DatabaseProvider"] = "Sqlite";
shellSettings["TablePrefix"] = "acme";
shellSettings["RecipeName"] = "Blog";           // recipe run at setup
shellSettings["Secret"] = Guid.NewGuid().ToString();

await _shellHost.UpdateShellSettingsAsync(shellSettings);

UpdateShellSettingsAsync stamps a new VersionId, saves, and reloads the shell. The tenant is now Uninitialized — it still needs setup (admin user, run recipe), done via the Setup UI/API or ISetupService.

Or via the Tenants API: POST /api/tenants/create then POST /api/tenants/setup.

Workflow B: run code in a tenant scope

To resolve tenant-scoped services (content manager, session, etc.) for a specific tenant:

var shellScope = await _shellHost.GetScopeAsync("acme");
await shellScope.UsingAsync(async scope =>
{
    var contentManager = scope.ServiceProvider.GetRequiredService<IContentManager>();
    // ... work inside the "acme" tenant ...
});

Inside the callback, ShellScope.Services / ShellScope.Current resolve to this tenant. Deferred tasks run on scope disposal. Never resolve tenant services off the root provider — you'll get the wrong (or no) tenant.

Workflow C: pre-configure tenants via configuration

In appsettings.json (or any config source), declare a tenant so it exists before any UI interaction:

{
  "OrchardCore": {
    "acme": {
      "State": "Uninitialized",
      "RequestUrlPrefix": "acme",
      "ConnectionString": "...",
      "DatabaseProvider": "SqlConnection"
    }
  }
}

Per-tenant module config goes under the tenant name too:

{ "OrchardCore": { "Default": { "OrchardCore_Media": { /* ... */ } } } }

Quick Reference

IShellHost

ShellSettings state extensions

AsUninitialized(), AsRunning(), AsDisabled(), plus IsRunning(), IsUninitialized(), etc.

Settings keys (bag)

ConnectionString, DatabaseProvider, TablePrefix, Schema, RecipeName, FeatureProfile, Secret, Category, Description.

Data isolation options

OrchardCore_Tenants config can enforce: RequireTablePrefix, TablePrefixPattern, SchemaPattern (templated with ShellSettings).

Feature Profiles

Feature OrchardCore.Tenants.FeatureProfiles. Profiles are include/exclude rules limiting which features a tenant may enable:

{
  "name": "FeatureProfiles",
  "FeatureProfiles": {
    "minimal": { "FeatureRules": [ { "Rule": "Exclude", "Expression": "OrchardCore.MiniProfiler" } ] }
  }
}

Assign via shellSettings["FeatureProfile"].

Gotchas

• Creating settings ≠ a usable site. A new tenant is Uninitialized; it must be set up (recipe + admin user) before it runs.
• Always using/dispose the ShellSettings from CreateDefaultSettings() (.AsDisposable()).
• Only the Default tenant (ShellSettings.DefaultShellName) can manage other tenants.
• Resolve services through a ShellScope, not the application root provider — tenant DI is a child container per shell.
• Each tenant runs each module's Startup.ConfigureServices independently; services are per-tenant singletons, not app-wide.

References

• references/shells.md — shell lifecycle, scope mechanics, container factory, config sources
• src/docs/reference/modules/Tenants/README.md (repo)
• src/docs/reference/modules/Configuration/README.md (repo)
• src/docs/reference/modules/Shells/README.md (repo)
• AGENTS.md (repo root) — build commands