SmrtHub.Config¶

Assembly: SmrtHub.Config

Namespace: SmrtHub.Config¶

ConfigJson¶

Centralized JSON configuration helpers: one canonical JsonSerializerOptions, atomic writes with .bak backups, and safe read-modify-write utilities.

Remarks

These APIs are the single entry point for configuration persistence inside %AppData%/SmrtHub/Config and %LocalAppData%/SmrtHub/Config, preventing hosts from rolling their own JSON handling.

Fields¶

Options¶

Canonical options for shared config files (camelCase + enum strings, indented).

Remarks

Consumers should not mutate these options; clone when customization is required.

Methods¶

AtomicWrite(string path, string json)¶

Atomically writes JSON text to a file with a temporary file and a .bak backup.

Parameters

path — Absolute path for the target JSON file (must resolve via ConfigPathResolver).
json — Serialized JSON payload to persist.

Remarks

Writes run with System.IO.FileOptions.WriteThrough and explicit flush calls to avoid partial data.

Load(string path)¶

Generic load for a typed model (returns default on failure).

Parameters

path — Absolute path to the JSON file.

Returns: Instance of T when parsing succeeds; otherwise .

Remarks

Callers should supply DTOs with nullability annotations to capture partial data from legacy files.

LoadObject(string path)¶

Loads a System.Text.Json.Nodes.JsonObject from disk or returns an empty object on failure.

Parameters

path — Absolute path to the JSON file.

Returns: The parsed System.Text.Json.Nodes.JsonObject; falls back to an empty object when the file is missing or corrupt.

Remarks

Utilizes small retry windows to tolerate concurrent writes. Callers should still coordinate via SmrtHub.Config.ConfigJson.WithNamedMutex(System.String,System.Action,System.Int32) when updating.

Save(string path, ``0 value)¶

Saves a typed model using canonical options and atomic write.

Parameters

path — Absolute path to the JSON file.
value — Instance to serialize.

SaveObject(string path, Text.Json.Nodes.JsonObject obj)¶

Saves a System.Text.Json.Nodes.JsonObject to disk using canonical options and atomic write semantics.

Parameters

path — Absolute path to persist the JSON payload.
obj — JSON object to serialize.

Update(string path, Action mutate)¶

Applies a mutation to a JsonObject and persists it atomically.

Parameters

path — Absolute path to the JSON file to update.
mutate — Delegate that mutates the in-memory System.Text.Json.Nodes.JsonObject prior to persistence.

Remarks

Callers should use SmrtHub.Config.ConfigJson.WithNamedMutex(System.String,System.Action,System.Int32) when multiple processes might mutate the same file.

WithNamedMutex(string name, Action action, int timeoutMs)¶

Executes an action while holding a named global mutex for cross-process coordination.

Parameters

name — Mutex name (use Global\ prefix for machine-wide, e.g., Global\SmrtHub.Config.hub-window).
action — The action to execute while holding the mutex.
timeoutMs — Wait timeout in milliseconds (default 2000ms).

Exceptions

System.TimeoutException — Thrown when the mutex cannot be acquired within the allotted time.

Remarks

The mutex guards concurrent access to the same config file across processes. Timeout ensures the caller cannot hang indefinitely when another process crashes without releasing the lock. Abandoned mutex instances are treated as acquired so the caller can continue after a prior-crash scenario.

ConfigPathResolver¶

Centralized helper for resolving well-known file and directory paths for all SmrtHub components. Implements a consistent, enterprise-grade scheme under: %AppData% (Roaming) / SmrtHub / Config / COMPONENT-SLUG %LocalAppData% (Local) / SmrtHub / Config / COMPONENT-SLUG

Remarks

File naming conventions (lower kebab-case): COMPONENT-SLUG-config.json : Persistent configuration (user editable) COMPONENT-SLUG-state.json : Transient / recoverable state persistence Additional custom file names can be requested via SmrtHub.Config.ConfigPathResolver.AppFileKind.Custom.

         Component slug normalization rules:
          * Accepts names in Camel/PascalCase, snake_case, kebab-case, spaced words.
          * Output is strict kebab-case (lowercase, hyphen separated).
          * Removes any characters that are not alphanumeric, space, hyphen, or underscore.

         See ``README.Files/SmrtHub-Operational-Data-Policy-v1.0.README.md`` for canonical directory definitions.
         This class is safe to call concurrently; all directory creation is idempotent.

Methods¶

GetAppDataRoot(SmrtHub.Config.ConfigPathResolver.AppDataScope param0)¶

Returns the base AppData root path for the chosen scope.

GetComponentDirectory(string componentName, SmrtHub.Config.ConfigPathResolver.AppDataScope scope)¶

Returns the absolute path to the component directory under the chosen AppData scope.

Parameters

componentName — Raw component name (any common casing or separators).
scope — Roaming (default) or Local path preference.

Returns: Absolute directory path rooted under %AppData%/SmrtHub/Config or %LocalAppData%/SmrtHub/Config.

Exceptions

System.ArgumentException — Thrown when componentName is null or whitespace.

GetConfigFilePath(string componentName, SmrtHub.Config.ConfigPathResolver.AppDataScope scope)¶

Convenience helper for retrieving the configuration file path.

Parameters

componentName — Component name to normalize.
scope — AppData scope; defaults to Roaming.

Returns: Absolute path ending in -config.json (or override extension).

GetConfigPath(string componentName, string fileName)¶

Convenience method for callers that already manage their own file names. Interprets componentName as a raw component name and returns the canonical component directory when fileName is empty, or appends the supplied file name otherwise. Prefer SmrtHub.Config.ConfigPathResolver.GetFilePath(System.String,SmrtHub.Config.ConfigPathResolver.AppFileKind,SmrtHub.Config.ConfigPathResolver.AppDataScope,System.String,System.String) for config/state/custom files that follow Operational Data Policy naming.

Parameters

componentName — Component name (any separators accepted).
fileName — Optional file name (must be a simple file name without directory separators).

Returns: Absolute path to the component directory or the specific file when provided.

Exceptions

System.ArgumentException — Thrown when fileName contains invalid characters or directory separators.

GetFilePath(string componentName, SmrtHub.Config.ConfigPathResolver.AppFileKind kind, SmrtHub.Config.ConfigPathResolver.AppDataScope scope, string customFileName, string jsonExtensionOverride)¶

Gets a strongly-conventioned file path for a given component and file kind.

Parameters

componentName — Component name to normalize.
kind — Config, State, or Custom.
scope — AppData location preference (defaults to Roaming).
customFileName — Required when kind is SmrtHub.Config.ConfigPathResolver.AppFileKind.Custom.
jsonExtensionOverride — Extension for config/state files (without leading dot); defaults to json.

Returns: The fully qualified file path adhering to Operational Data Policy naming rules.

Exceptions

System.ArgumentException — Thrown when a required parameter is null, invalid, or contains invalid characters.

GetStateFilePath(string componentName, SmrtHub.Config.ConfigPathResolver.AppDataScope scope)¶

Convenience helper for retrieving the state file path.

Parameters

componentName — Component name to normalize.
scope — AppData scope; defaults to Roaming.

Returns: Absolute path ending in -state.json (or override extension).

NormalizeComponentSlug(string raw)¶

Normalizes a component name to a strict kebab-case slug.

Parameters

raw — Component identifier in any common casing or separator style.

Returns: Kebab-case slug aligned with Operational Data Policy expectations.

OperationalDataRoot¶

Provides centralized access to the common application data root with support for test overrides.

Methods¶

GetCommonApplicationDataPath()¶

Gets the preferred CommonApplicationData root, honoring the optional override environment variable.

TryGetOverride(String@ param0)¶

Attempts to retrieve the override path declared via SMRTHUB_COMMON_APPDATA_OVERRIDE.

SharedDataPathResolver¶

Resolves shared (machine-wide) data paths rooted under %ProgramData%/SmrtHub for artifacts consumed by both services and user-scoped tools (e.g., Storage Guard secrets).

Methods¶

GetComponentDirectory(string componentName)¶

Returns the shared component directory under %ProgramData%/SmrtHub/Config.

Parameters

componentName — Component identifier (any casing/separators allowed).

GetFilePath(string componentName, string fileName)¶

Returns an absolute file path for the shared component directory.

Parameters

componentName — Component identifier.
fileName — Simple file name (no directories).

SmrtDbPathResolver¶

Centralized helper for resolving SmrtDB paths under the local AppData root.

Methods¶

GetComponentDirectory(string componentName)¶

Returns a component-scoped SmrtDB directory under the SmrtDB root.

Parameters

componentName — Raw component name for slug normalization.

Returns: Absolute directory path for the component.

Exceptions

System.ArgumentException — Thrown when componentName is invalid.

GetFilePath(string componentName, string fileName)¶

Returns a file path under the component SmrtDB directory.

Parameters

componentName — Component name to normalize for the directory.
fileName — File name to append (no directory separators).

Returns: Absolute path to the requested SmrtDB file.

Exceptions

System.ArgumentException — Thrown when inputs are invalid.

GetRootDirectory()¶

Returns the absolute SmrtDB root directory under %LocalAppData%.

Namespace: SmrtHub.Config.ConfigPathResolver¶

AppDataScope¶

Distinguishes between roaming (user-syncable) and local (machine-specific) data roots.

Fields¶

Local¶

%LocalAppData% (Local) - machine-specific, not synced.

Roaming¶

%AppData% (Roaming) - profile follows the user when domain roaming is enabled.

AppFileKind¶

Standard file kinds supported by the resolver.

Fields¶

Config¶

Semantic configuration (JSON) editable by user/admin.

Custom¶

Custom file name supplied by caller (must include extension).

State¶

State persistence (JSON) - ephemeral / recoverable.

Namespace: SmrtHub.Config.Logging¶

LoggingConfigurationExtensions¶

Extensions to include the embedded SmrtHub logging defaults into an IConfigurationBuilder.

Methods¶

AddSmrtHubLoggingDefaults(Microsoft.Extensions.Configuration.IConfigurationBuilder builder)¶

Adds the embedded default Logging:SmrtHub settings to the provided configuration builder. Call this before building the configuration. Optional; apps can also rely solely on their own appsettings.json.

Parameters

builder — Configuration builder instance to enrich with the embedded JSON.

Returns: The original Microsoft.Extensions.Configuration.IConfigurationBuilder to support fluent chaining.

Remarks

When the embedded resource is unavailable the builder is returned unchanged.

SmrtLoggingOptions¶

Central, typed logging options for SmrtHub. Bind this from configuration (e.g., section "Logging:SmrtHub"). Canonical usage is via IConfiguration: Logger.ConfigureFrom(configuration, componentName, "Logging:SmrtHub"). This type exists primarily for binding/validation; direct Logger.ConfigureFrom(SmrtLoggingOptions, ...) is deprecated.

Propertys¶

ActivityTagPrefix¶

Prefix applied to Activity Tag properties when enriched (e.g., "Tag."; use empty string to emit raw tag keys).

AutoOpenHtmlExport¶

Auto-open HTML logs when exported.

EnableConsole¶

Write logs to console (useful in development).

EnableTraceContext¶

Enable W3C trace context propagation.

EnrichWithDemystifiedExceptions¶

Enrich with exception demystifier for better stack traces.

FileSizeLimitBytes¶

Max file size before rolling.

LogDirectory¶

Root directory for logs; if null, Logger picks a default per component.

MinimumLevel¶

Minimum log level text, e.g., Information, Debug, Warning, Error, Verbose, Fatal.

RedactionToken¶

Token to replace redacted values.

RetainedFileCountLimit¶

Maximum retained files per sink.

RollOnFileSizeLimit¶

Whether to roll the file when reaching size limit.

ScrubPII¶

Enable basic PII scrubbing.