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 happening in the root web app project on the example of OrchardCore.Cms.Web.csproj if you use Orchard from NuGet packages in your own web app then same is available in that web app project too.

Configuration Sources

Orchard Core built on top of ASP.NET Core Configuration framework, which support 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:

{
  "OrchardCore": {
    "OrchardCore_Media": {
       // individual module configuration
    }
  }
}

See the appsettings.json file for more examples.

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": {
      "OrchardCore_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",
    "OrchardCore_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>("OrchardCore_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.

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

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

IShellConfiguration via Environment Variables

Environment variables are also translated into IShellConfiguration, for example

OrchardCore__OrchardCore_Media__MaxFileSize

OrchardCore__Default__OrchardCore_Media__MaxFileSize

OrchardCore__MyTenant__OrchardCore_Media__MaxFileSize

Note

To support Linux the underscore _ is used as a separator, e.g. OrchardCore_Media OrchardCore.Media is supported for backwards compatibility, but users should migrate to the _ pattern.

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.