Documentation

Configuration

Read time 3 minutes Package: Nalix.Environment
On this page

Namespace: Nalix.Environment.Configuration (and Nalix.Environment.Configuration.Binding)
Assembly: Nalix.Environment

The Nalix.Environment configuration system binds .ini files to strongly-typed ConfigurationLoader classes using compile-time code generated by ConfigurationGenerator (zero runtime reflection).

Source Mapping

  • src/Nalix.Environment/Configuration/ConfigurationManager.cs
  • src/Nalix.Environment/Configuration/Binding/ConfigurationLoader.cs
  • src/Nalix.Environment/Configuration/Binding/ConfigurationLoader.SectionName.cs
  • src/Nalix.Environment/Configuration/Binding/IniConfig.cs
  • analyzers/Nalix.Analyzers.Generators/ConfigurationGenerator.cs

ConfigurationManager

ConfigurationManager (public sealed class ConfigurationManager : IDisposable) manages the active .ini file (defaulting to <Directories.ConfigurationDirectory>/default.ini), debounced FileSystemWatcher reloads (300ms), and the thread-safe cache of ConfigurationLoader instances.

Public Properties & Methods

MemberSignatureDescription
Instancepublic static ConfigurationManager Instance { get; }Global singleton instance.
ConfigFilePathpublic string ConfigFilePath { get; }Absolute path to the active .ini file.
ConfigFileExistspublic bool ConfigFileExists { get; }true if the active .ini file exists on disk.
LastReloadTimepublic DateTime LastReloadTime { get; }UTC timestamp of the most recent configuration reload.
Get<TClass>()public TClass Get<TClass>() where TClass : ConfigurationLoader, new()Resolves or initializes the cached TClass options instance from the active .ini file.
Get<TClass>(string, bool)public TClass Get<TClass>(string configFilePath, bool autoReload = true) where TClass : ConfigurationLoader, new()Switches the active .ini file to configFilePath and resolves TClass.
MarkManuallyConfigured<TClass>()public void MarkManuallyConfigured<TClass>() where TClass : ConfigurationLoaderMarks TClass as configured in code so .ini reloads emit a warning when overwriting programmatic changes.
SetConfigFilePathpublic void SetConfigFilePath(string newConfigFilePath, bool autoReload = true)Switches the active .ini file path (must reside under Directories.ConfigurationDirectory; throws TimeoutException if a reload is already in progress).
UpdateValue<TClass>public void UpdateValue<TClass>(string key, object value) where TClass : ConfigurationLoader, new()Updates a single key in TClass’s .ini section, persists it to disk, and reloads TClass.
ReloadAllpublic void ReloadAll()Re-reads the active .ini file and updates all cached instances in-place (throws TimeoutException if another reload is concurrently running).
Flushpublic void Flush()Writes any buffered .ini defaults/comments to disk.
IsLoaded<TClass>()public bool IsLoaded<TClass>() where TClass : ConfigurationLoaderReturns true if TClass is currently cached.
Remove<TClass>()public bool Remove<TClass>() where TClass : ConfigurationLoaderRemoves TClass from the active cache.
ClearAllpublic void ClearAll()Clears all cached configuration instances.

ConfigurationLoader

All option classes inherit from ConfigurationLoader (Clone<T>() where T : ConfigurationLoader, new()) and must be declared partial so ConfigurationGenerator can emit BindProperties, CopyPropertiesTo, CloneEmpty, and ValidateDataAnnotations.

Section Naming Convention

The .ini section name is derived by stripping standard suffixes (Options, Config, Settings, Option, Configs, Setting, Configuration, Configurations) from the class name:

  • NetworkSocketOptions $\rightarrow$ [NetworkSocket]
  • TransportOptions $\rightarrow$ [Transport]

Supported Property Types (IniConfig)

IniConfig and ConfigurationGenerator support:

  • Integers & Bytes: byte, sbyte, short, ushort, int, uint, long, ulong (GetByte, GetSByte, GetInt16, GetUInt16, GetInt32, GetUInt32, GetInt64, GetUInt64)
  • Floating-Point & Decimal: float (GetSingle), double (GetDouble), decimal (GetDecimal)
  • Primitives & Value Types: bool (GetBool), char (GetChar), string (GetString), TimeSpan (GetTimeSpan), DateTime (GetDateTime), Guid (GetGuid), and enum (GetEnum<TEnum>).
using Nalix.Abstractions;
using Nalix.Abstractions.Validation;
using Nalix.Environment.Configuration.Binding;

[IniComment("Server room settings")]
public sealed partial class ServerRoomOptions : ConfigurationLoader, IValidatableConfiguration
{
    [IniComment("Listen port (1..65535)")]
    [ValueRange(1, 65535)]
    public ushort Port { get; set; } = 57206;

    [ConfiguredIgnore]
    public string InternalRuntimeId { get; set; } = "local";

    public void Validate() => this.ValidateDataAnnotations();
}