DotNetBrightener.SiteSettings 2025.0.6-preview-400

This is a prerelease version of DotNetBrightener.SiteSettings.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package DotNetBrightener.SiteSettings --version 2025.0.6-preview-400
                    
NuGet\Install-Package DotNetBrightener.SiteSettings -Version 2025.0.6-preview-400
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="DotNetBrightener.SiteSettings" Version="2025.0.6-preview-400" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="DotNetBrightener.SiteSettings" Version="2025.0.6-preview-400" />
                    
Directory.Packages.props
<PackageReference Include="DotNetBrightener.SiteSettings" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add DotNetBrightener.SiteSettings --version 2025.0.6-preview-400
                    
#r "nuget: DotNetBrightener.SiteSettings, 2025.0.6-preview-400"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package DotNetBrightener.SiteSettings@2025.0.6-preview-400
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=DotNetBrightener.SiteSettings&version=2025.0.6-preview-400&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=DotNetBrightener.SiteSettings&version=2025.0.6-preview-400&prerelease
                    
Install as a Cake Tool

DotNetBrightener SiteSettings Module

Overview

The DotNetBrightener SiteSettings module provides a comprehensive solution for managing application-wide configuration settings in .NET applications. It offers a flexible, type-safe approach to storing and retrieving settings with built-in caching, database persistence, and RESTful API endpoints.

Key Features

  • Type-safe settings management with strongly-typed setting classes
  • Database persistence with support for SQL Server and PostgreSQL
  • Built-in caching for optimal performance
  • RESTful API endpoints for CRUD operations
  • Automatic database migrations and schema management
  • Localization support for error messages and descriptions
  • Audit trail with creation/modification tracking
  • Default value merging for backward compatibility

Architecture

The module follows a layered architecture:

  • Controllers: RESTful API endpoints (SiteSettingsController)
  • Services: Business logic (ISiteSettingService, SiteSettingService)
  • Data Access: Repository pattern (ISiteSettingDataService)
  • Models: Setting definitions (SiteSettingBase, SiteSettingWrapper<T>)
  • Storage: Database-specific implementations (SQL Server, PostgreSQL)

Required Dependencies

Core NuGet Packages

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.7" />
<PackageReference Include="Microsoft.Extensions.Localization" Version="9.0.7" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

Database-Specific Packages

For SQL Server:

<PackageReference Include="DotNetBrightener.SiteSettings.Data.Mssql" Version="[latest]" />

For PostgreSQL:

<PackageReference Include="DotNetBrightener.SiteSettings.Data.PostgreSql" Version="[latest]" />

Framework Dependencies

  • DotNetBrightener.Caching.Abstractions: For caching functionality
  • DotNetBrightener.DataAccess.Abstractions: For data access patterns

Integration Steps

Step 1: Install Required Packages

# Core package
dotnet add package DotNetBrightener.SiteSettings

# Choose your database provider
dotnet add package DotNetBrightener.SiteSettings.Data.Mssql
# OR
dotnet add package DotNetBrightener.SiteSettings.Data.PostgreSql

Step 2: Define Your Settings Classes

Create strongly-typed setting classes by inheriting from SiteSettingWrapper<T>:

using DotNetBrightener.SiteSettings.Models;

public class ApplicationSettings : SiteSettingWrapper<ApplicationSettings>
{
    public string ApplicationName { get; set; } = "My Application";
    public string SupportEmail { get; set; } = "support@example.com";
    public int MaxFileUploadSize { get; set; } = 10485760; // 10MB
    public bool EnableNotifications { get; set; } = true;

    public override string SettingName => "Application Settings";
    public override string Description => "General application configuration settings";
}

public class EmailSettings : SiteSettingWrapper<EmailSettings>
{
    public string SmtpServer { get; set; } = "localhost";
    public int SmtpPort { get; set; } = 587;
    public string Username { get; set; }
    public string Password { get; set; }
    public bool EnableSsl { get; set; } = true;

    public override string SettingName => "Email Settings";
    public override string Description => "SMTP configuration for email sending";
}

Step 3: Configure Services in Program.cs

using DotNetBrightener.SiteSettings;
using DotNetBrightener.SiteSettings.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add localization support
builder.Services.AddLocalization();

// Add MVC services
var mvcBuilder = builder.Services.AddControllersWithViews();

// Register SiteSettings API
mvcBuilder.RegisterSiteSettingApi();

// Configure database storage (choose one)
// For SQL Server:
builder.Services.AddSiteSettingsSqlServerStorage(
    builder.Configuration.GetConnectionString("DefaultConnection"));

// For PostgreSQL:
// builder.Services.AddSiteSettingsPostgreSqlStorage(
//     builder.Configuration.GetConnectionString("DefaultConnection"));

// Register your setting types
builder.Services.RegisterSettingType<ApplicationSettings>();
builder.Services.RegisterSettingType<EmailSettings>();

var app = builder.Build();

// Configure the HTTP request pipeline
app.MapControllers();

app.Run();

Step 4: Database Configuration

Add connection string to appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MyApp;Trusted_Connection=true;TrustServerCertificate=true;"
  }
}

The module will automatically create the required database schema and tables on first run.

API Endpoints

The module exposes the following RESTful endpoints:

Get All Available Settings

GET /api/SiteSettings/allSettings

Response:

[
  {
    "settingName": "Application Settings",
    "description": "General application configuration settings",
    "settingType": "MyApp.ApplicationSettings"
  }
]

Get Setting Values

GET /api/SiteSettings/{settingKey}

Example:

GET /api/SiteSettings/MyApp.ApplicationSettings

Response:

{
  "applicationName": "My Application",
  "supportEmail": "support@example.com",
  "maxFileUploadSize": 10485760,
  "enableNotifications": true
}

Get Default Setting Values

GET /api/SiteSettings/{settingKey}/default

Save Setting Values

POST /api/SiteSettings/{settingKey}
Content-Type: application/json

{
  "applicationName": "Updated App Name",
  "supportEmail": "newsupport@example.com",
  "maxFileUploadSize": 20971520,
  "enableNotifications": false
}

Programmatic Usage

Inject and Use Settings Service

using DotNetBrightener.SiteSettings.Abstractions;

[ApiController]
[Route("api/[controller]")]
public class MyController : ControllerBase
{
    private readonly ISiteSettingService _settingService;

    public MyController(ISiteSettingService settingService)
    {
        _settingService = settingService;
    }

    [HttpGet("app-info")]
    public IActionResult GetAppInfo()
    {
        var appSettings = _settingService.GetSetting<ApplicationSettings>();
        
        return Ok(new
        {
            Name = appSettings.ApplicationName,
            Support = appSettings.SupportEmail,
            MaxUpload = appSettings.MaxFileUploadSize
        });
    }

    [HttpPost("update-settings")]
    public IActionResult UpdateSettings([FromBody] ApplicationSettings settings)
    {
        _settingService.SaveSetting(settings);
        return Ok();
    }
}

Configuration Options

Caching Configuration

The module uses the DotNetBrightener caching system. Settings are cached for 10 minutes by default. Configure caching in your startup:

// Add memory caching
builder.Services.AddMemoryCache();

// Or Redis caching
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = "localhost:6379";
});

Database Schema

The module creates tables in the following schema:

SQL Server: SiteSettings.SiteSettingRecord PostgreSQL: site_settings.site_setting_record

Table Structure:

  • Id (bigint, primary key)
  • SettingType (nvarchar(1024)) - Fully qualified type name
  • SettingContent (nvarchar(max)) - JSON serialized settings
  • Audit fields: CreatedDate, CreatedBy, ModifiedDate, ModifiedBy
  • Soft delete fields: IsDeleted, DeletedDate, DeletedBy, DeletionReason

Error Handling

The module provides localized error messages. Common error scenarios:

Setting Type Not Found

{
  "errorMessage": "Setting 'InvalidType' not found"
}

Invalid Setting Type

{
  "errorMessage": "Setting type must inherit from SiteSettingBase"
}

Advanced Features

Custom Contract Resolver

The module uses a custom JSON contract resolver (SiteSettingsContractResolver) for consistent serialization.

Default Value Merging

When retrieving settings, the module automatically merges saved values with default values, ensuring backward compatibility when new properties are added to setting classes.

Audit Trail

All setting changes are automatically tracked with creation and modification timestamps and user information.

Testing

Unit Testing Example

[Test]
public void Should_Save_And_Retrieve_Settings()
{
    // Arrange
    var settings = new ApplicationSettings
    {
        ApplicationName = "Test App",
        SupportEmail = "test@example.com"
    };

    // Act
    _settingService.SaveSetting(settings);
    var retrieved = _settingService.GetSetting<ApplicationSettings>();

    // Assert
    Assert.AreEqual("Test App", retrieved.ApplicationName);
    Assert.AreEqual("test@example.com", retrieved.SupportEmail);
}

Troubleshooting

Common Issues

  1. Database Connection Issues

    • Verify connection string format
    • Ensure database server is accessible
    • Check firewall settings
  2. Migration Issues

    • Ensure proper permissions for schema creation
    • Check if migrations are enabled in configuration
  3. Caching Issues

    • Verify caching service is properly registered
    • Check cache key conflicts
  4. Serialization Issues

    • Ensure setting properties have public getters/setters
    • Avoid circular references in setting objects

Performance Considerations

  • Settings are cached for 10 minutes by default
  • Use appropriate database indexes for SettingType column
  • Consider using Redis for distributed caching in multi-instance deployments

Migration from Other Configuration Systems

From appsettings.json

  1. Create setting classes for your configuration sections
  2. Register setting types in DI container
  3. Migrate values using the API or programmatically
  4. Update code to use ISiteSettingService instead of IConfiguration

From Custom Configuration Tables

  1. Create migration scripts to transform existing data
  2. Map existing columns to setting class properties
  3. Use the SaveSetting method to populate the new system

This integration guide provides everything needed to successfully implement the DotNetBrightener SiteSettings module in your .NET applications.

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on DotNetBrightener.SiteSettings:

Package Downloads
DotNetBrightener.SiteSettings.Data.Mssql

Package Description

DotNetBrightener.SiteSettings.Data.PostgreSql

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2025.0.6-preview-406 75 9/2/2025
2025.0.6-preview-401 73 9/2/2025
2025.0.6-preview-400 66 9/2/2025
2025.0.6-preview-369 182 8/27/2025
2025.0.6-preview-368 176 8/27/2025
2025.0.6-preview-334 158 8/18/2025
2025.0.6-preview-333 111 7/27/2025
2025.0.6-preview-332 444 7/24/2025
2025.0.6-preview-331 444 7/24/2025
2025.0.6-preview-328 443 7/24/2025
2025.0.6-preview-327 282 7/21/2025
2025.0.6-preview-326 296 7/21/2025
2025.0.6-preview-325 215 7/20/2025
2025.0.6-preview-324 206 7/20/2025
2025.0.6-preview-322 211 7/20/2025
2025.0.6-preview-321 212 7/19/2025
2025.0.6-preview-320 211 7/19/2025
2025.0.6-preview-319 123 7/17/2025
2025.0.6-preview-317 116 7/17/2025
2025.0.6-preview-316 117 7/17/2025
2025.0.6-preview-315 118 7/17/2025
2025.0.6-preview-314 114 7/17/2025
2025.0.6-preview-313 116 7/17/2025
2025.0.6-preview-312 118 7/16/2025
2025.0.5 162 7/10/2025
2025.0.5-preview-307 89 7/5/2025
2025.0.4 88 7/5/2025
2025.0.4-preview-305 97 7/4/2025
2025.0.4-preview-304 144 7/1/2025
2025.0.4-preview-299 133 5/31/2025
2025.0.4-preview-298 106 5/30/2025
2025.0.4-preview-296 141 5/30/2025
2025.0.4-preview-295 153 5/29/2025
2025.0.4-preview-293 149 5/26/2025
2025.0.4-preview-292 157 5/26/2025
2025.0.3 148 2/10/2025
2025.0.3-preview-288 109 2/10/2025
2025.0.2 132 1/21/2025
2025.0.2-preview-278 102 1/21/2025
2025.0.2-preview-277 108 12/16/2024
2025.0.1-rc-243301701 372 11/25/2024
2024.0.14.6 139 11/25/2024
2024.0.14.6-rc-243031001 184 10/29/2024
2024.0.14.6-rc-243030701 111 10/29/2024
2024.0.14.6-rc-242840501 120 10/10/2024
2024.0.14.6-rc-242820305 106 10/8/2024
2024.0.14.6-rc-242771401 209 10/3/2024
2024.0.14.6-rc-242770501 102 10/3/2024
2024.0.14.6-rc-242770201 131 10/3/2024
2024.0.14.6-rc-242761801 105 10/2/2024
2024.0.14.6-rc-242761601 117 10/2/2024
2024.0.14.6-rc-242761501 109 10/2/2024
2024.0.14.6-rc-242761401 119 10/2/2024
2024.0.14.6-rc-242760701 120 10/2/2024
2024.0.14.6-rc-242751002 106 10/1/2024
2024.0.14.6-rc-242750901 123 10/1/2024
2024.0.14.6-rc-242750502 112 10/1/2024
2024.0.14.6-rc-242750201 109 10/1/2024
2024.0.14.6-rc-242741501 97 9/30/2024
2024.0.14.6-rc-242730701 137 9/29/2024
2024.0.14.6-preview-2730501 118 9/29/2024
2024.0.14.6-preview-2701501 141 9/26/2024
2024.0.14.6-preview-2620901 160 9/18/2024
2024.0.14.6-preview-2570701 127 9/13/2024
2024.0.14.6-preview-2510703 177 9/7/2024
2024.0.14.6-preview-2480501 140 9/4/2024
2024.0.14.6-preview-2430401 149 8/30/2024
2024.0.14.6-preview-242730701 114 9/29/2024
2024.0.14.6-preview-2421703 113 8/29/2024
2024.0.14.6-preview-2421701 105 8/29/2024
2024.0.14.6-preview-2420901 105 8/29/2024
2024.0.14.6-preview-2390101 137 8/26/2024
2024.0.14.6-preview-2381603 142 8/25/2024
2024.0.14.6-preview-2341601 159 8/21/2024
2024.0.14.6-preview-2321602 147 8/20/2024
2024.0.14.6-preview-2190801 166 8/6/2024
2024.0.14.6-preview-2041501 119 7/22/2024
2024.0.14.6-preview-1920603 187 7/10/2024
2024.0.14.6-preview-1920301 127 7/10/2024
2024.0.14.6-preview-1911302 132 7/9/2024
2024.0.14.6-preview-1901001 151 7/8/2024
2024.0.14.6-preview-1900901 131 7/8/2024
2024.0.14.6-preview-1900801 133 7/8/2024
2024.0.14.6-preview-1860304 124 7/4/2024
2024.0.14.5 212 7/1/2024
2024.0.14.5-preview-1811601 121 6/29/2024
2024.0.14.5-preview-1810501 160 6/29/2024
2024.0.14.5-preview-180132 130 6/28/2024
2024.0.14.5-preview-180131 130 6/28/2024
2024.0.14.5-preview-180121 125 6/28/2024
2024.0.14.4 167 6/27/2024
2024.0.14.4-preview-7 125 6/27/2024
2024.0.14.3 161 6/21/2024
2024.0.14.1 162 6/6/2024
2024.0.14.1-preview 112 6/6/2024
2024.0.14-preview-1 123 6/6/2024
2024.0.13.8-preview 124 6/6/2024
2024.0.13.1-preview-0146 119 6/6/2024
2024.0.12.15803-preview-03 101 6/6/2024
2024.0.12.15608 151 6/4/2024
2024.0.12.15515 214 6/3/2024
2024.0.12.15220 135 5/31/2024
2024.0.12.15220-alpha31-240... 120 5/31/2024
2024.0.12.14911 189 5/28/2024
2024.0.12.14910-alpha28-240... 127 5/28/2024
2024.0.12.14823 156 5/27/2024
2024.0.12.14522-alpha7-2405... 133 5/24/2024
2024.0.12.14514-alpha6-2405... 128 5/24/2024
2024.0.12.14511 159 5/24/2024
2024.0.12.14314 201 5/22/2024
2024.0.12.14114 191 5/20/2024
2024.0.12.12815 186 5/7/2024
2024.0.12.12814 155 5/7/2024
2024.0.12.12721 196 5/6/2024
2024.0.12.12702 188 5/5/2024
2024.0.12.12622 193 5/5/2024
2024.0.12.12514 179 5/4/2024
2024.0.12.12512 180 5/4/2024
2024.0.12.12510 171 5/4/2024
2024.0.12.12420 160 5/3/2024
2024.0.12.12319 117 5/2/2024
2024.0.12.12319-rc-2405021801 103 5/2/2024
2024.0.12.12318 139 5/2/2024
2024.0.12.12215 156 5/1/2024
2024.0.12.12011 156 4/29/2024
2024.0.12.11720 161 4/26/2024
2024.0.12.11719 157 4/26/2024
2024.0.12.11621 166 4/25/2024
2024.0.12.11523 150 4/24/2024
2024.0.12.11522 161 4/24/2024
2024.0.12.11417 172 4/23/2024
2024.0.12.11400 162 4/22/2024
2024.0.12.11316 155 4/22/2024
2024.0.11.10220 161 4/11/2024
2024.0.11.10120 142 4/10/2024
2024.0.11.10119 139 4/10/2024
2024.0.11.10115 145 4/10/2024
2024.0.11.9914 184 4/8/2024
2024.0.11.9901 153 4/7/2024
2024.0.11.9823 165 4/7/2024
2024.0.11.9401 169 4/2/2024
2024.0.11.9301 178 4/1/2024
2024.0.11.9206 161 3/31/2024
2024.0.11.9205 161 3/31/2024
2024.0.11.8200 169 3/21/2024
2024.0.11.8122 147 3/21/2024
2024.0.11.8120 160 3/21/2024
2024.0.11.7320 241 3/13/2024
2024.0.11.7316 176 3/13/2024
2024.0.11.7310 156 3/13/2024
2024.0.11 160 3/13/2024
2024.0.10 188 3/3/2024
2024.0.9 172 2/27/2024
2024.0.8 214 2/1/2024
2024.0.7 168 1/26/2024
2024.0.6 162 1/25/2024
2024.0.5 155 1/24/2024
2024.0.4 150 1/24/2024
2024.0.3 155 1/22/2024
2024.0.2 214 1/10/2024
2024.0.1 171 1/9/2024
2024.0.1-alpha-3 143 1/9/2024
2024.0.1-alpha-2 119 1/9/2024
2024.0.1-alpha-1 151 1/3/2024
2024.0.0 220 12/26/2023
2023.0.27 168 12/21/2023
2023.0.26 156 12/21/2023
2023.0.25 191 12/11/2023
2023.0.24 181 12/8/2023
2023.0.23 163 12/6/2023
2023.0.21 174 12/4/2023
2023.0.20 198 11/27/2023
2023.0.19 170 11/20/2023
2023.0.18 191 10/25/2023
2023.0.17 258 10/22/2023
2023.0.16 209 10/16/2023
2023.0.16-alpha-1 166 10/16/2023
2023.0.15 214 10/14/2023
2023.0.14 176 10/14/2023
2023.0.13 184 10/14/2023
2023.0.12 197 10/14/2023
2023.0.11 195 10/10/2023
2023.0.10 193 10/9/2023
2023.0.9 248 8/16/2023
2023.0.8 239 8/15/2023
2023.0.8-alpha-2 319 5/31/2023
2023.0.7 216 5/12/2023
2023.0.6 405 5/10/2023
2023.0.5 242 5/7/2023
2023.0.4 263 4/22/2023
2023.0.3 287 4/19/2023
2023.0.2 275 4/6/2023
2023.0.1 338 3/13/2023