Kiwify.Kiwi.Configuration 1.0.0

Kiwi Config

Attribute-driven configuration binding for .NET. Declare what your configuration looks like - in code, next to the code that uses it - and let the library do the binding.

Key principle: configuration errors should fail at startup, not at runtime.

The Problem with Standard .NET Configuration

// IConfiguration: stringly-typed, silent failures
var port = int.Parse(config["app:port"] ?? "5000");
var name = config["app:name"] ?? "MyApp";

// ConfigurationBinder.Bind(): implicit, no declared intent
var settings = new AppSettings();
configuration.GetSection("app").Bind(settings);
// Which keys does AppSettings read? What are its defaults? Open the class to find out.

A typo in a key compiles fine. A missing required value surfaces as a NullReferenceException at runtime. Defaults are scattered across the codebase.

The Kiwi Config Approach

The config class is the schema. Every key it reads, every default it applies, and every field it requires is declared directly on the class as an attribute.

using Kiwify.Kiwi.Platform.Configuration.Attributes;

[ConfigSection("app")]
public class AppConfig
{
    [ConfigKey("name", "MyApp")]
    public string Name { get; private set; } = string.Empty;

    [ConfigKey("port", 5000)]
    public int Port { get; private set; }

    [ConfigKey("connection-string", Required = true)]
    public string ConnectionString { get; private set; } = string.Empty;
}

One glance at the class tells you everything: which section it lives in, which keys it reads, what the defaults are, and which fields are mandatory. No separate documentation required.

Installation

<PackageReference Include="Kiwify.Kiwi.Configuration" Version="1.0.0" />

Microsoft.Extensions.Configuration is included transitively. No other dependencies.

Quick Start

using Kiwify.Kiwi.Platform.Configuration;
using Kiwify.Kiwi.Platform.Configuration.Attributes;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()   // env vars override file values
    .Build();

var appConfig = configuration.LoadConfiguration<AppConfig>();

Console.WriteLine($"Starting {appConfig.Name} on port {appConfig.Port}");
// Output: Starting ProductionApp on port 8080

appsettings.json:

{
  "app": {
    "name": "ProductionApp",
    "port": 8080,
    "connection-string": "Server=db.example.com;Database=prod"
  }
}

LoadConfiguration<T> is an extension method on IConfiguration. No DI container is required - it works in CLI tools, test fixtures, and anywhere you have an IConfiguration.

If a required key is missing or a value cannot be converted to the declared type, it throws immediately with a clear message identifying exactly which key failed - at startup, not at runtime.

Nested Configuration

Compose config classes the same way the JSON they come from is composed:

[ConfigSection("app")]
public class AppConfig
{
    [ConfigKey("name", "MyApp")]
    public string Name { get; private set; } = string.Empty;

    [ConfigObject]                       // resolved at "app:database:..."
    public DatabaseConfig Database { get; private set; } = null!;
}

[ConfigSection("database")]
public class DatabaseConfig
{
    [ConfigKey("server", "localhost")]
    public string Server { get; private set; } = string.Empty;

    [ConfigKey("port", 5432)]
    public int Port { get; private set; }
}

{
  "app": {
    "name": "MyApp",
    "database": { "server": "db.example.com", "port": 5432 }
  }
}

Dynamic Defaults

For defaults that cannot be a compile-time constant - environment variables, machine characteristics, generated values - define a static method named GetDefault{PropertyName}:

[ConfigSection("app")]
public class AppConfig
{
    [ConfigKey("instance-id")]
    public string InstanceId { get; private set; } = string.Empty;

    public static string GetDefaultInstanceId() => Environment.MachineName;
}

The method is called only when the key is absent from configuration.

Feature Summary

Type support: string, int, long, double, decimal, bool, DateTime, TimeSpan, Guid, any enum, and string[] / List<string> collections.

Using with Kiwi DI

If you also use Kiwify.Kiwi.DependencyInjection, add [ConfigService] to have your config class auto-loaded and registered as a DI singleton in a single AddKiwiServices() call.

[ConfigSection("app")]
[ConfigService]           // auto-loaded and injected anywhere in the container
public class AppConfig { ... }

Kiwify.Kiwi.Configuration is included transitively by Kiwify.Kiwi.DependencyInjection.

Part of Kiwi Foundation

Kiwi Config is one library in Kiwi Foundation, a suite of .NET frameworks built around a single idea: developers should focus on business logic, not infrastructure boilerplate.