Then, prepare a class (UserSetting) in advance that you want to read and write as settings.
public class UserSetting
{
public string Name { get; set; } = "default name";
public int Age { get; set; } = 20;
}
Without DI
If you are not using DI (for example, in WinForms, WPF, console apps, etc.),
Use as the starting point for reading and writing settings.
WritableOptions
using Configuration.Writable;
// initialize once (at application startup)
WritableOptions.Initialize<SampleSetting>();
// -------------
// get the writable config instance with the specified setting class
var options = WritableOptions.GetOptions<SampleSetting>();
// get the UserSetting instance
var sampleSetting = options.CurrentValue;
Console.WriteLine($">> Name: {sampleSetting.Name}");
// and save to storage
await options.SaveAsync(setting =>
{
setting.Name = "new name";
});
// By default, it's saved to ./usersettings.json
With DI
If you are using DI (for example, in ASP.NET Core, Blazor, Worker Service, etc.), register IReadOnlyOptions<T> and IWritableOptions<T> in the DI container.
First, call AddWritableOptions<T> to register the settings class.
Then, inject IReadOnlyOptions<T> or IWritableOptions<T> to read and write settings.
// read config in your class
// you can also use IOptions<T>, IOptionsMonitor<T> or IOptionsSnapshot<T>
public class ConfigReadService(IReadOnlyOptions<UserSetting> options)
{
public void Print()
{
// get the UserSetting instance
var sampleSetting = options.CurrentValue;
Console.WriteLine($">> Name: {sampleSetting.Name}");
}
}
// read and write config in your class
public class ConfigReadWriteService(IWritableOptions<UserSetting> options)
{
public async Task UpdateAsync()
{
// get the UserSetting instance
var sampleSetting = options.CurrentValue;
// and save to storage
await options.SaveAsync(setting =>
{
setting.Name = "new name";
});
}
}
You can change various settings as arguments to Initialize or AddWritableOptions.
// Without DI
WritableOptions.Initialize<SampleSetting>(conf => { /* ... */ });
// With DI
builder.Services.AddWritableOptions<UserSetting>(conf => { /* ... */ });
Save Location
Default behavior is to save to {AppContext.BaseDirectory}/usersettings.json (in general, the same directory as the executable).
If you want to change the save location, use conf.UseFile(path) or conf.UseXxxDirectory().AddFilePath(path).
For example:
// to save to the parent directory
conf.UseFile("../myconfig");
// to save to child directory
conf.UseFile("config/myconfig");
// to save to a common settings directory
// in Windows: %APPDATA%/MyAppId
// in macOS: $XDG_CONFIG_HOME/MyAppId or ~/Library/Application Support/MyAppId
// in Linux: $XDG_CONFIG_HOME/MyAppId or ~/.config/MyAppId
conf.UseStandardSaveDirectory("MyAppId")
.AddFilePath("myconfig");
If you want to read/write files from multiple locations, you can call UseXxxDirectory().AddFilePath multiple times as follows.
When multiple locations are specified, the load/save destination is determined on initialization on the following priority order:
Explicit priority (descending)
Target file already exists and able to open with write access
Target directory already exists and able to create file
Order of registration (earlier registrations have higher priority)
conf.UseCustomDirectory(@"D:\SpecialFolder\")
.AddFilePath("first"); // is not existing folder/file yet
conf.UseStandardSaveDirectory("MyAppId")
.AddFilePath("second", priority: 10);
conf.UseExecutableDirectory()
.AddFilePath("third") // is already exist directory but not file
.AddFilePath("child/fourth"); // is already exist file
// In this case, the priorities are as follows:
// 1: %APPDATA%/MyAppId/second (priority 10)
// 2: ./child/fourth (target file exists)
// 3: ./third (target directory exists)
// 4: D:\SpecialFolder\first (target directory/file does not exist)
If you want to toggle between development and production environments, you can use #if RELEASE pattern or builder.Environtment.IsProduction().
// those pattern are saved to
// - development: ./mysettings.json (executable directory)
// - production: %APPDATA%/MyAppId/mysettings.json (on Windows)
// without DI
WritableOptions.Initialize<UserSetting>(conf => {
#if DEBUG
var isProduction = false;
#else
var isProduction = true;
#endif
conf.UseStandardSaveDirectory("MyAppId", enabled: isProduction)
.AddFilePath("mysettings");
});
// if using IHostApplicationBuilder
builder.Services.AddWritableOptions<UserSetting>(conf => {
var isProd = builder.Environment.IsProduction();
conf.UseStandardSaveDirectory("MyAppId", enabled: isProd)
.AddFilePath("mysettings");
});
FormatProvider
By default, files are saved in JSON format. If you want to customize the format, specify conf.FormatProvider as follows.
using Configuration.Writable.FormatProvider;
// use Json format with indentation
conf.FormatProvider = new JsonFormatProvider() {
JsonSerializerOptions = new () {
// you can customize JsonSerializerOptions as needed
WriteIndented = true
// for source-generation-based serialize/deserialize, set TypeInfoResolver here
TypeInfoResolver = SampleSettingSerializerContext.Default,
},
};
[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(SampleSetting))]
public partial class SampleSettingSerializerContext : JsonSerializerContext;
If you want to save in other formats, install the required packages and specify the corresponding provider.
Currently, the following providers are available:
using Configuration.Writable.FormatProvider;
// use Yaml format
// (you need to install Configuration.Writable.Yaml package)
conf.FormatProvider = new YamlFormatProvider();
// use encrypted format
// NOTE: Be aware that this is a simple encryption.
// (you need to install Configuration.Writable.Encrypt package)
conf.FormatProvider = new EncryptFormatProvider("any-encrypt-password");
FileProvider
Default FileProvider (CommonFileProvider) supports the following features:
Automatically retry when file access fails (default is max 3 times, wait 100ms each)
Create backup files rotated by timestamp (default is disabled)
Atomic file writing (write to a temporary file first, then rename it)
Thread-safe: uses internal semaphore to ensure safe concurrent access
If you want to change the way files are written, create a class that implements IFileProvider and specify it in conf.FileProvider.
using Configuration.Writable.FileProvider;
conf.FileProvider = new CommonFileProvider() {
// retry up to 5 times when file access fails
MaxRetryCount = 5,
// wait 100ms, 200ms, 300ms, ... before each retry
RetryDelay = (attempt) => 100 * attempt,
// keep 5 backup files when saving
BackupMaxCount = 5,
};
Change Detection
You can automatically detect changes to the file and use the latest settings.
For example:
public class MyService(IWritableOptions<UserSetting> options) : IDisposable
{
public void WatchStart()
{
// register change callback
var disposable = options.OnChange(newSetting => {
// called when the configuration file is changed externally
Console.WriteLine($">> Settings changed: Name={newSetting.Name}, Age={newSetting.Age}");
});
}
public async Task UpdateAsync()
{
// get the UserSetting instance
var sampleSetting = options.CurrentValue;
// and save to storage
await options.SaveAsync(setting =>
{
setting.Name = "new name";
});
// this will trigger the OnChange callback
}
public void Dispose() => disposable?.Dispose();
private IDisposable? disposable;
}
By default, throttling is enabled to suppress high-frequency file changes. Additional changes within 1 second from change detection are ignored by default.
If you want to change the throttle duration, specify conf.OnChangeThrottleMs.
If you want to directly reference the settings class, specify conf.RegisterInstanceToContainer = true.
[!NOTE]
The dynamic update functionality provided by IReadOnlyOptions<T> will no longer be available.
Be mindful of lifecycle management, as settings applied during instance creation will be reflected.
builder.Services.AddWritableOptions<UserSetting>(conf => {
conf.RegisterInstanceToContainer = true;
});
// you can use UserSetting directly
public class MyService(UserSetting setting)
{
public void Print()
{
Console.WriteLine($">> Name: {setting.Name}");
}
}
// and you can also use IReadOnlyOptions<T> as usual
public class MyOtherService(IReadOnlyOptions<UserSetting> options)
{
public void Print()
{
var setting = options.CurrentValue;
Console.WriteLine($">> Name: {setting.Name}");
}
}
Logging
Logging is enabled by default in DI environments.
If you are not using DI, or if you want to override the logging settings, you can enable logging by specifying conf.Logger.
// without DI
// package add Microsoft.Extensions.Logging.Console
conf.Logger = LoggerFactory
// enable console logging
.Create(builder => builder.AddConsole())
.CreateLogger("Configuration.Writable");
// with DI
// no setup required (uses the logger from DI)
When the output level is set to Information, mainly the following two logs are output.
By default, validation using DataAnnotations is enabled.
If validation fails, an OptionsValidationException is thrown and the settings are not saved.
using Microsoft.Extensions.Options;
builder.Services.AddWritableOptions<UserSetting>(conf => {
// if you want to disable validation of DataAnnotations, do the following:
// conf.UseDataAnnotationsValidation = false;
});
var options = WritableOptions.GetOptions<UserSetting>();
try {
await options.SaveAsync(setting => {
setting.Name = "ab"; // too short
setting.Age = 200; // out of range
});
}
catch (OptionsValidationException ex)
{
Console.WriteLine($">> Validation failed: {ex.Message}");
// setting is not saved if validation fails
}
internal class UserSetting
{
[Required, MinLength(3)]
public string Name { get; set; } = "default name";
[Range(0, 150)]
public int Age { get; set; } = 20;
}
To use source generators for DataAnnotations, use the following pattern.
Alternatively, you can add custom validation using WithValidatorFunction or WithValidator.
using Microsoft.Extensions.Options;
builder.Services.AddWritableOptions<UserSetting>(conf => {
// add custom validation function
conf.WithValidatorFunction(setting => {
if (setting.Name.Contains("invalid"))
return ValidateOptionsResult.Fail("Name must not contain 'invalid'.");
return ValidateOptionsResult.Success;
});
// or use a custom validator class
conf.WithValidator<MyCustomValidator>();
});
// IValidateOptions sample
internal class MyCustomValidator : IValidateOptions<UserSetting>
{
public ValidateOptionsResult Validate(string? name, UserSetting options)
{
if (options.Age < 10)
return ValidateOptionsResult.Fail("Age must be at least 10.");
if (options.Age > 100)
return ValidateOptionsResult.Fail("Age must be 100 or less.");
return ValidateOptionsResult.Success;
}
}
[!NOTE]
Validation at startup is intentionally not provided. The reason is that in the case of user settings, it is preferable to prompt for correction rather than prevent startup when a validation error occurs.
CloneStrategy
To improve performance, the configuration file is not read every time. Instead, it is loaded and stored as an internal cache when a change event is detected.
To prevent direct editing of this cache, a deep copy is created and provided to the user each time it is retrieved or saved.
By default, JSON serialization (UseJsonCloneStrategy()) is used for deep copying.
Internally, it works as follows:
// internal code
var json = JsonSerializer.Serialize(value);
return JsonSerializer.Deserialize<T>(json)!;
While this approach is not very performant, it ensures that a clone can be reliably created for any serializable object, making it the default method.
Of course, if a custom clone strategy is required, it can be freely specified.
conf.UseCustomCloneStrategy(original => {
// Any custom cloning library can be used
return original.DeepClone();
});
Advanced Usage
Support NativeAOT
By applying a few settings, you can run this library in NativeAOT environments. The following three settings are required:
Specify TypeInfoResolver in JsonFormatProvider
Use a NativeAOT-compatible CloneStrategy
If using DataAnnotations, disable the built-in validation and use a Source Generator-based validator
// 1. customize the provider and file writer
conf.FormatProvider = new JsonFormatProvider()
{
JsonSerializerOptions =
{
TypeInfoResolver = SampleSettingSerializerContext.Default,
},
};
// 2. customize the cloning strategy
// in NativeAOT, use Source Generation for JSON serialization
conf.UseJsonCloneStrategy(SampleSettingSerializerContext.Default.SampleSetting);
// 3. If use DataAnnotation validation with Source Generators,
// see SampleSettingValidator class in this project and comment out below code.
conf.UseDataAnnotationsValidation = false;
conf.WithValidator<SampleSettingValidator>();
// ------
public record SampleSetting { /* ... */ }
// add source generation context
[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(SampleSetting))]
public partial class SampleSettingSerializerContext : JsonSerializerContext;
// add validator with source generation
[OptionsValidator]
public partial class SampleSettingValidator : IValidateOptions<SampleSetting>;
If you want to manage multiple settings of the same type, you must specify different InstanceName for each setting.
// first setting
builder.Services.AddWritableOptions<UserSetting>("First", conf => {
conf.UseFile("firstsettings.json");
});
// second setting
builder.Services.AddWritableOptions<UserSetting>("Second", conf => {
conf.UseFile("secondsettings.json");
});
And use IReadOnlyNamedOptions<T> and IWritableNamedOptions<T> to access them.
// use IReadOnlyNamedOptions<T> to read, IWritableNamedOptions<T> to read and write
public class MyService(IWritableNamedOptions<UserSetting> options)
{
public async Task GetAndSaveAsync()
{
var firstSetting = options.Get("First");
var secondSetting = options.Get("Second");
await options.SaveAsync("First", setting => {
setting.Name = "first name";
});
await options.SaveAsync("Second", setting => {
setting.Name = "second name";
});
// If specifying the name each time is cumbersome, you can also use GetSpecifiedInstance
// By doing so, you can handle it in the same way as regular IReadOnlyOptions/IWritableOptions.
var firstOptions = options.GetSpecifiedInstance("First");
var firstSetting2 = firstOptions.CurrentValue;
await firstOptions.SaveAsync(setting => {
setting.Name = "first name 2";
});
}
}
// Alternatively, you can also use IWritableOptions<T> with the [FromKeyedService] attribute
public class MyOtherService(
[FromKeyedService("First")]
IWritableOptions<UserSetting> firstOptions
)
{
public async Task GetAndSaveAsync()
{
var firstSetting = firstOptions.CurrentValue;
await firstOptions.SaveAsync(setting => {
setting.Name = "first name";
});
}
}
If RegisterInstanceToContainer is enabled, you can access it as follows:
public class MyService([FromKeyedService("First")] UserSetting options)
{
public void DirectUseNamedInstance()
{
// you can use the instance directly
Console.WriteLine($">> Name: {options.Name}");
}
}
[!NOTE]
When not using DI (direct use of WritableOptions), managing multiple configurations is intentionally not supported.
This is to avoid complicating usage.
Dynamic Add/Remove Options
You can dynamically add or remove writable options at runtime using IWritableOptionsConfigRegistry.
for example, in addition to common application settings, it is useful when you want to have individual settings for each document opened by the user.
// use IWritableOptionsConfigRegistry from DI
public class DynamicOptionsService(IWritableOptionsConfigRegistry<UserSetting> registry)
{
public void AddNewOptions(string instanceName, string filePath)
{
registry.TryAdd(instanceName, conf => {
conf.UseFile(filePath);
});
}
public void RemoveOptions(string instanceName)
{
registry.TryRemove(instanceName);
}
}
// and you can access IOptionsNamedMonitor<T> or IWritableNamedOptions<T> as usual
public class MyService(IWritableNamedOptions<UserSetting> options)
{
public void UseOptions()
{
var commonSetting = options.Get("Common");
var documentSetting = options.Get("UserDocument1");
var name = documentSetting.Name ?? commonSetting.Name ?? "default";
Console.WriteLine($">> Name: {name}");
// and save to specific instance
await options.SaveAsync("UserDocument1", setting => {
setting.Name = "document specific name";
});
}
}
Multiple Settings in a Single File
Using ZipFileProvider, you can save multiple settings classes in a single configuration file.
for example, to save Foo(foo.json) and Bar(bar.json) in configurations.zip:
var zipFileProvider = new ZipFileProvider { ZipFileName = "configurations.zip" };
// initialize each setting with the same file provider
builder.Services.AddWritableOptions<Foo>(conf =>
{
conf.UseFile("foo");
conf.FileProvider = zipFileProvider;
});
builder.Services.AddWritableOptions<Bar>(conf =>
{
conf.UseFile("bar");
conf.FileProvider = zipFileProvider;
});
Testing
If you simply want to obtain IReadOnlyOptions<T> or IWritableOptions<T>, using WritableOptionsStub is straightforward.
using Configuration.Writable.Testing;
var settingValue = new UserSetting();
var options = WritableOptionsStub.Create(settingValue);
// and use options in your test
var yourService = new YourService(options);
yourService.DoSomething();
// settingValue is updated when yourService changes it
Assert.Equal("expected name", settingValue.Name);
If you want to perform tests that actually involve writing to the file system, use WritableOptionsSimpleInstance.
var sampleFilePath = Path.GetTempFileName();
var instance = new WritableOptionsSimpleInstance<UserSetting>();
instance.Initialize(conf => {
conf.UseFile(sampleFilePath);
});
var option = instance.GetOptions();
// and use options in your test
var yourService = new YourService(options);
yourService.DoSomething();
// sampleFilePath now contains the updated settings
var json = File.ReadAllText(sampleFilePath);
Assert.Contains("expected name", json);
Interfaces
Here, we describe the main interfaces provided by this library.
IOptions
Provides the value at application startup.
Even if the configuration file is updated later, accessing through this interface will not reflect the changes.
Named access is not supported. Only the unnamed instance is accessible via the .Value property.
Provides the latest value per request (Scoped). The content of the configuration file at the time the object is created is reflected, and even if the configuration file is updated later, the latest value is not reflected.
Named access is supported via the .Get(name) method.
Provides the latest value at the current time.
When the configuration file is updated, the latest value is automatically reflected.
Both named and unnamed access are supported; for unnamed access, use .CurrentValue, and for named access, use .Get(name).
Change detection is done by registering a callback with the OnChange(Action<T, string> listener) method. Since changes for both unnamed and named instances are detected, you need to identify the target name from the second string argument as needed.
Provides the latest values at the current point in time. When the configuration file is updated, the latest values are automatically reflected.
These are very similar to the IOptionsMonitor mentioned above but have been improved for easier use in the following ways. Unless there is a specific reason, it is recommended to use these interfaces.
A read-only options interface that supports named access.
Use the .Get(name) method to access named options.
Use the OnChange(string name, Action<T> listener) method to monitor changes to specific named options.
Use GetSpecifiedInstance(name) to retrieve a pre-specified IReadOnlyOptions instance.
Both interfaces allow you to retrieve configuration options (e.g., file save locations) using the GetOptionsConfiguration method.
IWritableOptions / IWritableNamedOptions
In addition to the features of IReadOnly(Named)Options, these support saving settings.
Other than the addition of the SaveAsync method, they are the same as the above IReadOnly(Named)Options.
IReadOnlyOptionsMonitor<T>
This interface combines the functionalities of IReadOnlyOptions, IReadOnlyNamedOptions, and IOptionsMonitor<T>.
They are provided mainly to ensure compatibility with codebases that already use IOptionsMonitor<T>.
Therefore, you typically do not need to use these interfaces explicitly.
IWritableOptionsMonitor<T>
This interface combines the functionalities of IWritableOptions, IWritableNamedOptions, and IOptionsMonitor<T>.
Like the above IReadOnlyOptionsMonitor<T>, you typically do not need to use these interfaces explicitly.
License
This project is licensed under the Apache-2.0 License.
