Application Configuration and Settings Edit on GitHub


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

Because Jasper applications are also ASP.Net Core applications, the built in ASP.Net Core configuration just works, and that is configured the way you're probably already used to using with the IWebHostBuilder model.

On top of that, Jasper supports a form of strong typed configuration we call the "Settings" model that was originally used in FubuMVC. This is a lighterweight alternative to ASP.Net Core's IOptions model (which is also usable with Jasper).

Settings 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()
    {
        Hosting(x => x.ConfigureAppConfiguration((context, config) => config.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. Loads the default data for known Settings types by looking first for a configuration section named with the prefix of your Settings type name.
  2. Apply all the JasperRegistry.Settings.Alter() or Replace() delegates from registered extensions in the order that they were registered
  3. 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

Alter the Settings Objects with IConfiguration

If you're already using an ASP.Net Core Startup class for configuring your application, the easiest way to configure Jasper Settings objects based on that configuration is to just inject that class into your Startup and work directly against it as shown in this example:


public class Startup
{
    private readonly JasperOptions _options;
    private readonly IConfiguration _configuration;
    private readonly IHostingEnvironment _hosting;

    public Startup(JasperOptions options, IConfiguration configuration, IHostingEnvironment hosting)
    {
        _options = options;
        _configuration = configuration;
        _hosting = hosting;
    }

    public void Configure(IApplicationBuilder app)
    {
        // modify the JasperOptions with your IConfiguration
        // and IHostingEnvironment
    }


}

Otherwise, you can do this as well within your JasperRegistry class that defines your application like this simple example that just plucks a value from configuration and applies that to the ServiceName for the application:


public class UsingConfigApp : JasperRegistry
{
    public UsingConfigApp()
    {
        // Ignore this please;)
        Handlers.DisableConventionalDiscovery();


        Hosting( x=> x.ConfigureAppConfiguration((_, config) =>
        {
            config.AddInMemoryCollection(new Dictionary<string, string> {{"AppName", "WocketInMyPocket"}});
        }));


        Settings.Alter<JasperOptions>((c, options) => options.ServiceName = c.Configuration["AppName"]);
    }
}

Modify Settings

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


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

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


or completely replaced:


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