1. Stay tuned
    2. Blog
    3. 2016
    • Published
    • 4 min

    Configuration options for Episerver sites

    A look at the most common ways of storing configuration in Episerver projects, with pros and cons for each one.

    By Arild Henrichsen

    Configuration settings are used in nearly all Episerver projects - some are available for editors, some are hidden away in Admin mode, and others are stored in .config files. Some help build menus, some determine page functionality, others are used as parameters for various internal services/background jobs.

    TL;DR - It's up to the developer to decide the best placement for each config setting. With a conscious strategy for your site's config, you will:

    • have a less cluttered UI for editors
    • avoid exposing site-critical settings unnecessarily
    • require less maintenance downtime

     

    1. Config as page type properties

    Episerver page type property settings

    Properties on a particular page type (most commonly a landing page such as the StartPage) are used to store settings that are used globally, or used for specific sub-sections.

    Suitable for:

    • Settings that editors might want to experiment with, such as the CSS theme for a sub-section, or the default amount of items in a carousel.
    • Settings that editors might need to change over time, such as a pointer to the news archive root. 
    • In essence, non-critical settings that don't bring the site down.
     

    Defining page type properties:

    public class StartPage
{
    [Display(Order = 10, GroupName = TabNames.Configuration)]
    [Required]
    public virtual PageReference BlogRootPage { get; set; }
}
     

    Retrieving page type properties:

    IContentRepository contentRepository = ServiceLocator.Current.GetInstance<IContentRepository>();
StartPage startPage = contentRepository.Get<StartPage>(ContentReference.StartPage);
var blogRootPage = contentRepository.GetDefault<BlogRootPage>(startPage.BlogRootPage);


    Pros:

    • Property DEFINITIONS (name and type) are included in code, enabling strongly-typed reference.
    • Value changes take effect immediately, and don't trigger a site restart.
    • Value changes can easily be made by editors when necessary.
    • Properties can be hidden from edit view (the setting will be in effect, but it won't show up in any tab).

    Cons:

    • Property VALUES are not defined in code, but rather stored in the database.
    • Property values have to be manually set for every environment (unless the database is migrated between environments on deploy).
    • Can clutter up the UI and confuse users. Most common approach is to create a "Configuration" tab to hold the settings (remember to tell the editors not to mess with them!)
    • Typically requires retrieving the page via a ContentLoader or ContentRepository instance.
     
     

    2. Plug-in Settings

    Episerver Admin plugin settings
     

    Each assembly in your Episerver project can have its own plug-in settings. Only Admin users can modify these settings:

    Config tab > Plug-in Manager > [Your assembly] > Configuration. 


    Suitable for:

    • Static settings that are unlikely to change over time ("set and forget").
    • Settings that should be available to a select few users who understand what they affect.


    Defining a plug-in setting:

    using EPiServer.PlugIn;
 
namespace Demo.Settings
{
    [GuiPlugIn(Area = PlugInArea.None, DisplayName = "My Plugin Settings")]
    public class MyPluginSettings: IMyPluginSettings: 
    {
	private static MyPluginSettings _instance;
           
	[PlugInProperty(Description = "Unpublish expired course pages", AdminControl = typeof(CheckBox), AdminControlValue = "Checked")]
        public bool UnpublishExpiredCoursePages{ get; set; }
	
	public MyPluginSettings()
        {
            PlugInSettings.SettingsChanged += new EventHandler(PlugInSettings_SettingsChanged);
        }

	private static void PlugInSettings_SettingsChanged(object sender, EventArgs e)
        {
            _instance = null;
        }

        public static MyPluginSettings Instance
        {
            get
            {
                if (_instance == null)
                {
                    _instance = new MyPluginSettings();
                }
                PlugInSettings.AutoPopulate(_instance);
                return _instance;
            }
        }

    }
}
    (Note: This only defines the setting, not its value.)

    Retrieving a plug-in setting:

    bool unpublishExpiredCoursePages = MyPluginSettings.Instance.UnpublishExpiredCoursePages;
     

    Pros:

    • Setting DEFINITIONS (name and type) are included in code, enabling strongly-typed reference.
    • Value changes don't trigger a site restart.
    • Can be accessed globally, without having to retrieve them from a page
    • Hidden away in Admin mode where users are unlikely to make changes by mistake.

    Cons:

    • Setting VALUES are not defined in code, but rather stored in the database.
    • Setting values have to be manually set for every environment (unless the database is migrated between environments on deploy).
    • Value changes should be checked into code repository to avoid being overwritten on next deploy. 

     

    3. AppSettings (web.config)

    <appSettings> is a section in your web.config. 

    Suitable for:

    • Static settings that are unlikely to change over time ("set and forget").
    • Settings that are unsuitable to present in an UI (or would require a custom property type to do so).
    • Settings that vary between deploy environments and need config transformation.

     

    Defining appSettings: 

    <appSettings>
     <add key="SomeExternalServiceUrl" value="https://foo.com/bar" />
</appSettings>
     

    Retrieving appSettings:

    var externalServiceUrl = System.Configuration.ConfigurationManager.AppSettings["SomeExternalServiceUrl"];

     

    Pros:

    • Can be config transformed for different environments.
    • Can't be tampered with by edit/admin users.
    • Doesn't clutter the UI.
    • Setting values are included when deploying the site, no need to manually set the values for each environment.

    Cons:

    • Value changes must be checked into code repository to avoid being overwritten on next deploy.
    • Value changes trigger a site restart.
    • String-based key lookup, does not enable strongly-typed reference.