Diamond.Configuration 2026.0.0

Diamond.Configuration

Diamond.Configuration adds a database-backed provider to .NET configuration. It loads key/value pairs from a database into IConfiguration, so application code can continue to use the normal configuration APIs such as configuration["Services:SMSClient:Host"] and GetSection(...).

Install

dotnet add package Diamond.Configuration

Add the ADO.NET provider package for your database separately. For example, with SQL Server:

dotnet add package Microsoft.Data.SqlClient

Database layout

By default, the provider expects a table named Configurations with these columns:

Create a table with compatible column types and a unique constraint/index on (App, ID) (or on ID when application scoping is disabled). Exact SQL types and identifier quoting depend on the database engine. The library does not create or migrate the table.

For SQL Server, a table matching the default column names can be created like this:

CREATE TABLE [Configurations] --Registry
(
    [App]   varchar(50)  NOT NULL,
    [Id]    varchar(200) NOT NULL,
    [Value] nvarchar(4000)   NULL,
    CONSTRAINT [PK_Configurations] PRIMARY KEY CLUSTERED ([App] ASC, [Id] ASC)
);

If you disable application scoping by setting AppColumnName to null or an empty string, use a unique constraint on ID alone instead.

Configure and load

The provider is lazy: AddDbConfiguration adds its source, and UseDbConfiguration starts it and loads values from the database. Here is a standalone example using SQL Server:

using Microsoft.Data.SqlClient;
using Microsoft.Extensions.Configuration;

builder.AddDbConfiguration(options =>
{
    options.AppId = "API-PROD";
});

string connectionString = builder.Configuration.GetConnectionString("default")!; //read from appsettings.json
builder.Configuration.UseDbConfiguration(options => options.SetConnection<Microsoft.Data.SqlClient.SqlConnection>(connectionString));
//builder.Configuration.UseDbConfiguration(options => options.SetConnection<Oracle.ManagedDataAccess.Client.OracleConnection>(connectionString));
//builder.Configuration.UseDbConfiguration(options => options.SetConnection<Npgsql.NpgsqlConnection>(connectionString));
//builder.Configuration.UseDbConfiguration(options => options.SetConnection<MySql.Data.MySqlClient.MySqlConnection>(connectionString));
//builder.Configuration.UseDbConfiguration(options => options.SetConnection<Microsoft.Data.Sqlite.SqliteConnection>(connectionString));

string? host = builder.Configuration["Services:SMSClient:Host"];

...

//inject
public HomeController(IConfiguration configuration)
{
	string? host = configuration["Services:SMSClient:Host"];
}

OR

using Microsoft.Data.SqlClient;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables()
    .AddDbConfiguration(options =>
    {
        options.AppId = "API-PROD";
    })
    .Build();

string connectionString = configuration.GetConnectionString("default"); //read from appsettings.json
configuration.UseDbConfiguration(options => options.SetConnection<SqlConnection>(connectionString));

string? host = configuration["Services:SMSClient:Host"];

Configuration providers are applied in registration order, and later providers take precedence for duplicate keys. In this example, database values override JSON and environment values with the same key. Register the database source after providers that should have lower precedence.

For a different database, pass its DbConnection type to SetConnection<TConnection>. This method chooses a parameter prefix for common SQL Server, Oracle, MySQL/MariaDB, PostgreSQL, and SQLite connection types. For an unrecognized provider, set DbConnection, ConnectionString, and ParamSymbol explicitly in the options callback.

Options

DbConfigurationOptions supports these main settings:

The watchdog detects changes when the timestamp value changes. When writing through the repository, the library updates this timestamp automatically. If another process edits configuration rows directly, that process should also update the configured timestamp key for other application instances to reload promptly.

Sharing a database across applications and environments

AppId lets multiple applications or deployment environments keep separate configuration sets in the same database table. Rows are selected by the configured application id, so give each distinct application/environment combination its own id—for example, OrdersApi:Development, OrdersApi:Production, or BillingApi:Production. This avoids mixing settings even when different sets use the same configuration keys.

You can choose the id from any configuration source available during startup, such as an environment-specific appsettings.json file or an environment variable, and pass it to DbConfigurationOptions. This makes it possible to switch which set is loaded by changing the selected AppId for that deployment. If AppId is not set, the provider selects rows whose App column is NULL; set AppColumnName to null or empty to disable application scoping entirely.

Protecting keys and values

You can use ASP.NET Core Data Protection to protect keys and/or values stored in the table. Configure the data protection services in the host, create a purpose-specific IDataProtector, and pass it through SetKeyProtector or SetValueProtector:

using Microsoft.AspNetCore.DataProtection;

var protector = dataProtectionProvider.CreateProtector("Diamond.Configuration.Values");
options.SetValueProtector(protector);

Use the same compatible data protection key ring and purpose across application instances that share the database. Protecting configuration values does not encrypt the connection string or database itself. Keep secrets such as connection strings in a secure configuration source.

Notes

• Values are stored as strings, matching the standard IConfiguration model. Bind sections to options with the usual .NET configuration binding APIs.
• Table and column names are inserted into SQL statements as identifiers. Configure them as trusted schema values; SQL parameters protect the values, not identifiers.
• UseDbConfiguration should be called once for each configuration root after the host services needed by its options are available. The first database load occurs when it is called.

Sample

Samples: https://github.com/Hajisharifi/Diamond-Samples/tree/master/DbConfiguration