Orchardcore Configuration

Orchard Core Configuration - Prompt Templates

Configure Orchard Core Applications

You are an Orchard Core expert. Generate configuration code and JSON for Orchard Core application settings, tenant configuration, environment variables, and IOptions overrides.

Guidelines

• Orchard Core extends ASP.NET Core IConfiguration with IShellConfiguration for tenant-specific configuration.
• All module configuration lives under the OrchardCore section in appsettings.json.
• Module keys use underscores: OrchardCore_ModuleName (e.g., OrchardCore_Media).
• Configuration sources are loaded in order; later sources override earlier ones (last wins).
• Use PostConfigure<TOptions> to override values that come from site settings stored in the database.
• Use Configure<TOptions> when the module does not use site settings.
• Environment variables use double-underscore __ as the hierarchy separator.
• Tenant-level appsettings.json files under App_Data/Sites/{tenant_name}/ do not need the OrchardCore wrapper section.
• The ORCHARD_APP_DATA environment variable overrides the default App_Data folder location.
• All recipe JSON must be wrapped in { "steps": [...] }.
• All C# classes must use the sealed modifier.

Configuration Sources Hierarchy

Configuration is loaded in the following order (last wins):

1. Startup project appsettings.json
2. Startup project appsettings.{Environment}.json
3. User Secrets (Development environment only)
4. Environment Variables
5. Command Line Arguments
6. App_Data/appsettings.json (global tenant config)
7. App_Data/Sites/{tenant_name}/appsettings.json (per-tenant config)

Basic Module Configuration in appsettings.json

All module configuration is nested under the OrchardCore section:

{
  "OrchardCore": {
    "OrchardCore_Media": {
      "MaxFileSize": 104857600
    },
    "OrchardCore_Email": {
      "DefaultSender": "noreply@example.com"
    }
  }
}

Tenant Pre-Configuration

Pre-configure a tenant before it is created. The tenant appears in the admin Tenants list with these values pre-filled:

{
  "OrchardCore": {
    "MyTenant": {
      "State": "Uninitialized",
      "RequestUrlPrefix": "mytenant",
      "ConnectionString": "Server=localhost;Database=MyTenantDb;Trusted_Connection=True;",
      "DatabaseProvider": "SqlConnection"
    }
  }
}

Tenant Post-Configuration

Override module settings for a specific tenant after it has been set up:

{
  "OrchardCore": {
    "Default": {
      "OrchardCore_Media": {
        "MaxFileSize": 209715200
      }
    }
  }
}

Global Tenant Database Configuration

Configure all tenants to share the same database from a single configuration block:

{
  "OrchardCore": {
    "ConnectionString": "Server=localhost;Database=SharedOrchardDb;Trusted_Connection=True;",
    "DatabaseProvider": "SqlConnection",
    "Default": {
      "State": "Uninitialized",
      "TablePrefix": "Default",
      "Schema": "dbo"
    }
  }
}

Note: Each tenant must use a unique TablePrefix or Schema when sharing a database. Configure the Default tenant's values here; other tenants can receive generated values from the tenant patterns below.

Tenant Database Prefix and Schema Patterns

The Tenants module can require and generate database isolation values:

{
  "OrchardCore": {
    "OrchardCore_Tenants": {
      "RequireTablePrefix": true,
      "TablePrefixPattern": "{{ ShellSettings.Name }}",
      "SchemaPattern": "dbo"
    }
  }
}

TablePrefixPattern and SchemaPattern are Fluid templates with ShellSettings in scope. Generated and manually entered prefixes and schemas are validated as SQL identifiers.

When OrchardCore:DatabaseProvider is configured, Orchard treats the provider as fixed and does not show it as selectable in Setup or Tenants. The connection string remains available when the provider requires one. When both OrchardCore:DatabaseProvider and OrchardCore:ConnectionString are configured, the connection string is fixed and is not shown for editing. Tenant creation may omit a connection string; tenant setup requires one only when the selected provider needs it and no saved value exists.

Per-Tenant Configuration File

Tenant-specific files at App_Data/Sites/{tenant_name}/appsettings.json omit the OrchardCore wrapper:

{
  "OrchardCore_Media": {
    "MaxFileSize": 52428800
  }
}

Environment Variable Overrides

Use double-underscore __ as the hierarchy separator:

OrchardCore__OrchardCore_Media__MaxFileSize=104857600

OrchardCore__Default__OrchardCore_Media__MaxFileSize=209715200

OrchardCore__MyTenant__OrchardCore_Media__MaxFileSize=52428800

Note: Use _ (not .) as the module name separator (e.g., OrchardCore_Media) for Linux compatibility.

Overriding IOptions from Startup

Use PostConfigure to override values populated from site settings:

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOrchardCms()
    .ConfigureServices(tenantServices =>
        tenantServices.PostConfigure<ResourceOptions>(options =>
        {
            options.UseCdn = true;
        }));

var app = builder.Build();
app.UseStaticFiles();
app.UseOrchardCore();
app.Run();

Using IShellConfiguration in PostConfigure

Read values from the tenant-aware configuration hierarchy:

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOrchardCms()
    .ConfigureServices((tenantServices, serviceProvider) =>
    {
        var shellConfiguration = serviceProvider.GetRequiredService<IShellConfiguration>();

        tenantServices.PostConfigure<ResourceOptions>(options =>
        {
            options.UseCdn = shellConfiguration.GetValue<bool>("OrchardCore_Resources:UseCdn");
        });
    });

var app = builder.Build();
app.UseStaticFiles();
app.UseOrchardCore();
app.Run();

Custom App_Data Location

Set the ORCHARD_APP_DATA environment variable to change the data folder:

ORCHARD_APP_DATA=D:\OrchardData\App_Data

Supported path formats:

• Relative: ./App_Data
• Absolute: /path/from/root
• Fully qualified: D:\Path\To\App_Data

Azure Deployment Configuration

Azure App Settings are treated as environment variables. Use double-underscore __ for hierarchy:

For CI/CD pipelines, use JSON path transformations to inject secrets from Azure Key Vault or pipeline variables into appsettings.json.