Skip to content

Configuration

Orchard Core extends ASP.NET Core IConfiguration with IShellConfiguration to allow tenant-specific configuration on top of the application-wide one.

To learn more about ASP.NET Core IConfiguration visit https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration.

Note that while this documentation page explains configuration in the root web app project by using OrchardCore.Cms.Web.csproj as an example, if you use Orchard from NuGet packages in your own web app, the same is available in that web app project too.

Configuration Sources

Orchard Core is built on top of the ASP.NET Core configuration framework, which supports a variety of different configuration options. Developers are not limited to using a single configuration source. In fact, several may be set up together such that a default configuration is overridden by settings from another source if they are present.

The Configuration Sources are loaded in the order described in Configuration Sources Order below.

Note

The IShellConfiguration patterns in the appsettings.json examples below will only work for modules that specifically support such configuration. You can check out the given module's code or documentation to see if this is the case.

IShellConfiguration in the OrchardCore.Cms.Web.csproj Startup Project

Orchard Core stores all Configuration data under the OrchardCore section in appsettings.json files:

{
  "OrchardCore": {
      // module configurations
  }
}

Each Orchard Core module has its own configuration section under the OrchardCore section. Sections are grouped by service, with a nested section for each provider of the service, so that all the settings of a service are located together. For instance, the Azure Blob Storage configuration of the Media module is located in the OrchardCore:Media:Azure section, next to the OrchardCore:Media:AmazonS3 section, and the SMTP and Azure email providers are configured in the OrchardCore:Email:Smtp and OrchardCore:Email:Azure sections:

{
  "OrchardCore": {
    "Media": {
      // Media module configuration
      "Azure": {
        // Azure Blob Storage media configuration
      }
    }
  }
}

See the appsettings.json file for more examples.

Tip

When creating your own modules, follow the same convention: name your configuration sections without an OrchardCore_ prefix, and group them by service using nesting, e.g. OrchardCore:MyService:MyProvider. This keeps environment variable names like OrchardCore__MyService__MyProvider__MySetting short.

Warning

Tenant specific sections share the same path as the configuration sections, e.g. OrchardCore:MyTenant. Avoid giving a tenant the name of a configuration section, like Media or Email.

Deprecated section names

The configuration sections used to be prefixed with OrchardCore_, and used underscores instead of nesting, e.g. OrchardCore:OrchardCore_Media_Azure. These names are deprecated but are still supported, in addition to the current names. When a setting is defined using both names, the value defined with the current name is used, and an array defined with the current name replaces the array defined with the deprecated name. The deprecated names will be removed in a future major version, so you should rename them to the current names.

Deprecated section name Current section name
OrchardCore_Admin Admin
OrchardCore_Apis_GraphQL Apis:GraphQL
OrchardCore_AutoSetup AutoSetup
OrchardCore_AzureAISearch Search:AzureAISearch
OrchardCore_BackgroundService BackgroundService
OrchardCore_ContentLocalization_CulturePickerOptions ContentLocalization:CulturePickerOptions
OrchardCore_ContentTypes ContentTypes
OrchardCore_Data_Sqlite Data:Sqlite
OrchardCore_Data_TableOptions Data:TableOptions
OrchardCore_DataProtection_Azure DataProtection:Azure
OrchardCore_Documents Documents
OrchardCore_DynamicCache DynamicCache
OrchardCore_Elasticsearch Search:Elasticsearch
OrchardCore_Email_Azure, OrchardCore_Email_AzureCommunicationServices Email:Azure
OrchardCore_Email_Smtp, OrchardCore_Email Email:Smtp
OrchardCore_Facebook Facebook
OrchardCore_GitHub Authentication:GitHub
OrchardCore_Google Authentication:Google
OrchardCore_HealthChecks HealthChecks
OrchardCore_KeyVault_Azure KeyVault:Azure
OrchardCore_Liquid Liquid
OrchardCore_Localization_CultureOptions Localization:CultureOptions
OrchardCore_Markdown Markdown
OrchardCore_Media Media
OrchardCore_Media_AmazonS3 Media:AmazonS3
OrchardCore_Media_AmazonS3_ImageSharp_Cache Media:AmazonS3:ImageCache
OrchardCore_Media_Azure Media:Azure
OrchardCore_Media_Azure_ImageSharp_Cache Media:Azure:ImageCache
OrchardCore_Media_Slugify Media:Slugify
OrchardCore_Microsoft_Authentication_AzureAD Authentication:AzureAD
OrchardCore_Microsoft_Authentication_MicrosoftAccount Authentication:MicrosoftAccount
OrchardCore_Navigation Navigation
OrchardCore_Notifications Notifications
OrchardCore_ReCaptcha ReCaptcha
OrchardCore_Redis Redis
OrchardCore_Resources Resources
OrchardCore_ReverseProxy ReverseProxy
OrchardCore_Roles Roles
OrchardCore_Security Security
OrchardCore_Setup Setup
OrchardCore_Shells_Azure Shells:Azure
OrchardCore_Shells_Database Shells:Database
OrchardCore_Sms_AzureCommunicationServices Sms:Azure
OrchardCore_Tenants Tenants
OrchardCore_Users Users
OrchardCore_Workflows Workflows
OrchardCore_X, OrchardCore_Twitter X
OrchardCore_YesSql YesSql

For instance, the OrchardCore__OrchardCore_Media_Azure__ConnectionString environment variable becomes OrchardCore__Media__Azure__ConnectionString.

IntelliSense and validation of the appsettings.json files

The Orchard Core packages that read a configuration section include a ConfigurationSchema.json file describing their sections. This file is declared as a JSON schema segment by the package, and flows to the projects referencing the package, even indirectly, for instance through the OrchardCore.Application.Cms.Targets package. Visual Studio merges the schemas of the referenced packages to provide IntelliSense, descriptions and validation when editing these files of your web project:

  • appsettings.json and appsettings.{Environment}.json.
  • App_Data/appsettings.json and App_Data/appsettings.{Environment}.json, the global tenant configuration files, which the OrchardCore.Application.Cms.Targets package keeps in the project for this purpose.

Besides the section and setting names, the editor suggests the known values of settings like the database providers, the setup recipes, the time zones, the cultures, the AWS regions, or the security headers. The deprecated section names are flagged as such, and are not suggested.

Note

Visual Studio applies the same schema to all the appsettings.json files of a project, so the tenant specific App_Data/Sites/{tenant}/appsettings.json files, whose sections are not nested in an OrchardCore section, don't get IntelliSense. Visual Studio Code doesn't support JSON schema segments yet.

Tip

A module can describe its own configuration sections the same way. Include a ConfigurationSchema.json file describing the sections under the OrchardCore property at the root of the NuGet package, and a buildTransitive/{PackageId}.targets file declaring it as a JSON schema segment:

<Project>
  <ItemGroup>
    <JsonSchemaSegment Include="$(MSBuildThisFileDirectory)..\ConfigurationSchema.json" FilePathPattern="appsettings\..*json" />
  </ItemGroup>
</Project>

Tenant Pre-configuration

To pre configure the setup values for a tenant before it has been created you can specify a section named for the tenant, with a State value of Uninitialized

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

The preconfigured tenant will then appear in the Tenants list in the admin, and these values will be used when the tenant is setup.

Tenant Post-configuration

To configure the values for a tenant after it has been created you can specify a section named for the tenant, without having to provide a state value.

{
  "OrchardCore": {
    "Default": {
      "Media": {
         // specific tenant configuration
      }
    }
  }
}

Global tenant data access configuration

What if you want all tenants to access the same database? The corresponding configuration can be kept in a single place, as opposed to setting up the same connection string for all tenants one by one, as following:

{
  "OrchardCore": {
    "ConnectionString": "...",
    "DatabaseProvider": "SqlConnection",
    "Tenants": {
      "RequireTablePrefix": true,
      "TablePrefixPattern": "{{ ShellSettings.Name }}",
      "SchemaPattern": "dbo"
    },
    "Default" : {
      "State": "Uninitialized",
      "TablePrefix": "Default"
    }
  }
}

Notes on the above configuration:

  • Be aware that while you can use the same configuration keys for tenants, as demonstrated previously, this is in the root of the OrchardCore section.
  • Add the connection string for the database to be used by all tenants.
  • DatabaseProvider should correspond to the database engine used, the sample being one for SQL Server.
  • Default:TablePrefix configures the table prefix used by the Default tenant itself so its tables stay isolated from other tenants in the shared database. It does not automatically populate or require prefixes for tenants created later from the admin or API, and by itself it does not lock or hide database provider and connection settings for other tenants.
  • OrchardCore:Tenants:RequireTablePrefix can be enabled to require a table prefix whenever a new tenant is created, or an uninitialized tenant is edited, with a database provider that supports table prefixes.
  • For providers that require a connection string, Orchard only treats the root database configuration as preset when both DatabaseProvider and ConnectionString are configured. Setting only DatabaseProvider does not lock setup or tenant database fields and does not bootstrap YesSql for the setup shell.
  • OrchardCore:Tenants:TablePrefixPattern can be used to generate each tenant's TablePrefix automatically so the admin and API no longer need manual input for it. The pattern uses Fluid syntax with ShellSettings in scope, for example {{ ShellSettings.Name }}.
  • OrchardCore:Tenants:SchemaPattern works the same way for the tenant Schema, for example "dbo" or {{ ShellSettings.Name }}.
  • Pattern-generated and manually entered TablePrefix and Schema values are validated as SQL identifiers. Use only letters, numbers, and underscores, and start the value with a letter or underscore.
  • When a pattern is configured, Orchard uses the generated value instead of any posted manual value for tenant creation, editing uninitialized tenants, and tenant setup.
  • This shared-database pattern applies to providers such as SQL Server, MySQL, and PostgreSQL. The built-in SQLite provider does not use the root ConnectionString setting for tenant data and is not configured as a single shared .db file with per-tenant prefixes through this pattern.

This way, the app can be easily moved between environments (like a staging and production one) by configuring the corresponding database's settings in the given environment. Tenants' shell settings won't contain this information, all tenants will use the same, global configuration.

A related topic is Shells Configuration Providers. See especially the section about Database Shells Configuration Provider, on how to keep all shell configuration in the database.

IOptions Configuration

You can also configure IOptions from code in the web project's Startup class as explained in the ASP.NET documentation.

A lot of Orchard Core features are configured through the admin UI with site settings stored in the database and/or expose configuration via IOptions. If you wish to override the site settings or default settings, you can do this with your own configuration code.

For example, the Resource module allows CDN configuration via the ResourceOptions class which by default is populated from the given tenant's site settings, as set on the admin. However, you can override the site settings from the Startup class like this (note that we use PostConfigure to override the site settings values but if the module doesn't use site settings you can just use Configure):

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

Or, if you want to make use of IShellConfiguration as seen above:

services
    .AddOrchardCms()
    .ConfigureServices((tenantServices, serviceProvider) =>
    {
        // Instead of IShellConfiguration you could fetch the configuration 
        // values from an injected IConfiguration instance here too. While that 
        // would also allow you to access standard ASP.NET Core configuration 
        // keys it won't have support for all the hierarchical sources 
        // detailed above.
        var shellConfiguration = serviceProvider.GetRequiredService<IShellConfiguration>();

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

Note

On the admin there will be no indication that this override happened, and the value displayed there will still be the one configured in site settings, so if you choose to do this you'll need to let your users know.

Live tenant options with IOptionsMonitor

Orchard Core keeps the standard IOptionsMonitor<TOptions> implementation. To make a specific options type refresh after tenant data changes, opt it in by registering Orchard Core's signal-backed IOptionsChangeTokenSource<TOptions>.

Use IOptionsMonitor<TOptions> when an options type is built from mutable tenant state such as site settings, documents, or other values that can change from the admin UI without restarting the application. Continue to use IOptions<TOptions> for values that are effectively immutable for the lifetime of the tenant shell, such as options coming only from startup code or static configuration.

When a settings editor updates data that feeds an options type, request an invalidation through IOptionsUpdateNotifier. Orchard Core defers the notification until the current document session commits successfully, so failed or rolled-back updates do not refresh the options cache.

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddSignalOptionsChangeTokenSource<MyOptions>();
    }
}

public sealed class MySettingsDisplayDriver : SiteDisplayDriver<MySettings>
{
    private readonly IOptionsUpdateNotifier _optionsUpdateNotifier;

    public MySettingsDisplayDriver(IOptionsUpdateNotifier optionsUpdateNotifier)
    {
        _optionsUpdateNotifier = optionsUpdateNotifier;
    }

    public override async Task<IDisplayResult> UpdateAsync(ISite site, MySettings settings, UpdateEditorContext context)
    {
        await context.Updater.TryUpdateModelAsync(settings, Prefix);

        if (context.Updater.ModelState.IsValid)
        {
            _optionsUpdateNotifier.RequestUpdate<MyOptions>();
        }

        return await EditAsync(site, settings, context);
    }
}

public sealed class MyService
{
    private readonly IOptionsMonitor<MyOptions> _options;

    public MyService(IOptionsMonitor<MyOptions> options)
    {
        _options = options;
    }

    public string GetValue() => _options.CurrentValue.SomeSetting;
}

Queue update requests only after validation succeeds and only for the options types affected by the change. The notifier is intentionally one-way: Orchard Core coalesces requests per shell scope and dispatches them after commit, so there is no RemoveUpdateRequest() API to cancel earlier requests.

For named options, register IOptionsChangeTokenSource<TOptions> manually with SignalOptionsChangeTokenSource<TOptions> for the matching name and call RequestUpdate<TOptions>(name) with the same value.

In multi-node environments, use a distributed ISignal implementation such as the Redis Bus feature from OrchardCore.Redis. This ensures every node invalidates its local IOptionsMonitor<TOptions> cache and rebuilds the updated options from the committed tenant state.

ORCHARD_APP_DATA Environment Variable

The location of the App_Data folder can be configured by setting the ORCHARD_APP_DATA environment variable. Paths can be relative to the application path (./App_Data), absolute (/path/from/root), or fully qualified (D:\Path\To\App_Data). If the folder does not exist the application will attempt to create it.

IShellConfiguration in the Global Tenant Configuration App_Data/appsettings.json

These settings can also be located in an App_Data/appsettings.json folder (not created by default), and any settings specified there will override settings from the Startup Project.

IShellConfiguration in the Individual Tenants Folder

These settings are mutable and written during the setup for the tenant. For this reason, reading from Environment Name is not supported. Additionally, these appsettings.json files do not need the OrchardCore section.

{
  "Media": {
     // specific tenant configuration
  }
}

IShellConfiguration via Environment Variables

Environment variables are also translated into IShellConfiguration, for example

OrchardCore__Media__MaxFileSize

OrchardCore__Default__Media__MaxFileSize

OrchardCore__MyTenant__Media__MaxFileSize

Note

A double underscore __ separates each level of the configuration path, e.g. OrchardCore__Media__Azure__ConnectionString for the OrchardCore:Media:Azure:ConnectionString setting.

Configuration Sources Order

By default an Orchard Core site will use CreateDefaultBuilder in the Startup Project's Program.cs which will load IConfiguration in the following order

  1. The Startup ASP.NET Core Project, e.g. OrchardCore.Cms.Web.csproj, appsettings.json, or by environment appsettings.Development.json.
  2. User Secrets (if environment is Development)
  3. Environment Variables, or AppSettings as Environment Variables via Azure.
  4. Command Line Args
  5. IShellConfiguration will then add these
    1. Global Tenant Configuration App_Data/appsettings.json
    2. Individual Tenant Configuration files located under each Tenant Folder in the App_Data/Sites/{tenant_name}/appsettings.json folder.

Note

Configurations with the same key that are loaded later take precedence over those which were loaded earlier (last wins).

Configuration during Deployment

Azure App Settings are supported as Environment Variables on a Windows Environment, or a Linux Environment.

Azure DevOps, or other CI/CD pipelines, are supported, on all platforms, and Json Path Transformations can be used to transform appsettings.json files and provide app secrets from pipeline variables, or secret key stores like Azure Key Vault.

If building with the nightly dev builds from the preview package feed, the CI/CD pipeline will need to use a NuGet.Config with the location of the MyGet package feed.

<configuration>
  <packageSources>
    <add key="nuget" value="https://api.nuget.org/v3/index.json"/>
    <add key="preview" value="https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json" />
  </packageSources>
</configuration>

Alternate locations

The IShellConfiguration values stored in the App_Data folder, and individual tenants appsettings.json files, can also be stored in alternate locations.

Refer to the Shells Section for more details on this.