Area: Optimizely CMS
Applies to versions: 12 and higher
Other versions:
ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.


Recommended reading 
Note: This documentation is for the preview version of the upcoming release of CMS 12/Commerce 14/Search & Navigation 14. Features included here might not be complete, and might be changed before becoming available in the public release. This documentation is provided for evaluation purposes only.

This topic provides an introduction to configuration and options in Optimizely CMS, and describes how options can be configured from various sources such as through code, configuration files, or environment variables.


Configurable settings in Optimizely CMS are exposed as option classes. An option class is basically a POCO C# class that is singleton registered in the DI container in the .NET Core application. More information can be found in Options pattern in ASP.NET Core.

Configuring options programmatically

All options classes are registered in the service container and can therefore be injected into any service that requires this information. This also means that options values can be modified during the configuration phase of the application initialization. One common way to configure an option programmatically is to use the extension method Configure on IServiceCollection as shown below. Another alternative is to register an instance of IConfigureOptions<TOptions> in IOC container.

public void ConfigureServices(IServiceCollection services)
     services.Configure<DataAccessOptions>(o => o.UpdateDatabaseSchema = true);

You can find more detailed information on individual options classes under the relevant options section.

Configuration files

A common way is to have configuration values in an appSettings.json file and then bind the values from the configuration file to option classes. It is possible to have a custom format of the configuration file and bind the values to options as described in Bind hierarchical configuration.

By following the pattern where the first element is "episerver" and then the "product" part is specified, followed by the name of the option and the values for the option, you can get binding to options automatically. Below is an example where SchedulerOptions in configuration section Cms is configured:

  "EPiServer": {
    "CMS": {
      "Scheduler": {
        "Enabled": "false"

For the option class, it is optional to have the class suffix "Options" as above where SchedulerOptions is specified as "Scheduler".

You also may find the following configuration files in an Optimizely CMS installation:

  • module.config. A configuration file installed with the CMS sample templates, showing how to deploy new modules to your solution.

Environment variables

Another alternative to configure options is to have settings applied as environment variables. To get automatically binding of environment variables to options, use the same convention as in configration files such as appsettings.json, but with '__' as a separator. Below is an environment variable that configures SchedulerOptions in configuration section "Cms".


Do you find this information helpful? Please log in to provide feedback.

Last updated: Jul 02, 2021

Recommended reading