TomRR.SettingsBinder 0.1.0

⚙️ SettingsBinder

A lightweight, zero-boilerplate Roslyn Source Generator that binds [Settings]-annotated classes and structs directly to the .NET Options pattern.

Quick Links

• Sample API guide: SettingsBinder.SampleApi/README.md
• Run the sample: dotnet run --project SettingsBinder.SampleApi/SettingsBinder.SampleApi.csproj

Table of Contents

• Features
• Installation
• Quick Start
• Consuming Settings via IOptions<T>
• Advanced Configuration Pipeline
• Customize Section Names
• Struct Settings
• DataAnnotation Validation
• Non-Web Scenarios
• What Gets Generated?
• Performance
• SettingsBinder.SampleApi
• Package Info
• License
• Changelog

✨ Features

• ✅ Automatic binding of settings from appsettings.json
• ✅ Strongly-typed settings via [Settings] attribute
• ✅ Supports classes and structs
• ✅ Supports IOptions<T>, validation, and DI
• ✅ Source-generated SectionName and registration logic
• ✅ Modular and customizable configuration pipelines
• ✅ Zero reflection, minimal runtime overhead
• ✅ XML Documentation

� Installation

dotnet add package TomRR.SettingsBinder

Or in your project file:

<PackageReference Include="TomRR.SettingsBinder" Version="X.X.X" />

🚀 Quick Start

1. Define a Settings Class

using TomRR.SettingsBinder;

[Settings]
public sealed partial class LoggingSettings
{
    public string? Level { get; init; }
    public string? Format { get; init; }
}

2. Add a Matching Section to appsettings.json

{
  "LoggingSettings": {
    "Level": "Information",
    "Format": "Json"
  }
}

3. Wire Up in Program.cs

var builder = WebApplication.CreateBuilder(args);

// Optional: add default config sources (base path, JSON, user secrets, env vars)
builder.Configuration.AddDefaultConfigurationSources<Program>();

// Registers all [Settings] classes automatically
builder.AddSettingsOptions();

var app = builder.Build();

✅ You're done!

💉 Consuming Settings via IOptions<T>

After calling AddSettingsOptions(), inject settings into your services or endpoints:

app.MapGet("/logging", (IOptions<LoggingSettings> options) => options.Value);

Or in a class via constructor injection:

public class MyService(IOptions<LoggingSettings> options)
{
    private readonly LoggingSettings _settings = options.Value;
}

🧩 Advanced Configuration Pipeline

If you prefer fine-grained control over configuration sources:

using TomRR.SettingsBinder.Advanced;

builder.Configuration
    .WithBasePath()
    .WithJsonFile()
    .WithEnvironmentJsonFile()
    .WithSecrets<Program>()
    .WithEnvironmentVariables();

You can mix & match based on your project needs.

🎛️ Customize Section Names

Override the section name using the attribute constructor:

[Settings("MyCustomSection")]
public sealed partial class AdvancedSettings
{
    public string? Mode { get; init; }
    public bool Enabled { get; init; }
}

This generates SectionName => "MyCustomSection" and binds to:

{
  "MyCustomSection": {
    "Mode": "Debug",
    "Enabled": true
  }
}

Use this when the config section does not match the class name.

🧱 Struct Settings

You can also annotate structs with [Settings]:

[Settings]
public partial struct CacheSettings
{
    public bool Enabled { get; set; }
    public int DurationSeconds { get; set; }
}

This generates ISettings and SectionName just like for classes.

Note: IOptions<T> requires T : class, so structs are excluded from automatic DI registration via AddSettingsOptions(). Bind them manually:

var cache = builder.Configuration
    .GetSection(CacheSettings.SectionName)
    .Get<CacheSettings>();

✅ DataAnnotation Validation

Settings classes support System.ComponentModel.DataAnnotations. The generated binding calls ValidateDataAnnotations() and ValidateOnStart(), so invalid configuration fails at startup:

using System.ComponentModel.DataAnnotations;

[Settings]
public sealed partial class DatabaseSettings
{
    [Required]
    public string ConnectionString { get; set; } = string.Empty;

    [Range(1, 65535)]
    public int Port { get; set; } = 5432;
}

If ConnectionString is missing from appsettings.json, the application will throw an OptionsValidationException at startup.

🖥️ Non-Web Scenarios (Console / Worker Service)

For console apps or worker services that don't have a WebApplicationBuilder, use the IServiceCollection overload:

var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();
services.AddSettingsOptions(config);

✅ What Gets Generated?

Interface

public interface ISettings
{
    static abstract string SectionName { get; }
}

Partial Implementation with SectionName

// For classes:
public sealed partial class LoggingSettings : ISettings
{
    public static string SectionName => "LoggingSettings";
}

// For structs:
public partial struct CacheSettings : ISettings
{
    public static string SectionName => "CacheSettings";
}

Default Configuration Sourcing

public static IConfigurationBuilder AddDefaultConfigurationSources<T>(
    this IConfigurationBuilder builder) where T : class 
    => builder
        .SetBasePath(Directory.GetCurrentDirectory())
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile("appsettings.Development.json", optional: true, reloadOnChange: true)
        .AddUserSecrets<T>()
        .AddEnvironmentVariables();

Automatic Binding with Validation

builder.Services
    .AddOptions<LoggingSettings>()
    .Bind(builder.Configuration.GetSection(LoggingSettings.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

� Performance

• ✅ Zero reflection at runtime (everything is compile-time generated).
• ✅ No ActivatorUtilities, no extra runtime DI overhead.
• ✅ Source generation ensures optimal performance with minimal allocations.

SettingsBinder.SampleApi

This repository includes SettingsBinder.SampleApi, a runnable reference API.

It is designed to:

• exercise all main API features (classes, structs, custom sections, validation, DI)
• expose bound settings via endpoints so you can verify binding works
• provide a runnable walkthrough for users exploring the library

Run it with:

dotnet run --project SettingsBinder.SampleApi/SettingsBinder.SampleApi.csproj

For a detailed coverage map, see SettingsBinder.SampleApi/README.md.

📦 Package Info

📄 License

Licensed under the Apache License 2.0.

📋 Changelog

See CHANGELOG.md for release history.