DotNetSettings 1.2.0

DotNetSettings

A strongly-typed, database-backed application settings library for .NET.

Store your application settings in a database or Redis, update them at runtime without redeployment, and access them anywhere via dependency injection with full type safety.

Features

• Strongly typed settings classes (string, bool, int, DateTime, enums, complex objects)
• Database (EF Core) and Redis (StackExchange.Redis) storage backends
• Settings migrations (seed, rename, update, delete values)
• Built-in caching via IDistributedCache
• Per-property encryption via ASP.NET Core Data Protection
• Property locking (make a setting read-only at runtime)
• Lifecycle events (Loading, Loaded, Saving, Saved)
• Pluggable ISettingsRepository interface for custom backends
• Test helpers (Settings.Fake<T>() and FakeSettingsRepository)

Compatibility

Targets net6.0 and net8.0:

Installation

dotnet add package DotNetSettings

For the EF Core database backend, also add a database provider:

dotnet add package Microsoft.EntityFrameworkCore.Sqlite   # or SqlServer, Npgsql, etc.

Quick Start

1. Define a settings class

using DotNetSettings;
using DotNetSettings.Attributes;

public class GeneralSettings : Settings
{
    public string SiteName { get; set; } = "";
    public bool SiteActive { get; set; }
    public int MaxUploadSizeMb { get; set; }
    public DateTime LaunchedAt { get; set; }

    [Encrypt]
    public string ApiKey { get; set; } = "";

    public override string Group => "general";
}

2. Register with DI

builder.Services.AddDotNetSettings(options =>
{
    options.UseDatabase("Data Source=app.db",
        b => b.UseSqlite("Data Source=app.db"));

    options.EnableCaching(ttl: TimeSpan.FromMinutes(5));

    options.RegisterSettingsFromAssembly(typeof(GeneralSettings).Assembly);
    options.RegisterMigrationsFromAssembly(typeof(CreateInitialSettings).Assembly);
});

builder.Services.AddSettings<GeneralSettings>();

Add AddDistributedMemoryCache() before AddDotNetSettings() when caching is enabled.

3. Use in your code

app.MapGet("/settings", (GeneralSettings settings) => new
{
    settings.SiteName,
    settings.SiteActive
});

app.MapPost("/settings", (GeneralSettings settings, UpdateInput input) =>
{
    settings.SiteName = input.SiteName;
    settings.Save();
    return Results.Ok();
});

Settings Classes

Every settings class:

• Inherits from Settings
• Declares a unique Group property (used as the namespace in the repository)
• Has public get/set properties for each setting value

public class MailSettings : Settings
{
    public string FromAddress { get; set; } = "";
    public string FromName { get; set; } = "";
    public bool SendWelcomeEmail { get; set; }

    public override string Group => "mail";
}

Multiple repositories

Override RepositoryName to direct a settings class to a named repository:

public override string? RepositoryName => "redis";

Migrations

Create a class implementing ISettingsMigration for each schema change:

public class CreateGeneralSettings : ISettingsMigration
{
    public void Up(SettingsMigrator migrator)
    {
        migrator.InGroup("general", m =>
        {
            m.Add("SiteName", "My Site");
            m.Add("SiteActive", true);
            m.Add("MaxUploadSizeMb", 10);
            m.AddEncrypted("ApiKey", "");
        });
    }
}

Migrations run in alphabetical order by class name and are tracked in a settings_migrations table.

Run migrations at startup:

using var scope = app.Services.CreateScope();
var runner = scope.ServiceProvider.GetRequiredService<SettingsMigrationRunner>();
await runner.RunAsync();

Migrator API

Keys use the format "group.PropertyName" outside InGroup, or just "PropertyName" inside it.

Casts

Built-in casts

Register global casts in AddDotNetSettings():

options.AddGlobalCast<DateTime, DateTimeSettingsCast>();
options.AddGlobalCast<DateTimeOffset, DateTimeOffsetSettingsCast>();

Custom casts

Implement ISettingsCast and return it from GetCasts():

public class MySettings : Settings
{
    public MyType Value { get; set; } = new();

    public override Dictionary<string, ISettingsCast> GetCasts() => new()
    {
        [nameof(Value)] = new MyTypeCast()
    };
}

Encryption

Mark individual properties with [Encrypt]:

[Encrypt]
public string ApiKey { get; set; } = "";

Or override GetEncryptedProperties() on the settings class:

public override string[] GetEncryptedProperties() =>
    new[] { nameof(ApiKey), nameof(SecretToken) };

Encryption uses ASP.NET Core Data Protection. Call services.AddDataProtection() before AddDotNetSettings().

Locking

Lock a property to prevent it being overwritten on Save():

settings.Lock(nameof(GeneralSettings.SiteName));

// Check
bool locked = settings.IsLocked(nameof(GeneralSettings.SiteName));

// List all
string[] locked = settings.GetLockedProperties();

// Unlock
settings.Unlock(nameof(GeneralSettings.SiteName));

Locked properties retain their stored value even if the in-memory instance has a different value.

Caching

Enable caching in AddDotNetSettings():

services.AddDistributedMemoryCache(); // or AddStackExchangeRedisCache(...)

builder.Services.AddDotNetSettings(options =>
{
    options.EnableCaching(ttl: TimeSpan.FromMinutes(5));
    // ...
});

The cache is keyed by dotnetsettings:{group} and invalidated automatically on Save().

Events

Register a custom ISettingsEventPublisher to hook into the settings lifecycle:

services.AddSingleton<ISettingsEventPublisher, MyEventPublisher>();

Events fired:

Sample Projects

Testing

Settings.Fake<T>()

Create a settings instance without any repository for unit tests:

var settings = Settings.Fake<GeneralSettings>(new()
{
    [nameof(GeneralSettings.SiteName)] = "Test Site",
    [nameof(GeneralSettings.SiteActive)] = true
});

Assert.Equal("Test Site", settings.SiteName);

FakeSettingsRepository

Use an in-memory repository for integration tests:

var repo = new FakeSettingsRepository();
repo.SetPropertyInternal("general", "SiteName", "\"My Site\"");

var manager = new SettingsManager(repo);
var settings = new GeneralSettings();
settings.Repository = repo;
settings.Manager = manager;
manager.Load(settings);

Assert.Equal("My Site", settings.SiteName);