Lockjaw.Client 2.0.2.66

dotnet add package Lockjaw.Client --version 2.0.2.66
                    
NuGet\Install-Package Lockjaw.Client -Version 2.0.2.66
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Lockjaw.Client" Version="2.0.2.66" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Lockjaw.Client" Version="2.0.2.66" />
                    
Directory.Packages.props
<PackageReference Include="Lockjaw.Client" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Lockjaw.Client --version 2.0.2.66
                    
#r "nuget: Lockjaw.Client, 2.0.2.66"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Lockjaw.Client@2.0.2.66
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Lockjaw.Client&version=2.0.2.66
                    
Install as a Cake Addin
#tool nuget:?package=Lockjaw.Client&version=2.0.2.66
                    
Install as a Cake Tool

Lockjaw.Client

Read the environment currently selected in the Lockjaw app from any .NET application, and react the moment it changes.

Lockjaw keeps every environment's values in one configuration — keys prefixed Development_, Production_, or whatever else you declare — and lets you choose, per setting and while your app is running, which one each resolves to. This package is the reading half.

using Lockjaw.Client;

var apiUrl = LockjawClient.Default.Get("ApiUrl");
var db     = LockjawClient.Default.GetConnectionString("Main");

Ask for the key without its prefix; you get whichever environment is currently selected. No configuration on your side — the client and the app find each other by instance name.

Finding your instance

One Lockjaw manages several applications, each published under its own instance name. Name the one you want:

var client = new LockjawClient(new LockjawClientOptions { InstanceName = "OrderService" });

Or let the client find it. Lockjaw publishes the application names each instance serves, so a client can match its own and needs no configuration at all:

// In OrderService.exe — no instance name anywhere.
var client = new LockjawClient(new LockjawClientOptions { AutoDiscoverInstance = true });

Console.WriteLine(client.InstanceName);   // "OrderService", resolved at construction

ApplicationName defaults to the entry assembly's name; set it explicitly if your executable is named differently from the instance's target. Discovery is off by default and never overrides an explicit choice: an explicit SnapshotPath or a non-default InstanceName wins, and if nothing matches the client falls back to default.

To see what is available:

foreach (var instance in SnapshotStore.EnumerateInstances())
    Console.WriteLine($"{instance.Instance}: {string.Join(", ", instance.Applications)}");

netstandard2.0, so it works from .NET Framework 4.6.1+ and .NET Core / .NET 5+.

Typed reads

var timeout = LockjawClient.Default.Get("TimeoutSeconds", 30);   // parsed, with a fallback
var url     = LockjawClient.Default.GetRequired("ApiUrl");       // throws if missing

Colon-delimited paths

Nested JSON flattens into colon paths, the same convention .NET configuration uses, so ask for a nested value by its path:

var level = LockjawClient.Default.Get("Logging:Level");
var host  = LockjawClient.Default.Get("Hosts:0");            // arrays take their index

The environment prefix can sit on any segment of the path, which is what lets a single leaf vary while its unprefixed siblings are read as Production:

{
  // The whole subtree varies:
  "Development_Logging": { "Level": "Debug", "Console": { "Enabled": true } },
  "Production_Logging":  { "Level": "Warning", "Console": { "Enabled": false } },

  // …or just one leaf, its siblings read as Production:
  "Telemetry": {
    "Development_Endpoint": "http://localhost:4317",
    "Production_Endpoint":  "https://otel.contoso.com",
    "SampleRate": "0.25"
  }
}

Both forms give you Logging:Level, Logging:Console:Enabled and Telemetry:Endpoint — ask for the path with the prefix removed, exactly as you would for a flat key. Connection strings nest the same way, and a flat key that simply contains a colon (Development_Api:Url in app.config) works too.

Top-level pairs — individual keys that sit beside the AppSettings and ConnectionStrings sections rather than inside them — are read as app settings, so Get("SomeTopLevelKey") returns them directly.

Connection strings, the ConfigurationManager way

GetConnectionString(name) gives you the string. When you want what ConfigurationManager gives you — a ConnectionStringSettings with its ProviderName — index ConnectionStrings by name:

// Where you used to write this:
var main = ConfigurationManager.ConnectionStrings["Main"];

// write this, and the value follows the environment you have selected:
var main = LockjawClient.Default.ConnectionStrings["Main"];

var text     = main.ConnectionString;   // Server=sql-prod-01;Database=Contoso
var provider = main.ProviderName;       // System.Data.SqlClient

It behaves the way ConfigurationManager.ConnectionStrings does: the lookup is case-insensitive and an unknown name returns null rather than throwing. Count, an integer indexer, Contains(name), Names and enumeration are all there too, ordered by name.

Two differences worth knowing:

  • It is a live view, not a copy. Every read goes back to the client, so a lookup made after the user switches environment returns the new value — there is nothing to refresh.
  • Each read builds a fresh ConnectionStringSettings (ConfigurationManager hands back a cached instance). Mutating what you get back changes nothing in Lockjaw, and two reads of the same name are equal in content but are not the same object.

ProviderName is whatever configuration declared, and an empty string when it declared none — Lockjaw does not substitute a default. In app.config it comes off the attribute you already write:

<connectionStrings>
  <add name="Development_Main" connectionString="Server=(localdb)\MSSQLLocalDB;Database=Contoso_Dev"
       providerName="System.Data.SqlClient" />
  <add name="Production_Main"  connectionString="Server=sql-prod-01;Database=Contoso"
       providerName="System.Data.SqlClient" />
</connectionStrings>

JSON has no equivalent attribute, so a connection string may be written as an object to carry one. The plain string form keeps working, and the two can be mixed:

"ConnectionStrings": {
  "Development_Main": "Server=(localdb)\\MSSQLLocalDB;Database=Contoso_Dev",
  "Production_Main":  { "connectionString": "Server=sql-prod-01;Database=Contoso",
                        "providerName": "System.Data.SqlClient" }
}

The provider is tracked per environment, so Development_Main and Production_Main can name different ones and ProviderName follows whichever is selected — useful when a local box runs SQLite or Postgres against a SQL Server production database.

As an IConfiguration

LockjawClient is a Microsoft.Extensions.Configuration.IConfiguration, so its resolved values are readable with the standard path syntax and bindable with IOptions:

IConfiguration config = LockjawClient.Default;

var db  = config["ConnectionStrings:Main"];        // == config.GetConnectionString("Main")
var url  = config["ApiUrl"];                        // an AppSettings value, prefix already resolved
var flag = config["FeatureEnabled"];               // a top-level pair

App settings (including the top-level pairs and nested keys) appear at the root by their base key, and connection strings under the conventional ConnectionStrings section. The environment prefix is already stripped, so ConnectionStrings:Main reads whichever of Development_Main / Production_Main is currently active — switch the environment in the Lockjaw app and the value follows. A change also fires IConfiguration.GetReloadToken(), so IOptionsMonitor and reloadOnChange bindings refresh.

Add it to a host builder's configuration pipeline with AddLockjaw:

builder.Configuration.AddLockjaw();                // the Default client
// or a specific one:
builder.Configuration.AddLockjaw(myClient);

Because Lockjaw is layered last, its live, environment-switched values take precedence over the JSON and environment-variable sources added before it.

On .NET 4.5.2, where Microsoft.Extensions.Configuration has no build, the client is not an IConfiguration — but the client["Section:Key"] indexer still exists with the same path syntax and behavior, so code written against it compiles and runs unchanged.

Reacting to changes

Changes are picked up live. The app pushes each change to the client over a named pipe the moment you switch an environment or apply one to everything — the client does not poll or watch a file, so delivery is prompt and survives a locked-down machine where file-change notifications are unreliable (a redirected profile, a VDI/roaming setup, or aggressive endpoint protection). If the app is not running yet, the client keeps trying to connect, and picks up the current values the moment it does; the same happens if the app is restarted.

The event arrives on a background thread, so a WPF or WinForms handler must reach the UI thread first — SubscribeOnUiThread does that for you when called from the UI thread, and returns a token you dispose to unsubscribe:

_subscription = LockjawClient.Default.SubscribeOnUiThread((s, e) =>
{
    ApiUrlText.Text = e.Value;     // already on the dispatcher
});

Under the hood it captures the UI thread's SynchronizationContext — a DispatcherSynchronizationContext on WPF — so this package needs no WPF reference of its own. For a context you hold yourself, use SubscribeOn(context, handler). Off the UI thread, subscribe to SettingChanged directly.

When the Lockjaw app isn't running

  • Published values apply only while the app is running. Its snapshot file stays on disk after it exits, but the client will not serve one nothing is maintaining — a key switched to a local or production environment for one debugging session would otherwise stay switched for every later run.
  • With no app publishing, the client falls back to its own app.config, web.config or appsettings.json, read with the same prefix convention and resolved to the environment that config declares as default. So an app that references Lockjaw.Client still works standalone, and resolves the way it would on a machine where Lockjaw was never installed.
  • Start order does not matter: values arrive the moment an app appears and are withdrawn when it goes, each raising SettingChanged like any other change.
  • Published values always win, per key; the fallback only fills gaps.
  • SourceOf(key) tells you which it was: Published, LocalConfig, or None.
  • To read a snapshot file regardless — an exported one, or a machine where the app is deliberately not kept running — set RequireLivePublisher = false.
switch (LockjawClient.Default.SourceOf("ApiUrl"))
{
    case LockjawValueSource.Published:   /* the user picked this in the app */ break;
    case LockjawValueSource.LocalConfig: /* no app publishing; from my own config */ break;
    case LockjawValueSource.None:        /* nobody has this key */ break;
}

Your own fallback config

Ship the settings in your application's own appsettings.json and it keeps working on a machine where Lockjaw has never run. Same prefix convention:

{
  // No "Lockjaw" section — which environments exist is the Lockjaw app's business.
  "AppSettings": {
    "Local_ApiUrl":       "http://localhost:5000/api",
    "Development_ApiUrl": "https://localhost:5001/api",
    "Production_ApiUrl":  "https://api.contoso.com",

    // Partial coverage is fine: with no Local value, Local resolves to Development.
    "Development_LogLevel": "Debug",
    "Production_LogLevel":  "Warning",

    // Unprefixed keys are served too, read as Production, so ordinary settings keep working.
    "SupportEmail": "support@contoso.com"
  },

  "ConnectionStrings": {
    "Local_Main":       "Server=(localdb)\\MSSQLLocalDB;Database=Contoso_Local",
    "Development_Main": "Server=(localdb)\\MSSQLLocalDB;Database=Contoso_Dev",
    "Production_Main":  "Server=sql-prod-01;Database=Contoso"
  }
}

Or in app.config / web.config:

<configuration>
  <appSettings>
    <add key="Local_ApiUrl"       value="http://localhost:5000/api" />
    <add key="Development_ApiUrl" value="https://localhost:5001/api" />
    <add key="Production_ApiUrl"  value="https://api.contoso.com" />

    
    <add key="SupportEmail" value="support@contoso.com" />
  </appSettings>

  <connectionStrings>
    <add name="Development_Main"
         connectionString="Server=(localdb)\MSSQLLocalDB;Database=Contoso_Dev" />
    <add name="Production_Main"
         connectionString="Server=sql-prod-01;Database=Contoso" />
  </connectionStrings>
</configuration>

Three things differ from the Lockjaw app's own configuration:

  • No Lockjaw section. Which environments exist is the app's business. The client needs the list only when its own keys use prefixes beyond Development_ / Production_.
  • Unprefixed keys are served, read as Production the same way the Lockjaw window reads them — so your ordinary settings can live in the same file, untouched.
  • Prefixed keys resolve to FallbackEnvironment, which defaults to Development, so a machine without Lockjaw never quietly starts on production.

Anything beyond the defaults is set in code rather than in the file:

using var client = new LockjawClient(new LockjawClientOptions
{
    // Only needed for prefixes beyond the built-in pair.
    Environments = new List<EnvironmentDefinition>
    {
        new EnvironmentDefinition("Local",       "Local_"),
        new EnvironmentDefinition("Development", "Development_"),
        new EnvironmentDefinition("Production",  "Production_")
    },

    FallbackEnvironment       = "Local",  // which one the fallback picks
    IncludeUnprefixedFallback = true,     // serve plain keys too (the default)
    FallBackToLocalConfig     = true      // false: require the Lockjaw app
});

Values the Lockjaw app publishes carry their environment name with them, so none of this affects those — it shapes the fallback only.

API

Member Purpose
Get(key) / Get<T>(key, fallback) / GetRequired(key) Resolve an app setting (including top-level pairs)
GetConnectionString(name) Resolve a connection string
ConnectionStrings[name] / GetConnectionStringSettings(name) Resolve one as a ConnectionStringSettings, as ConfigurationManager does
this[key] / GetSection / GetChildren / GetReloadToken IConfiguration — read by Section:Key path
ToConfigurationSource() / AddLockjaw(builder) Add Lockjaw to an IConfigurationBuilder pipeline
EnvironmentOf(key, kind) The environment name a key resolves to
InstanceName The instance this client resolved to
SourceOf(key, kind) Published, LocalConfig, or None
All Every setting the client can resolve
Environments The environments the app published, with names and colors
IsAvailable / HasLocalFallback / UpdatedUtc Whether the app has published, whether a fallback loaded, and when
SettingChanged Raised when a value changes (background thread)
SubscribeOnUiThread(handler) / SubscribeOn(context, handler) Subscribe with events marshalled to the UI thread
Refresh() Re-read now

Options

Option Default
InstanceName default Must match the app's instance
AutoDiscoverInstance false Find the instance that names this application
ApplicationName the entry assembly's name What discovery matches on
SnapshotPath derived from the instance Explicit file to read
WatchForChanges true Receive live updates (pushed over a named pipe)
AllowCrossAccountHost false No longer needed; ignored (see below)
FallBackToLocalConfig true Read own config when the app has published nothing
FallbackEnvironment Development Environment the fallback resolves to
Environments Development_ / Production_ Prefixes recognised in the fallback
IncludeUnprefixedFallback true Serve plain keys from own config
UseLocalAppConfig / UseLocalJsonFile true Which fallback sources to read
LocalJsonFilePath appsettings.json beside the app Fallback JSON file

LockjawClient is thread-safe and implements IDisposable — dispose it to stop listening. Use LockjawClient.Default for the common single-instance case.

Clients under a different account

A named pipe is machine-wide, so any client running as the same Windows account hears the push with no configuration — including one in another logon session. Reaching a client under a different Windows account — a service account, say — is decided entirely on the app's side: set AllowCrossAccountClients on the app/host (LockjawOptions, in Lockjaw.Core) and it widens the pipe's ACL to authenticated users. It is off by default because that lets any authenticated account on the machine read the published values.

AllowCrossAccountHost on the client is a leftover from the previous transport, where both sides had to agree on a kernel namespace. It is ignored now, and kept only so existing code compiles.

Shipping

Lockjaw is a development aid. Keep production credentials out of config files that reach end users; the usual approach is to reference it from Debug builds only:

<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <PackageReference Include="Lockjaw.Client" Version="2.0.1" />
</ItemGroup>

See also

  • Lockjaw.Core — the shared model, if you want to read the published snapshot yourself.
  • The Lockjaw app — the tray application that reads your configuration and publishes the values. Its built-in Help (F1) documents the whole system, including the real file paths on your machine.
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net452 is compatible.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.2.66 308 9/10/2026
2.0.2.57 152 8/21/2026
2.0.2.51 179 8/14/2026
2.0.2.49 129 8/14/2026
2.0.2.37 126 8/6/2026
2.0.2.34 134 8/5/2026
2.0.2.33 120 8/5/2026
2.0.2.32 108 8/5/2026
2.0.2.28 123 8/5/2026
2.0.2.27 129 8/5/2026
2.0.2.17 138 7/25/2026

2.3.0
- Live updates now travel over PipeR — SignalR's hub model over a Windows named pipe — instead of the SIPC semaphore mesh. Still a direct push from the Lockjaw app, still prompt on locked-down machines where file-change notifications are unreliable, and the client still reads the last published snapshot at startup so values stay available when the app is not running.
- The client connects, subscribes, and is handed the current snapshot in the same step, so it is up to date immediately rather than after the next change. A client started before the app keeps trying to connect and subscribes the moment it appears; an app restart takes the same path, with no request/retry handshake left to get out of step.
- AllowCrossAccountHost is no longer needed and is ignored. A named pipe is machine-wide, so a same-account app in any logon session is reached with no configuration, and reaching one under a different Windows account is decided entirely by the app's AllowCrossAccountClients. The property is kept so existing code compiles.
- No new dependency: Lockjaw.Client still brings only Lockjaw.Core, whose dependencies are now Newtonsoft.Json and Jetsonsoft.PipeR.

2.2.0
- Connection strings can now be read as ConnectionStringSettings, the way ConfigurationManager.ConnectionStrings["Main"] does: LockjawClient.ConnectionStrings["Main"] returns the value and providerName for the environment currently selected, or null when the name is unknown. The collection is a live view, so a lookup after an environment switch returns the new value.
- providerName now travels from configuration to the client. It is read from the providerName attribute in app.config, and in JSON from an object form — "Main": { "connectionString": "…", "providerName": "…" } — since JSON has no equivalent attribute. It is tracked per environment, so Development_Main and Production_Main can name different providers.
- Live updates now travel over SIPC, a semaphore-only peer mesh, instead of a named pipe — still a direct push from the Lockjaw app, with no sockets, pipes or shared files. Changes are delivered promptly even on locked-down machines where file-change notifications are unreliable.
- The client joins the app's mesh, subscribes for changes, and asks the app for the current snapshot on join, retrying until the app answers or appears. It still reads the last published snapshot at startup, so values stay available when the app is not running.
- Set AllowCrossAccountHost to receive updates from an app running in another logon session or under a different Windows account; it must match AllowCrossAccountClients on the app/host side. A same-user app on the same desktop needs no configuration.
- SettingChanged now fires when a previously published key is withdrawn — the app stops publishing it, or is disabled and publishes an empty snapshot — reporting the value it reverts to (the client's own config, or none). Previously a withdrawn value could leave consumers, and the IConfiguration provider, on the stale published value.
- The local fallback now resolves prefixed keys to the environment the client's own config declares as default (Lockjaw:DefaultEnvironment), so a key reverts to its default-environment value when nothing is published, exactly as on a production machine. FallbackEnvironment is now unset by default and, when set, still pins the fallback to a specific environment; it previously defaulted to Development.

2.1.0
- Live updates now arrive as a direct push from the Lockjaw app over a named pipe, replacing the snapshot-file watch. Changes are delivered promptly even on locked-down machines where file-change notifications are unreliable — redirected profiles, VDI/roaming setups, or aggressive endpoint protection.
- The client no longer uses FileSystemWatcher: it listens on the pipe and reconnects on its own if the app is not running yet or restarts. It still reads the last published snapshot at startup, so values stay available when the app is not running.
- Clients in another logon session are reached with no configuration; a client under a different Windows account is supported by enabling AllowCrossAccountClients on the app/host side.

2.0.2
- Environments are open-ended: declare any prefix (Local_, Test_, Staging_) instead of only Development_/Production_.
- EnvironmentOf returns the environment name; Environments exposes the published environment list.
- Falls back to the consuming application's own app.config / appsettings.json when nothing has been published; SourceOf reports where a value came from.
- SubscribeOnUiThread / SubscribeOn marshal SettingChanged onto a WPF or WinForms UI thread.
- Recovers from FileSystemWatcher buffer overflow so a dropped event cannot leave stale values.