Lockjaw.Core 2.0.2.58

Lockjaw.Core

The shared model behind Lockjaw: it reads environment-prefixed settings from app.config and appsettings.json, resolves each key to the environment you have selected, and defines the snapshot the Lockjaw app publishes and clients read.

Most applications want Lockjaw.Client, not this package. Reference Lockjaw.Core directly only when you are hosting the resolution yourself or building tooling on top of Lockjaw.

netstandard2.0, with no UI dependency.

What it does

Keys are prefixed with the environment they belong to. Lockjaw groups the prefixed keys into one logical setting holding every environment's value:

<add key="Development_ApiUrl" value="https://localhost:5001/api" />
<add key="Production_ApiUrl"  value="https://api.contoso.com/v2" />

becomes a single ApiUrl entry that resolves to whichever environment is selected.

Hosting it yourself

using var host = new LockjawHost(new LockjawOptions
{
    InstanceName = "default",
    Environments =
    {
        new EnvironmentDefinition("Local", "Local_"),
        new EnvironmentDefinition("Test",  "Test_", "#7C3AED")
    },
    DefaultEnvironment = "Development"
}).Initialize();

var apiUrl = host.Catalog.Get("ApiUrl");
host.Catalog.SelectAll("Test");

Initialize() reads the configuration, layers on any saved edits, restores the remembered selections, and publishes a snapshot. Every later change republishes automatically.

Reload() re-reads the configuration files and rebuilds the catalog, keeping the user's edits and chosen environments — use it when a file has changed on disk. The sources are read in full before anything is discarded, so a file that has become unreadable throws and leaves the previous state exactly as it was.

The host also watches those files and raises ConfigurationChanged once they settle — debounced, because editors write a file in several steps. It reports rather than reloads, so the owner picks the moment; a UI reloads on its own thread, where rebuilding what is on screen is safe:

host.ConfigurationChanged += (s, e) => dispatcher.BeginInvoke(new Action(() => host.Reload()));

Turn it off with LockjawOptions.WatchConfigurationFiles, or change the settle time with WatchQuietPeriodMs.

Key types

Colon-delimited paths

JsonConfigSource flattens nested objects and arrays into colon paths, as .NET configuration does — { "Logging": { "Level": "Debug" } } becomes Logging:Level, and array items take their index. SettingsCatalog will strip an environment prefix from any segment of such a path, so either the whole subtree or a single leaf can carry it.

Environments are open-ended

Development_ and Production_ are only the defaults. Declare whatever you use — Local_, Test_, Staging_ — and Lockjaw picks those keys up. The longest matching prefix wins, so Test_ and Test_Local_ can coexist. A key with no value in the default environment falls back to the first declared environment it does have.

Editing

The catalog is editable, and edits never rewrite your configuration files — they are held as a diff and persisted separately, so config keeps its comments and every value can be reverted:

using (catalog.BeginEdit())          // one change notification for the batch
{
    catalog.SetValue("ApiUrl", SettingKind.AppSetting, "Local", "http://localhost:5000");
    catalog.SetValue("ApiUrl", SettingKind.AppSetting, "Test",  "https://test.contoso.com");
}

catalog.IsOverridden("ApiUrl", SettingKind.AppSetting, "Local");   // differs from config?
catalog.ConfigValue("ApiUrl", SettingKind.AppSetting, "Local");    // what config actually says
catalog.RevertValue("ApiUrl", SettingKind.AppSetting, "Local");    // put it back

Import and export

var bundle = SettingsTransfer.Export(catalog, "default", DateTime.UtcNow);
SettingsTransfer.Write(bundle, path);

var result = SettingsTransfer.Import(catalog, SettingsTransfer.Read(path),
    new ImportOptions { Mode = ImportMode.Merge });

Values naming an environment the target does not declare are skipped and reported rather than creating settings nothing can display.

Notes

• Persistence is best effort: a locked or corrupt store costs the saved choices, never the host app.
• A malformed configuration section makes .NET throw while parsing it; local-config reads treat that as "no values" rather than crashing.
• LockjawHost is IDisposable — disposing saves edits and selections.

See also

• Lockjaw.Client — what applications reference to read the resolved values.
• The Lockjaw app — the tray UI over this model.