Application Configuration and Settings Edit on GitHub


Note! All of the code snippets shown in this topic apply to the JasperRegistry syntax

For application configuration, Jasper supports both the built in .Net Core configuration and a form of strong typed configuration we call the "Settings" model that was originally used in FubuMVC.

Quick Start

Probably the most common scenario is to have a single configuration file mapped to a single object:

  1. Add a class that ends with Settings to your project, e.g. MySettings.cs.
  2. Add a json file that has properties that match your Settings class.
  3. Use the Build method to tell Jasper about your configuration file.
  4. Include your Settings class in the constructor of a class and Jasper will automatically inject the settings object

public class MyApp : JasperRegistry
{
    public MyApp()
    {
        Configuration.AddJsonFile("mysettings.json");
    }
}

public class SettingsTest
{
    private readonly MySettings _settings;

    public SettingsTest(MySettings settings)
    {
        _settings = settings;
    }
}

Configuration Lifecycle

Application configuration can come from a mix of the built in .Net Core configuration sources and programmatic options set in either your JasperRegistry or a loaded extension. While you make all the declarations in your JasperRegistry class, Jasper takes some steps to execute the usage of configuration options at bootstrapping time like so:

  1. Build out the .Net Core IConfigurationRoot object based on the sources added to JasperRegistry.Configuration.
  2. Loads the default data for known Settings types
  3. Apply all the JasperRegistry.Settings.Alter() or Replace() delegates from registered extensions in the order that they were registered
  4. Apply all the JasperRegistry.Settings.Alter() or Replace() delegates configured in your JasperRegistry in the order that they were registered to ensure that the application specific options always win out over the base options or options coming from an extension
  5. Finally, apply all the JasperRegistry.Settings.With() delegates configured in your JasperRegistry to use the final, configured versions of
    Settings objects to alter your application setup

Add Configuration Sources

Jasper uses the .NET Core ConfigurationBuilder to get config data and bind it to objects.


Configuration.SetBasePath("path")
    .AddJsonFile("myconfig.json")
    .AddJsonFile("myotherconfig.json.config")
    .AddEnvironmentVariables();

If you need to bind a settings class that does not follow the convention of ending with Settings then use the Configure method to tell Jasper which class you want to bind.


Settings.Configure<Colors>();

If a settings class needs additional information to bind correctly, such as being in a nested sub-section, use the Configure method.


Settings.Configure<MySettings>(_ => _.GetSection("subsection"));

Modify Settings

It may be necessary to modify a settings object after it has been loaded from configuration. Settings can be altered:


Settings.Alter<MySettings>(_ =>
{
    _.SomeSetting = 5;
});

// or additionally use IConfiguration
Settings.Alter<MySettings>((config, settings) =>
{
    settings.SomeSetting = int.Parse(config["SomeKey"]);
});


or completely replaced:


Settings.Replace(new MySettings
{
    SomeSetting = 3,
    OtherSetting = "blue"
});

Modify Application

The JasperRegistry (or the application that inherits from JasperRegistry) can be modified using loaded settings:


public class MyApplication : JasperRegistry
{
    public bool MyBoolean { get; set; }

    public MyApplication()
    {
        Settings.With<MySettings>(_ =>
        {
            if (_.SomeSetting == 1)
            {
                MyBoolean = true;
            }
        });
    }
}