DEV Community: Ajay Jain

Introducing Kiwi Config: Simplifying Configuration Management in .NET Ecosystems

Ajay Jain — Wed, 06 May 2026 10:08:06 +0000

Introduction to Kiwi Config

Kiwi Config (Kiwify.Kiwi.Configuration) is an attribute-driven configuration library for .NET. This article walks through every concept and feature with detailed explanations and practical examples - from the simplest binding to nested hierarchies, dynamic defaults, and collection handling.

The Problem Kiwi Config Solves

Every .NET application reads configuration. The platform gives you IConfiguration, which is flexible but stringly-typed. A call like config["database:port"] compiles regardless of whether that key exists. A typo is silent. A missing key returns null. The code that reads configuration is scattered across the application, and there is no single place that says "this is everything this service reads from config."

ConfigurationBinder.Bind() and IOptions<T> improve on this by binding to typed objects, but they work by name matching convention - the class does not explicitly declare which key it reads, what default to use when the key is absent, or which fields are required. You learn about required-field problems at runtime, not at load time.

Kiwi Config takes a different position: configuration errors should fail at startup, not at runtime. If your service can start, its configuration is valid.

The config class is the schema. Every key a class reads, every default it applies, and every field it requires is declared as an attribute directly on the class. The library reads those declarations once at startup and populates the object. After that, the rest of the application works with a strongly-typed, fully-populated object - no string lookups, no nullable coalescing, no silent failures.

Implicit vs. Explicit Schema

Traditional .NET configuration uses an implicit schema: what a class reads from config is scattered across string lookups, discoverable only by reading the calling code. Kiwi Config uses an explicit schema: the class declares everything it reads, and the library enforces it at load time.

	`IConfiguration` (traditional)	Kiwi Config
Schema location	Scattered across call sites	Declared on the class
Defaults	Hardcoded at each call site	`[ConfigKey("key", defaultValue)]`
Required fields	Not enforced	`Required = true` - validated at startup
Failure point	Runtime - first access of a missing key	Startup - before the app handles requests
Discovery	Read all callers	Open the file

The same information that was once implied is now declared. That is the complete picture of what changes.

Source & Repository

Kiwi Config is open-source and available on GitHub:

https://github.com/kiwifylabs/kiwi-foundation-config-di

Installation

NuGet Package

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

.NET CLI

dotnet add package Kiwify.Kiwi.Configuration --version 1.0.0

Source Code

https://github.com/kiwifylabs/kiwi-foundation-config-di

No other packages are required. Microsoft.Extensions.Configuration is included transitively.

Introducing Kiwi DI: Simplifying Dependency Injection in .NET Ecosystems

The Basics: Your First Config Class

A config class needs two things: a [ConfigSection] attribute on the class that declares where in the configuration hierarchy the class lives, and [ConfigKey] attributes on each property that declare which key to read and what default to use.

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("debug", false)]
    public bool Debug { get; private set; }
}

appsettings.json:

{
  "app": {
    "name": "ProductionApp",
    "port": 8080,
    "debug": false
  }
}

To load it:

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

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

var appConfig = configuration.LoadConfiguration<AppConfig>();
Console.WriteLine(appConfig.Name);  // ProductionApp
Console.WriteLine(appConfig.Port);  // 8080
Console.WriteLine(appConfig.Debug); // False

LoadConfiguration<T> is an extension method on IConfiguration. It creates a new instance of T and walks every property with a [ConfigKey] attribute, reads the value from configuration, converts it to the property type, and sets it. It returns the fully populated instance.

`[ConfigSection]` - Declaring the Root Key

[ConfigSection] tells the library which key in the configuration hierarchy this class belongs to.

[ConfigSection("database")]
public class DatabaseConfig { ... }

When you call configuration.LoadConfiguration<DatabaseConfig>(), the library uses "database" as the prefix for every key it reads from that class. A property bound to "port" reads "database:port" from IConfiguration.

What [ConfigSection] is not:

It is not an absolute path. The key is always the starting prefix, and nested objects append to it.
It cannot use / to escape to the root. Only [ConfigKey] supports absolute paths.
Every class passed directly to LoadConfiguration<T>() must have [ConfigSection]. Every class used as a [ConfigObject] property must also have it.

`[ConfigKey]` - Binding a Property

[ConfigKey] maps a property to a configuration key within the class's section.

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

The first argument is the key name (relative to the section). The second argument is the default value used when the key is absent from configuration.

Setter support

Private setters, protected setters, and init-only properties are all supported. The library sets values via reflection. The init restriction is compiler-enforced at compile time, not at runtime, so reflection bypasses it cleanly.

[ConfigKey("timeout", 30)]
public int Timeout { get; private set; }   // private setter - supported

[ConfigKey("name", "default")]
public string Name { get; init; } = string.Empty;  // init-only - supported

No default

If you omit the default argument and the key is absent, the property gets the type's zero value (0, false, null). For strings, that means null. If you want string.Empty instead, use [ConfigKey("key", "")] or a GetDefaultName() method. This is the lowest-priority fallback.

[ConfigKey("retryCount")]
public int RetryCount { get; private set; }  // gets 0 if absent

Property Initializers

Property initializers run before configuration binding. The library always overwrites the property - whether it sets a config value, an attribute default, a GetDefault* result, or a type zero value. Initializers are not part of the fallback chain and have no effect on what value the property ends up with after loading.

[ConfigKey("timeout", 30)]
public int Timeout { get; private set; } = 60;  // 60 is always overwritten by binding

This also affects string properties. If a string property has no config value and no default, it will be null after loading, even if the initializer sets it to string.Empty:

[ConfigKey("name")]
public string Name { get; private set; } = "fallback";  // overwritten - gets null if absent

Use [ConfigKey("name", "")] or GetDefaultName() if you need a non-null fallback.

Type Conversions

The library converts configuration string values to property types automatically.

Integers, longs, doubles, decimals

Standard numeric parsing. A value that cannot be converted throws InvalidOperationException immediately with the key path and failed value in the message.

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

[ConfigKey("maxFileSize", 104857600L)]
public long MaxFileSize { get; private set; }

[ConfigKey("threshold", 0.95)]
public double Threshold { get; private set; }

Booleans

Booleans accept a wider set of truthy and falsy strings than strict "true"/"false" parsing. This matches how boolean flags commonly appear in environment variables and configuration files.

Truthy	Falsy
`true`, `1`, `yes`, `on`, `enabled`	`false`, `0`, `no`, `off`, `disabled`

[ConfigKey("metricsEnabled", false)]
public bool MetricsEnabled { get; private set; }

Config value "yes" → true. Config value "off" → false. Any other value throws.

Enums

Enum values are parsed case-insensitively. The enum type is inferred from the property type.

public enum AppEnvironment { Development, Staging, Production }

[ConfigKey("environment", AppEnvironment.Development)]
public AppEnvironment Environment { get; private set; }

Config value "production" or "Production" → AppEnvironment.Production. An unrecognised value throws InvalidOperationException naming the key and the bad value.

Strings

Strings are passed through as-is - no conversion required.

[ConfigKey("connectionString", "")]
public string ConnectionString { get; private set; } = string.Empty;

Default Value Resolution

When a key is absent from configuration, the library resolves a fallback using four levels of priority:

Priority	Source	Example
1 (highest)	Value present in `IConfiguration`	`appsettings.json`, environment variable
2	`DefaultValue` argument on `[ConfigKey]`	`[ConfigKey("port", 5432)]`
3	`GetDefault{PropertyName}()` static method	`private static int GetDefaultPort()`
4 (lowest)	Type's zero value	`0`, `false`, `null`

If [ConfigKey] carries a DefaultValue, the library never calls GetDefault* - the attribute default takes precedence entirely.

[ConfigKey("port", 5432)]     // uses 5432 if absent; GetDefaultPort() is never called
public int Port { get; private set; }

[ConfigKey("maxConnections")] // no attribute default; GetDefaultMaxConnections() is called
public int MaxConnections { get; private set; }

[ConfigKey("name")]           // no attribute default, no GetDefault*; gets "" if absent
public string Name { get; private set; } = string.Empty;

Required Fields

Mark a field as required when it must always be present in configuration and has no sensible default.

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

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

When the key is absent and Required = true:

The library does not fall through to GetDefault* or the type default.
LoadConfiguration<T> throws InvalidOperationException immediately.
The error message includes the full key path and the property name.

InvalidOperationException: Required configuration key 'app:apiKey' is missing
and no default value is provided. Property: AppConfig.ApiKey.

Required = true combined with a DefaultValue is technically valid but redundant - the default satisfies the requirement before it can fire.

The `GetDefault` Convention

When a default needs to be computed rather than hardcoded - based on environment variables, machine characteristics, or external state - define a static method named GetDefault{PropertyName}() on the class.

[ConfigSection("database")]
public partial class DatabaseConfig
{
    [ConfigKey("maxConnections")]
    public int MaxConnections { get; private set; }

    [ConfigKey("commandTimeout")]
    public int CommandTimeout { get; private set; }
}

public partial class DatabaseConfig
{
    // Called when "database:maxConnections" is absent from config
    private static int GetDefaultMaxConnections()
        => Environment.ProcessorCount * 4;

    // Called when "database:commandTimeout" is absent from config
    private static int GetDefaultCommandTimeout()
        => int.TryParse(Environment.GetEnvironmentVariable("DEFAULT_TIMEOUT"), out var t) ? t : 30;
}

The method is split into a partial class here to keep the defaults separate from the config declarations - a common pattern, not a requirement.

Rules for the method:

Must be static. Access modifier does not matter (private, internal, public all work).
Return type must exactly match the property type. A mismatch is detected at load time and throws.
Must accept no parameters. A method with parameters is detected at load time and throws.
If the method throws, the exception propagates uncaught through LoadConfiguration<T>. Guard against exceptions within the method if needed.
GetDefault* is never called when [ConfigKey] carries an attribute default - it is only the third-priority fallback.

Nested Configuration with `[ConfigObject]`

Configuration naturally forms hierarchies. A database section might contain a credentials sub-section. An app section might contain a caching sub-section. [ConfigObject] composes config classes to match the JSON structure.

How path resolution works

When the library encounters a [ConfigObject] property, it reads the nested type's [ConfigSection] key and appends it to the current path prefix using :. All properties of the nested type are then resolved relative to this new prefix.

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

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

[ConfigSection("database")]
public class DatabaseConfig
{
    [ConfigKey("server")]
    public string Server { get; private set; } = string.Empty;
    // reads: "app:database:server"

    [ConfigKey("port", 5432)]
    public int Port { get; private set; }
    // reads: "app:database:port"

    [ConfigObject]
    public CredentialsConfig Credentials { get; private set; } = null!;
    // nested prefix: "app:database:credentials"
}

[ConfigSection("credentials")]
public class CredentialsConfig
{
    [ConfigKey("username")]
    public string Username { get; private set; } = string.Empty;
    // reads: "app:database:credentials:username"

    [ConfigKey("password", Required = true)]
    public string Password { get; private set; } = string.Empty;
    // reads: "app:database:credentials:password"
}

appsettings.json:

{
  "app": {
    "name": "OrderService",
    "database": {
      "server": "db.prod.example.com",
      "port": 5432,
      "credentials": {
        "username": "svc_orders",
        "password": "s3cr3t"
      }
    }
  }
}

Loading AppConfig populates the entire hierarchy in one call:

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

Console.WriteLine(appConfig.Name);                          // OrderService
Console.WriteLine(appConfig.Database.Server);               // db.prod.example.com
Console.WriteLine(appConfig.Database.Port);                 // 5432
Console.WriteLine(appConfig.Database.Credentials.Username); // svc_orders
Console.WriteLine(appConfig.Database.Credentials.Password); // s3cr3t

Nested types and DI registration

When using Kiwi Config with Kiwi DI, only root config classes need [ConfigService] to be auto-loaded. Nested types like DatabaseConfig and CredentialsConfig in the example above are loaded as part of their parent - they do not need their own [ConfigService] unless you want them registered independently as well.

Circular reference detection

If a [ConfigObject] chain references a type that is already in its own ancestor chain, the library detects the cycle and throws InvalidOperationException. The check is per-load-call and tracks only the current path, so the same type can safely appear in separate, independent branches of the hierarchy.

Absolute Key Paths

Sometimes a property needs to read a value from an entirely different part of the configuration hierarchy - perhaps a global setting that is shared across sections. The / prefix on a [ConfigKey] key escapes the current section prefix and reads from the configuration root.

[ConfigSection("app")]
public class AppConfig
{
    [ConfigKey("name")]
    public string Name { get; private set; } = string.Empty;
    // reads "app:name" (normal, relative to section)

    [ConfigKey("/globalTimeout", 30)]
    public int GlobalTimeout { get; private set; }
    // reads root-level "globalTimeout" - the "app:" prefix is ignored
}

appsettings.json:

{
  "globalTimeout": 60,
  "app": {
    "name": "MyApp"
  }
}

var appConfig = configuration.LoadConfiguration<AppConfig>();
Console.WriteLine(appConfig.GlobalTimeout); // 60 - from root level

Important: The / prefix applies only to [ConfigKey]. There is no equivalent for [ConfigSection] - section keys are always appended to the parent prefix. Only individual properties can escape the hierarchy.

Absolute paths also work inside nested types:

[ConfigSection("database")]
public class DatabaseConfig
{
    [ConfigKey("port", 5432)]
    public int Port { get; private set; }
    // reads "app:database:port" when nested under AppConfig

    [ConfigKey("/sharedSecret", Required = true)]
    public string SharedSecret { get; private set; } = string.Empty;
    // reads root-level "sharedSecret" regardless of nesting depth
}

Collections

Properties typed as arrays or lists are populated by splitting a comma-separated configuration string.

[ConfigSection("app")]
public class AppConfig
{
    [ConfigKey("allowedPorts", "80,443,8080")]
    public int[] AllowedPorts { get; private set; } = Array.Empty<int>();

    [ConfigKey("allowedOrigins")]
    public List<string> AllowedOrigins { get; private set; } = new();

    [ConfigKey("featureFlags")]
    public string[] FeatureFlags { get; private set; } = Array.Empty<string>();
}

appsettings.json:

{
  "app": {
    "allowedPorts": "80,443,8080",
    "allowedOrigins": "https://app.example.com,https://admin.example.com",
    "featureFlags": "analytics,darkMode,betaApi"
  }
}

Supported collection types: T[], List<T>, and any type implementing IEnumerable<T>, IList<T>, or ICollection<T>.

⚠️ Collection Format Limitation

Kiwi Config expects collections as comma-separated strings. JSON array syntax is not supported.

Supported:

{ "app": { "allowedPorts": "80,443,8080" } }

Not supported - will not be parsed as a collection:

{ "app": { "allowedPorts": [80, 443, 8080] } }

If your configuration source uses JSON array syntax, use IConfiguration.GetSection(...).Get<T[]>() directly instead of [ConfigKey].

Edge cases

Input	Behaviour
`"8080, 8443"` (spaces around commas)	Whitespace is trimmed - produces `[8080, 8443]`
`"value1,,value2"` (double comma)	Empty entries are removed - produces `["value1", "value2"]`
`""` (empty string)	Returns an empty collection
`"80,abc"` for `int[]`	Throws `InvalidOperationException` naming the key and the bad element

Using `LoadConfiguration<T>` Standalone

No DI container is required. LoadConfiguration<T> works anywhere you have an IConfiguration - whether or not a service collection exists.

CLI tools

[ConfigSection("tool")]
public class ToolConfig
{
    [ConfigKey("outputPath", "./output")]
    public string OutputPath { get; private set; } = string.Empty;

    [ConfigKey("verbose", false)]
    public bool Verbose { get; private set; }

    [ConfigKey("maxThreads")]
    public int MaxThreads { get; private set; }

    private static int GetDefaultMaxThreads() => Environment.ProcessorCount;
}

var configuration = new ConfigurationBuilder()
    .AddJsonFile("tool.json", optional: true)
    .AddEnvironmentVariables(prefix: "TOOL_")
    .AddCommandLine(args)
    .Build();

var toolConfig = configuration.LoadConfiguration<ToolConfig>();
// Use toolConfig directly - no service collection needed

Test helpers

var inMemoryConfig = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["database:host"] = "localhost",
        ["database:port"] = "5432",
        ["database:name"] = "testdb"
    })
    .Build();

var dbConfig = inMemoryConfig.LoadConfiguration<DatabaseConfig>();
// Use dbConfig to construct the class under test directly

In-memory configuration is particularly useful in tests because it does not require files on disk and the values are explicit in the test code.

Pre-container startup code

// Read config before the DI container is built - for use in middleware setup, logging, etc.
var appConfig = configuration.LoadConfiguration<AppConfig>();
SetupLogging(appConfig.LogLevel);
ConfigureMiddleware(appConfig.Port);

// Later: pass the already-loaded instance to the DI container
services.AddKiwiServices(configuration, preLoadedConfigs: appConfig);

Logging

Pass an ILogger to LoadConfiguration<T> to receive a detailed trace of what the library does during binding. This is useful during development and debugging.

var logger = loggerFactory.CreateLogger<DatabaseConfig>();
var dbConfig = configuration.LoadConfiguration<DatabaseConfig>(logger);

Example output at Debug level:

dbg: Loading configuration for DatabaseConfig from section 'database'
dbg: Loaded config 'database:host' = db.prod.example.com
dbg: Loaded config 'database:port' = 5432 (default from: attribute)
dbg: Loaded config 'database:maxConnections' = 16 (default from: method:GetDefaultMaxConnections)
dbg: Loading nested configuration object 'Credentials' from section 'database:credentials'
dbg: Loaded config 'database:credentials:username' = svc_orders
dbg: Loaded config 'database:credentials:password' = *****
inf: Successfully loaded configuration for DatabaseConfig

The library logs the raw value it resolves for each property. Sensitive values should be masked by the caller before logging - LoadConfiguration<T> has no built-in concept of sensitive keys.

Event	Level
Starting load for a config type	`Debug`
Property bound from config	`Debug`
Property resolved from a default	`Debug` (includes default source: `attribute`, `method:GetDefaultXxx`, `type-default`)
Nested object starting	`Debug`
Config type loaded successfully	`Information`
Property load failure	Propagates as exception - no log entry

Logging is optional. Omit the logger argument when you do not need the output.

Error Messages

Errors include the full key path, the property name, and a description of what went wrong. They are all thrown as InvalidOperationException.

Configuration error at 'database:port': Cannot convert value 'abc' to type Int32.
  Check your configuration file. Details: Input string was not in a correct format.

Required configuration key 'app:apiKey' is missing and no default value is provided.
  Property: AppConfig.ApiKey.

Nested configuration type 'DatabaseConfig' used with [ConfigObject] must have [ConfigSection].
  Property: AppConfig.Database.

Circular reference detected in configuration hierarchy: Type 'DatabaseConfig' references itself
  either directly or through nested objects.

Default method 'DatabaseConfig.GetDefaultPort()' has wrong return type.
  Expected 'Int32', but got 'String'.

Default method 'DatabaseConfig.GetDefaultPort()' must have no parameters.

All errors surface at load time - at startup, before the application enters its request-handling loop. There are no silent failures.

Validation Beyond Required Fields

Kiwi Config intentionally does not support range checks, format validation, or cross-property rules. The library validates structure (required keys, correct types, valid enum values) and stops there.

For additional constraints, validate the populated object immediately after loading:

var dbConfig = configuration.LoadConfiguration<DatabaseConfig>();

if (dbConfig.MaxConnections is < 1 or > 1000)
    throw new InvalidOperationException("MaxConnections must be between 1 and 1000.");

if (!Uri.TryCreate(dbConfig.BrokerUrl, UriKind.Absolute, out _))
    throw new InvalidOperationException($"BrokerUrl is not a valid URI: {dbConfig.BrokerUrl}");

This keeps validation visible and co-located with the loading code. It also keeps the library focused.

Performance Guidance

LoadConfiguration<T> uses reflection to discover and populate properties.

Call once, store the result. The library does not cache. Each call does a full reflection walk and creates a new instance. Call LoadConfiguration<T>() once at startup and store or register the result.
Not for hot paths. Do not call it inside request handlers, loops, or frequently-executed code.
Thread safe. Multiple concurrent calls are safe - the method operates on independent instances with no shared mutable state.
Startup cost scales with depth. A deep nested hierarchy with many properties costs more than a flat class, but the cost is paid once at startup, not per request. Typical startup cost is in the range of microseconds to a few milliseconds, depending on the size of the configuration graph.

The expected pattern:

// At startup - once
var dbConfig = configuration.LoadConfiguration<DatabaseConfig>();
services.AddSingleton(dbConfig);

// In application code - injected, no further loading
public class OrderRepository(DatabaseConfig db) { ... }

Complete Real-World Example

A microservice configuration with every feature of the library in use.

appsettings.json:

{
  "globalRateLimit": 1000,
  "service": {
    "name": "OrderService",
    "environment": "Production",
    "port": 5000,
    "allowedOrigins": "https://app.example.com,https://admin.example.com"
  },
  "database": {
    "connectionString": "Host=db.prod.example.com;Database=orders;Username=svc_orders",
    "commandTimeoutSeconds": 30,
    "retryAttempts": 3,
    "credentials": {
      "username": "svc_orders",
      "password": "s3cr3t"
    }
  },
  "messaging": {
    "brokerUrl": "amqp://rabbit.prod.example.com",
    "exchangeName": "orders",
    "prefetchCount": 10
  }
}

Config classes:

using Kiwify.Kiwi.Platform.Configuration.Attributes;

public enum AppEnvironment { Development, Staging, Production }

// Root service config - reads a root-level value via absolute path
[ConfigSection("service")]
public class ServiceConfig
{
    [ConfigKey("name", Required = true)]
    public string Name { get; private set; } = string.Empty;

    [ConfigKey("environment", AppEnvironment.Development)]
    public AppEnvironment Environment { get; private set; }

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

    [ConfigKey("allowedOrigins")]
    public string[] AllowedOrigins { get; private set; } = Array.Empty<string>();

    // Reads root-level "globalRateLimit", not "service:globalRateLimit"
    [ConfigKey("/globalRateLimit", 500)]
    public int RateLimit { get; private set; }
}

// Database config with nested credentials and a computed default
[ConfigSection("database")]
public partial class DatabaseConfig
{
    [ConfigKey("connectionString", Required = true)]
    public string ConnectionString { get; private set; } = string.Empty;

    [ConfigKey("commandTimeoutSeconds", 30)]
    public int CommandTimeoutSeconds { get; private set; }

    [ConfigKey("retryAttempts", 3)]
    public int RetryAttempts { get; private set; }

    // No attribute default - computed dynamically
    [ConfigKey("maxConnections")]
    public int MaxConnections { get; private set; }

    [ConfigObject]
    public CredentialsConfig Credentials { get; private set; } = null!;
}

public partial class DatabaseConfig
{
    private static int GetDefaultMaxConnections() => Environment.ProcessorCount * 4;
}

// Nested credentials - loaded as part of DatabaseConfig
[ConfigSection("credentials")]
public class CredentialsConfig
{
    [ConfigKey("username", Required = true)]
    public string Username { get; private set; } = string.Empty;

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

// Messaging config - simple flat section
[ConfigSection("messaging")]
public class MessagingConfig
{
    [ConfigKey("brokerUrl", Required = true)]
    public string BrokerUrl { get; private set; } = string.Empty;

    [ConfigKey("exchangeName", "default")]
    public string ExchangeName { get; private set; } = string.Empty;

    [ConfigKey("prefetchCount", 10)]
    public int PrefetchCount { get; private set; }
}

Loading all configs standalone - no DI container required:

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

var service   = configuration.LoadConfiguration<ServiceConfig>();
var database  = configuration.LoadConfiguration<DatabaseConfig>();
var messaging = configuration.LoadConfiguration<MessagingConfig>();

Console.WriteLine($"{service.Name} [{service.Environment}] on :{service.Port}");
// OrderService [Production] on :5000

Console.WriteLine($"Rate limit: {service.RateLimit} req/s");
// Rate limit: 1000 req/s  (from root-level "globalRateLimit")

Console.WriteLine($"DB: {database.ConnectionString}");
Console.WriteLine($"DB connections: {database.MaxConnections}");
// DB connections: 16  (from GetDefaultMaxConnections(), 4 cores * 4)

Console.WriteLine($"DB credentials: {database.Credentials.Username}@...");
// DB credentials: svc_orders@...

Console.WriteLine($"MQ: {messaging.BrokerUrl} / {messaging.ExchangeName} (prefetch={messaging.PrefetchCount})");
// MQ: amqp://rabbit.prod.example.com / orders (prefetch=10)

Validation after load:

if (database.CommandTimeoutSeconds is < 1 or > 300)
    throw new InvalidOperationException("CommandTimeoutSeconds must be between 1 and 300.");

if (messaging.PrefetchCount < 1)
    throw new InvalidOperationException("PrefetchCount must be at least 1.");

When used with Kiwi DI, adding [ConfigService] to each class means a single services.AddKiwiServices(configuration) call loads and registers all of them automatically.

Configuration Reloading

Kiwi Config loads configuration once and produces an immutable object. There is no mechanism to re-read the configuration source and update the object in place, and the library does not observe IConfiguration change tokens.

This is intentional. Immutable config objects are safe to inject as singletons and share across threads without locks. For most applications - especially server applications where configuration changes require a restart to reason about reliably - this is the right default.

If you need configuration values to update at runtime without restarting the application, use IOptionsMonitor<T> from Microsoft.Extensions.Options. It observes configuration change tokens and provides access to the current value at each call site:

public class MyService(IOptionsMonitor<AppOptions> options)
{
    public void Do()
    {
        var current = options.CurrentValue; // always reflects the latest config
    }
}

Kiwi Config and IOptionsMonitor<T> serve different needs and can coexist in the same application. Use Kiwi Config for startup-critical settings where immutability is a feature; use IOptionsMonitor<T> for settings that must update without a restart.

When to Use Kiwi Config vs `IOptions<T>`

Both libraries bind configuration to typed classes. The difference is in intent and guarantees.

	Kiwi Config	`IOptions<T>` / `IOptionsMonitor<T>`
How binding is declared	Attributes on the class	Convention (property names match config keys) or `Configure<T>()` calls
Default values	Declared on the attribute	Set in code via `Configure<T>()` or property initializers
Required fields	`Required = true` - throws at load time	Not built-in; validate after binding
Failure point	Startup - before the app serves requests	First access of `IOptions<T>.Value`
Reload support	No - object is immutable after load	Yes - `IOptionsMonitor<T>` observes change tokens
DI integration	Optional - works without a container	Requires `IServiceCollection`
Nested hierarchy	`[ConfigObject]` with explicit path composition	Automatic by property name matching

Choose Kiwi Config when:

You want the config class to be self-documenting - all keys, defaults, and requirements visible in one place.
Startup-time validation matters. A missing required key should fail immediately, not on the first request that happens to read the option.
You need computed defaults (GetDefault* methods) or absolute key paths.
You are outside a DI container (CLI tools, test fixtures, startup bootstrapping).

Choose IOptions<T> / IOptionsMonitor<T> when:

You need live reload - configuration values that update without restarting the application.
You are binding to a large set of settings where name-matching convention is less overhead than explicit attributes.
You are working with third-party libraries that already publish their own options types.

The two approaches can coexist in the same application. A common pattern is to use Kiwi Config for your own application settings (where explicitness matters) and IOptionsMonitor<T> for settings that require live reload.

Mental Model

Everything LoadConfiguration<T> does maps to five steps. Once you have this, the rest of the article is detail.

1. Start at [ConfigSection]
The attribute on the class sets the root key. All property lookups are relative to it: [ConfigSection("database")] means every key in the class reads from database:*.

2. Walk properties
For each property on T:

[ConfigKey] - read a scalar value from configuration at section:key
[ConfigObject] - recurse into the nested type, appending its [ConfigSection] key to the current prefix

3. Resolve the value (four-level priority)

1. Value present in IConfiguration          ← wins
2. DefaultValue on [ConfigKey]
3. GetDefault{PropertyName}() static method
4. Type's zero value (0, false, null)       ← last resort

If Required = true and no value is found at levels 1-3, throw immediately.

4. Convert and assign
The resolved string is converted to the property type (int, bool, enum, collection, ...). Conversion failure throws with the key path and bad value in the message. The value is set via reflection - private and init setters are supported.

5. Fail fast on any error
Missing required keys, bad values, circular references, wrong GetDefault* signatures - all throw InvalidOperationException at load time. If LoadConfiguration<T> returns, the object is valid.

Feature Summary

Feature	Attribute / API
Declare config section	`[ConfigSection("key")]` on the class
Bind a property to a key	`[ConfigKey("key")]` on the property
Set a static default	`[ConfigKey("key", defaultValue)]`
Mark a field as required	`[ConfigKey("key", Required = true)]`
Computed dynamic default	`private static T GetDefault{Prop}()` method
Nested config object	`[ConfigObject]` on a property
Read from config root	`[ConfigKey("/rootKey")]` (slash prefix)
Collections (arrays/lists)	Comma-separated config values
Flexible booleans	`true/1/yes/on/enabled`, `false/0/no/off/disabled`
Case-insensitive enums	Auto-parsed by property type
Load a config object	`configuration.LoadConfiguration<T>()`
Load with diagnostics	`configuration.LoadConfiguration<T>(logger)`

Introducing Kiwi DI: Simplifying Dependency Injection in .NET Ecosystems

Ajay Jain — Wed, 06 May 2026 10:07:28 +0000

Introduction to Kiwi DI

Kiwi DI (Kiwify.Kiwi.DependencyInjection) is an attribute-driven dependency injection framework for .NET. It moves service registration from startup code to the classes themselves, enabling config-driven activation, generic expansion, and declarative construction - all with a single AddKiwiServices call.

The Problem Kiwi DI Solves

Standard .NET DI registration works well at small scale. Five services, ten calls to AddScoped and AddSingleton, one startup entry point - manageable. But as an application grows, that startup code grows with it. At fifty services it is a maintenance problem. At one hundred, it is a liability.

The deeper issue is not the line count. It is the disconnection. A class exists in one file. Its DI registration exists in another. To understand how a class is wired-its lifetime, conditions, and interfaces-you have to look in multiple places. To add a feature flag that controls whether a service is active, you edit both the service and the startup code. To swap an implementation, you find and modify the startup block that wires it.

Kiwi DI inverts this relationship: the class declares its own registration rules. An attribute on the class says what its lifetime is, what conditions it depends on, and how it should be constructed. The framework reads those declarations at startup and wires everything automatically. Startup code becomes trivially short - one call - and stays that way regardless of how many services are added.

Source & Repository

Kiwi Config is open-source and available on GitHub:

https://github.com/kiwifylabs/kiwi-foundation-config-di

Installation

NuGet Package

<PackageReference Include="Kiwify.Kiwi.DependencyInjection" Version="1.0.0" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.7" />

Kiwify.Kiwi.Configuration is included transitively.

.NET CLI

dotnet add package Kiwify.Kiwi.DependencyInjection --version 1.0.0

Introducing Kiwi Config: Simplifying Configuration Management in .NET Ecosystems

Source Code

https://github.com/kiwifylabs/kiwi-foundation-config-di

Quick Start

var services = new ServiceCollection();
services.AddKiwiServices(configuration);
var provider = services.BuildServiceProvider();

That single call scans your assembly, loads all [ConfigService] config classes, and registers all [Service] classes - conditionally where specified.

Mental Model

Kiwi DI follows a simple model:

Classes declare what they are - lifetime, interfaces, and construction rules, expressed as attributes on the class itself.
Configuration declares when they are active - a config flag or named predicate controls whether a service enters the container.
The framework decides what gets wired - AddKiwiServices reads those declarations at startup and builds the container automatically.

Everything in this article maps back to one of these three responsibilities.

How `AddKiwiServices` Works

Before looking at individual attributes, it is worth understanding what AddKiwiServices actually does when you call it. Everything else flows from this.

services.AddKiwiServices(configuration);

Internally, this runs four deterministic phases:

Phase 0 (pre-registration):
  Register any pre-loaded config instances passed via preLoadedConfigs

Phase 1 (config discovery):
  Scan assembly for classes carrying both [ConfigSection] and [ConfigService]
  For each: call LoadConfiguration<T>() and register the instance as a singleton

Phase 2 (temporary provider):
  Build a temporary IServiceProvider
  (All config singletons from Phase 1 are now resolvable)

Phase 3 (service discovery):
  Scan assembly for classes carrying [Service]
  For each: evaluate any conditions against the temporary provider
  Register passing services into the real container

Done - call BuildServiceProvider() normally

The temporary provider built in Phase 2 exists only to evaluate conditions. It is never used for actual service resolution. It is discarded when AddKiwiServices returns. The final container is a standard IServiceProvider - Kiwi DI has no presence at runtime.

The Attributes

Kiwi DI uses four attributes. Each is placed on the class that it describes.

Attributes live in Kiwify.Kiwi.Platform.DependencyInjection.Attributes. Extension methods (AddKiwiServices, AddKiwiConfig, AddKiwiService) live in Kiwify.Kiwi.Platform.DependencyInjection.

using Kiwify.Kiwi.Platform.DependencyInjection;            // AddKiwiServices and friends
using Kiwify.Kiwi.Platform.DependencyInjection.Attributes; // [Service], [ConfigService], [RegistersFor], [ConstructFrom]

Attribute	Purpose
`[ConfigService]`	Marks a config class for auto-loading and singleton registration
`[Service(Lifetime)]`	Marks a service class for auto-registration
`[RegistersFor(typeof(T))]`	Expands a generic class into concrete closed-generic registrations
`[ConstructFrom(typeof(C), "Prop")]`	Injects scalar config property values as constructor arguments

`[ConfigService]` - Auto-Loading Configuration

[ConfigService] comes from this library but works together with [ConfigSection] from Kiwi Config. A class carrying both is discovered during Phase 1 and loaded as a config singleton.

using Kiwify.Kiwi.Platform.Configuration.Attributes;
using Kiwify.Kiwi.Platform.DependencyInjection;
using Kiwify.Kiwi.Platform.DependencyInjection.Attributes;

[ConfigSection("database")]   // from Kiwi Config - declares the config key
[ConfigService]               // from Kiwi DI - opts into auto-loading
public class DatabaseConfig
{
    [ConfigKey("host", "localhost")]
    public string Host { get; private set; } = string.Empty;

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

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

After AddKiwiServices runs, DatabaseConfig is in the container as a singleton and can be injected normally:

[Service(ServiceLifetime.Scoped)]
public class OrderRepository
{
    private readonly DatabaseConfig _db;
    public OrderRepository(DatabaseConfig db) => _db = db;
}

What `[ConfigSection]` alone does not do

[ConfigSection] tells Kiwi Config how to load the class. It says nothing about DI. Without [ConfigService], a class is invisible to AddKiwiServices - it still works with configuration.LoadConfiguration<T>() but is not auto-loaded into the container.

This separation matters: you can have config classes that are only ever loaded manually (e.g. before the container is built) without them appearing as singletons in the container.

`[Service]` - Registering a Service

[Service] marks a class for automatic registration. The required argument is the service lifetime.

[Service(ServiceLifetime.Singleton)]
public class GreetingService : IGreetingService { ... }

[Service(ServiceLifetime.Scoped)]
public class OrderService : IOrderService { ... }

[Service(ServiceLifetime.Transient)]
public class EmailFormatter : IEmailFormatter { ... }

Interface resolution

By default, all non-System.* interfaces implemented by the class are registered automatically.

If a class implements no non-system interfaces, it is registered as its concrete type.

public interface IPaymentGateway { ... }
public interface IRetryable { ... }

[Service(ServiceLifetime.Singleton)]
public class StripeGateway : IPaymentGateway, IRetryable { ... }
// Registered as: IPaymentGateway and IRetryable

Registering as self too

RegisterAsSelf = true adds the concrete type registration alongside the interface registrations. Useful when code needs to inject the concrete type directly - for example, when calling methods not on the interface.

[Service(ServiceLifetime.Singleton, RegisterAsSelf = true)]
public class MetricsCollector : IMetricsCollector { ... }
// Registered as: IMetricsCollector AND MetricsCollector

Service lifetimes

Lifetime	Created	Disposed
`Singleton`	Once per container	When the container is disposed
`Scoped`	Once per scope (per request in web apps)	When the scope is disposed
`Transient`	Every time it is resolved	When the scope that created them is disposed (if tracked by the container)

Choose based on how much state the service holds and how long that state should live. Stateless services can be Singleton. Services that hold per-request state should be Scoped. Very lightweight, stateless objects can be Transient.

Multiple Implementations of the Same Interface

When two services implement the same interface and neither uses Key, both are registered:

[Service(ServiceLifetime.Singleton)]
public class ConsoleLogger : ILogger { ... }

[Service(ServiceLifetime.Singleton)]
public class FileLogger : ILogger { ... }

GetRequiredService<ILogger>() returns the last registration (determined by discovery order, which depends on assembly metadata and should not be relied upon).
GetServices<ILogger>() returns all of them.

If you need deterministic resolution, use Key to give each implementation a distinct identity:

[Service(ServiceLifetime.Singleton, Key = "console")]
public class ConsoleLogger : ILogger { ... }

[Service(ServiceLifetime.Singleton, Key = "file")]
public class FileLogger : ILogger { ... }

var console = provider.GetRequiredKeyedService<ILogger>("console");
var file    = provider.GetRequiredKeyedService<ILogger>("file");

Conditional Registration: Config-Key Conditions

A service can declare a condition under which it should be registered. The most common form checks a configuration value.

[Service(ServiceLifetime.Singleton, ConfigKey = "Features:Redis")]
public class RedisCache : ICache { ... }

This service is registered only when configuration["Features:Redis"] equals "true" (evaluated as a case-insensitive string comparison). The condition is evaluated in Phase 3, after all config singletons are loaded, using the temporary provider.

A different expected value:

[Service(ServiceLifetime.Singleton, ConfigKey = "Database:Type", ConfigValue = "postgres")]
public class PostgresRepository : IRepository { ... }

This registers only when configuration["Database:Type"] == "postgres".

appsettings.json:

{
  "Features": { "Redis": "true" },
  "Database": { "Type": "postgres" }
}

The Fallback Pattern: `Negate = true`

Negate = true inverts the condition. Combine it with the same condition on a second class to create a primary/fallback pair - exactly one of which is always registered.

// Primary: registered when Redis is enabled
[Service(ServiceLifetime.Singleton, ConfigKey = "Features:Redis")]
public class RedisCache : ICache { ... }

// Fallback: registered when Redis is NOT enabled
[Service(ServiceLifetime.Singleton, ConfigKey = "Features:Redis", Negate = true)]
public class InMemoryCache : ICache { ... }

With Features:Redis = "true": only RedisCache is in the container.
With Features:Redis = "false" (or absent): only InMemoryCache is in the container.

The swap costs one config change. No startup code changes. No recompilation.

This pattern works for any number of implementations across any condition. You can also nest conditions or use the same flag for multiple service pairs.

Named Conditions: Complex Logic

Config flag checks cover common cases, but some conditions go beyond a single config value. Maybe a service should only be registered in the production environment. Maybe it requires credentials that might not be present. Maybe it checks a combination of conditions.

Named conditions are registered as predicates and referenced by name in the attribute.

services.AddKiwiServices(configuration, options =>
{
    options.AddCondition("IsProduction", sp =>
        sp.GetRequiredService<IHostEnvironment>().IsProduction());

    options.AddCondition("HasAzureCredentials", sp =>
    {
        var cfg = sp.GetRequiredService<IConfiguration>();
        return !string.IsNullOrEmpty(cfg["Azure:ConnectionString"]);
    });

    options.AddCondition("HighTrafficMode", sp =>
    {
        var appConfig = sp.GetRequiredService<AppConfig>();
        return appConfig.MaxConcurrency > 100;
    });
});

The IServiceProvider passed to each predicate is the Phase 2 temporary provider - all config singletons are already available, so you can resolve them to inspect their values.

Referencing a named condition:

[Service(ServiceLifetime.Singleton, Condition = "IsProduction")]
public class ProductionMetrics : IMetrics { ... }

[Service(ServiceLifetime.Singleton, Condition = "IsProduction", Negate = true)]
public class NoOpMetrics : IMetrics { ... }

[Service(ServiceLifetime.Singleton, Condition = "HasAzureCredentials")]
public class AzureBlobStorage : IStorageService { ... }

[Service(ServiceLifetime.Scoped, Condition = "HighTrafficMode")]
public class BulkOrderProcessor : IOrderProcessor { ... }

If both ConfigKey and Condition are set on the same [Service], Condition takes precedence. In practice, use one or the other - setting both invites ambiguity.

Keyed Services

Keyed services let multiple implementations of the same interface coexist, each retrievable by a string key.

[Service(ServiceLifetime.Scoped, Key = "primary")]
public class PrimaryDatabase : IDatabase { ... }

[Service(ServiceLifetime.Scoped, Key = "replica")]
public class ReplicaDatabase : IDatabase { ... }

Resolution:

var primary = provider.GetRequiredKeyedService<IDatabase>("primary");
var replica  = provider.GetRequiredKeyedService<IDatabase>("replica");

Keyed and conditional can be combined:

// Keyed primary/fallback - the key stays the same, the implementation swaps
[Service(ServiceLifetime.Scoped, Key = "cache", ConfigKey = "Features:Redis")]
public class RedisCache : ICache { ... }

[Service(ServiceLifetime.Scoped, Key = "cache", ConfigKey = "Features:Redis", Negate = true)]
public class InMemoryCache : ICache { ... }

Callers always resolve by "cache" key - which implementation they get depends on the config flag.

Generic Services: `[RegistersFor]`

When the same pattern applies to multiple concrete types - event handlers, message processors, pipeline stages, notification senders - writing a separate registration for each concrete instantiation is repetitive.

[RegistersFor] lets one generic class declaration produce multiple concrete closed-generic registrations. Each attribute is one registration.

[Service(ServiceLifetime.Singleton)]
[RegistersFor(typeof(OrderHandler))]
[RegistersFor(typeof(PaymentHandler), Key = "payment")]
[RegistersFor(typeof(AuditHandler), Key = "audit", ConfigKey = "Features:Audit")]
public class EventManager<THandler> where THandler : class
{
    private readonly THandler _handler;

    public EventManager(THandler handler) => _handler = handler;

    public void Handle(object @event) { /* delegate to _handler */ }
}

This single class produces:

EventManager<OrderHandler> - singleton, no key, always registered
EventManager<PaymentHandler> - singleton, keyed "payment", always registered
EventManager<AuditHandler> - singleton, keyed "audit", only if Features:Audit == "true"

Adding support for a new handler means adding one [RegistersFor] line. The startup code does not change.

Note: If a concrete type used in [RegistersFor] is itself conditionally registered, apply the same condition to the [RegistersFor] attribute. Otherwise, the generic wrapper can be registered while the dependency it wraps is absent from the container, causing a resolution failure at runtime.
// Good - condition on the generic registration matches the service it wraps
[RegistersFor(typeof(SmsHandler), Key = "sms", ConfigKey = "Features:Sms")]

Per-registration options

Each [RegistersFor] attribute can override the lifetime from [Service] and specify its own key, condition, and negate:

Property	Purpose
`concreteType`	The closed type argument (must not be a generic type definition)
`Key`	Keyed registration key
`Lifetime`	Override the parent `[Service]` lifetime for this registration
`ConfigKey`	Config-flag condition
`ConfigValue`	Expected value (default `"true"`)
`Condition`	Named condition reference
`Negate`	Invert the condition

Generic type constraints

If the class has a type parameter constraint (: class, : new(), : ISomeInterface), the concrete type provided to [RegistersFor] is validated against it. An invalid type throws InvalidOperationException at startup.

public class EventManager<THandler> where THandler : class, IEventHandler
{
    ...
}

[RegistersFor(typeof(string))]  // throws - string does not satisfy IEventHandler constraint

`[ConstructFrom]` - Scalar Values from Config

Standard constructor injection resolves entire services. Some components need raw scalar values from configuration - a port number, a connection string, a timeout - not a reference to the full config object.

Without [ConstructFrom], the only way to provide these is a factory lambda in startup code:

// Startup code - disconnected from the class that needs these values
services.AddSingleton(sp =>
{
    var cfg = sp.GetRequiredService<AppConfig>();
    return new TcpServer(cfg.Host, cfg.Port);
});

[ConstructFrom] moves the extraction rule to the class itself:

[Service(ServiceLifetime.Singleton)]
[ConstructFrom(typeof(AppConfig), nameof(AppConfig.Host), nameof(AppConfig.Port))]
public class TcpServer
{
    private readonly string _host;
    private readonly int _port;

    public TcpServer(string host, int port)
    {
        _host = host;
        _port = port;
    }
}

At resolve time, the framework:

Resolves AppConfig from the container.
Reads AppConfig.Host and AppConfig.Port in the order listed.
Calls new TcpServer(host, port).

The startup code stays untouched.

Single property from one source

[Service(ServiceLifetime.Singleton)]
[ConstructFrom(typeof(DatabaseConfig), nameof(DatabaseConfig.ConnectionString))]
public class ConnectionPool
{
    public ConnectionPool(string connectionString) { ... }
}

Multiple properties from one source

Properties are passed to the constructor in the order they are listed in the attribute:

[Service(ServiceLifetime.Singleton)]
[ConstructFrom(typeof(DatabaseConfig),
    nameof(DatabaseConfig.Host),
    nameof(DatabaseConfig.Port),
    nameof(DatabaseConfig.Name))]
public class DatabaseConnection
{
    public DatabaseConnection(string host, int port, string dbName) { ... }
}

Multiple sources

Multiple [ConstructFrom] attributes are processed in declaration order. All properties from the first attribute become the first constructor arguments, then the second, and so on:

[Service(ServiceLifetime.Scoped)]
[ConstructFrom(typeof(DatabaseConfig), nameof(DatabaseConfig.ConnectionString))]  // arg 0
[ConstructFrom(typeof(CacheConfig),    nameof(CacheConfig.RedisEndpoint))]         // arg 1
[ConstructFrom(typeof(AppConfig),      nameof(AppConfig.InstanceId))]              // arg 2
public class DataCoordinator
{
    public DataCoordinator(string connStr, string redisEndpoint, string instanceId) { ... }
}

When to use vs regular injection

Scenario	Approach
Service needs specific scalar values (port, timeout, connection string)	`[ConstructFrom]`
Service needs to call methods on the config object	Regular injection - inject the config class
Service needs both scalar config values and other services	Regular injection - let the service extract what it needs
Factory logic is too complex for property extraction	Manual `services.Add*(sp => ...)`

Constraint to know

Important: A class using [ConstructFrom] cannot also use regular DI constructor injection. All constructor arguments must come from property extraction. If a class needs both scalar config values and injected services, inject the full config object instead.

Pre-Loaded Configs

Sometimes you need configuration values before the DI container is built - to configure the logging pipeline, set up middleware, or make decisions before AddKiwiServices is called.

Load the config manually and use it immediately:

// Load before the container exists
var appConfig = configuration.LoadConfiguration<AppConfig>();

// Use the values pre-container
SetupLogging(appConfig.LogLevel);
ConfigureListenAddress(appConfig.Port);

// Pass the already-loaded instance to AddKiwiServices
// It skips auto-loading for that type and registers the provided instance as the singleton
services.AddKiwiServices(configuration, preLoadedConfigs: appConfig);

Services that inject AppConfig receive the same instance loaded before the container was built.

Multiple pre-loaded configs:

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

services.AddKiwiServices(configuration,
    preLoadedConfigs: new object[] { appConfig, dbConfig });

All other [ConfigService] types in the assembly are still auto-loaded normally. Only the pre-loaded types are skipped (since they are already registered).

Manual Registration

For selective control without a full assembly scan, use the single-type registration methods:

// Register a single config class
services.AddKiwiConfig<DatabaseConfig>(configuration);

// Register a single service
services.AddKiwiService<OrderService>();

AddKiwiConfig<T> validates [ConfigSection] and [ConfigService], calls LoadConfiguration<T>, and registers the result as a singleton.

AddKiwiService<T> validates [Service], resolves constructor dependencies recursively, and registers the service.

These are useful in tests, in tools that do not scan entire assemblies, or when integrating Kiwi DI incrementally into an existing codebase.

Using Kiwi Config and Kiwi DI Together

The two libraries are designed to work together, but each can be used independently. When used together, AddKiwiServices handles the entire coordination:

// Program.cs

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

var services = new ServiceCollection();
services.AddKiwiServices(configuration);
var provider = services.BuildServiceProvider();

Config classes annotated with both [ConfigSection] and [ConfigService] are loaded from configuration and become injectable singletons. Service classes annotated with [Service] can inject those config singletons through normal constructor injection because the config singletons are registered first (Phase 1 before Phase 3).

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

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

[Service(ServiceLifetime.Singleton)]
public class AppServer : IAppServer
{
    private readonly AppConfig _config;

    public AppServer(AppConfig config) => _config = config;

    public void Start() => Console.WriteLine($"Starting {_config.Name} on port {_config.Port}");
}

services.AddKiwiServices(configuration);
var provider = services.BuildServiceProvider();
provider.GetRequiredService<IAppServer>().Start();
// Starting MyApp on port 5000

No factory, no registration block, no startup code changes when new services are added.

Complete End-to-End Example

A realistic notification system demonstrating config loading, conditional services, the fallback pattern, generic expansion, and [ConstructFrom] - all wired together with a single AddKiwiServices call.

Configuration

appsettings.json (all configuration values are treated as strings):

{
  "notifications": {
    "smtpHost": "mail.example.com",
    "retryCount": 3
  },
  "Features": {
    "Sms": "false",
    "Audit": "true"
  }
}

Config class

[ConfigSection("notifications")]
[ConfigService]
public class NotificationConfig
{
    [ConfigKey("smtpHost", Required = true)]
    public string SmtpHost { get; private set; } = string.Empty;

    [ConfigKey("retryCount", 3)]
    public int RetryCount { get; private set; }
}

Conditional services - SMS or email based on config

public interface INotificationSender
{
    void Send(string to, string body);
}

// Active only when Features:Sms = "true"
[Service(ServiceLifetime.Scoped, ConfigKey = "Features:Sms")]
public class SmsNotificationSender : INotificationSender
{
    public void Send(string to, string body)
        => Console.WriteLine($"[SMS] {to}: {body}");
}

// Active when Features:Sms is not "true" (the fallback)
[Service(ServiceLifetime.Scoped, ConfigKey = "Features:Sms", Negate = true)]
public class EmailNotificationSender : INotificationSender
{
    private readonly string _smtpHost;

    public EmailNotificationSender(NotificationConfig config)
        => _smtpHost = config.SmtpHost;

    public void Send(string to, string body)
        => Console.WriteLine($"[Email via {_smtpHost}] {to}: {body}");
}

With Features:Sms = "false", only EmailNotificationSender enters the container.

Retry handler - scalar value from config via `[ConstructFrom]`

[Service(ServiceLifetime.Singleton)]
[ConstructFrom(typeof(NotificationConfig), nameof(NotificationConfig.RetryCount))]
public class RetryHandler
{
    private readonly int _retryCount;

    public RetryHandler(int retryCount) => _retryCount = retryCount;

    public void Execute(Action action)
    {
        for (var i = 0; i <= _retryCount; i++)
        {
            try { action(); return; }
            catch when (i < _retryCount) { }
        }
    }
}

RetryHandler receives the RetryCount = 3 value extracted directly from NotificationConfig - no reference to the full config object needed.

Generic processor - one class, two registrations

[Service(ServiceLifetime.Scoped)]
[RegistersFor(typeof(SmsNotificationSender),   Key = "sms",   ConfigKey = "Features:Sms")]
[RegistersFor(typeof(EmailNotificationSender), Key = "email", ConfigKey = "Features:Sms", Negate = true)]
public class NotificationProcessor<TSender>
    where TSender : class, INotificationSender
{
    private readonly TSender _sender;
    private readonly RetryHandler _retry;

    public NotificationProcessor(TSender sender, RetryHandler retry)
    {
        _sender = sender;
        _retry  = retry;
    }

    public void Notify(string to, string body)
        => _retry.Execute(() => _sender.Send(to, body));
}

This produces:

NotificationProcessor<SmsNotificationSender> registered under key "sms"
NotificationProcessor<EmailNotificationSender> registered under key "email"

Audit service - named condition example

services.AddKiwiServices(configuration, options =>
{
    options.AddCondition("AuditEnabled", sp =>
    {
        var cfg = sp.GetRequiredService<IConfiguration>();
        return cfg["Features:Audit"] == "true";
    });
});

[Service(ServiceLifetime.Singleton, Condition = "AuditEnabled")]
public class AuditLogger : IAuditLogger
{
    public void Log(string action) => Console.WriteLine($"[AUDIT] {action}");
}

[Service(ServiceLifetime.Singleton, Condition = "AuditEnabled", Negate = true)]
public class NoOpAuditLogger : IAuditLogger
{
    public void Log(string action) { }
}

Startup and usage

services.AddKiwiServices(configuration, options =>
{
    options.AddCondition("AuditEnabled", sp =>
        sp.GetRequiredService<IConfiguration>()["Features:Audit"] == "true");
});

var provider = services.BuildServiceProvider();

// With Features:Sms = "false" and Features:Audit = "true":
var emailProcessor = provider.GetRequiredKeyedService<NotificationProcessor<EmailNotificationSender>>("email");
emailProcessor.Notify("user@example.com", "Your order has shipped.");
// [Email via mail.example.com] user@example.com: Your order has shipped.

var audit = provider.GetRequiredService<IAuditLogger>();
audit.Log("Notification sent");
// [AUDIT] Notification sent

What AddKiwiServices did:

Loaded NotificationConfig → registered as singleton (SmtpHost = mail.example.com, RetryCount = 3).
Evaluated Features:Sms = "false" → registered EmailNotificationSender; skipped SmsNotificationSender.
Registered RetryHandler as singleton - extracted RetryCount = 3 from NotificationConfig.
Evaluated Features:Sms = "false" → registered NotificationProcessor<EmailNotificationSender> (key "email"); skipped NotificationProcessor<SmsNotificationSender> (key "sms") because its condition mirrors that of SmsNotificationSender.
Evaluated named condition AuditEnabled → registered AuditLogger; skipped NoOpAuditLogger.

To switch to SMS: set Features:Sms = "true". To disable auditing: set Features:Audit = "false". The swap is a config change. No startup edits. No recompilation.

Performance and Startup Cost

Kiwi DI shifts all discovery and wiring work to startup so runtime remains identical to standard .NET DI. All reflection and assembly scanning happens exactly once - at startup - and contributes nothing to runtime latency.

Step	When	Notes
Assembly type scanning	Startup	Proportional to assembly size; typically well under 100ms for a few hundred types (depending on environment)
Config loading (per class)	Startup	Reflection-based; negligible for typical class sizes
Temporary provider build	Startup	One extra `BuildServiceProvider()` call
Condition evaluation	Startup	One predicate call per conditional service
Service resolution at runtime	Runtime	Standard .NET DI - no Kiwi reflection involved

If assembly scanning of very large assemblies causes noticeable startup delay, pass explicit assemblies to narrow the scope:

services.AddKiwiServices(configuration, assemblies: new[]
{
    typeof(OrderService).Assembly,
    typeof(PaymentService).Assembly
});

When to Use Kiwi DI

Use it when:

Your application has a meaningful number of services and startup registration has become a maintenance concern.
You want config-driven feature flags to control service activation without touching startup code.
You use generic processor or handler patterns where one class is instantiated for many concrete types.
You value co-location: the DI role of a class is visible at the class, not buried in startup code.

Consider alternatives when:

Your application is small (roughly fewer than 20-30 services). The attribute indirection adds complexity that manual registration does not, and the savings are minimal.
You need fine-grained control over registration order or multi-step factory chains that do not map to attribute declarations.
Your team prefers fully explicit, line-by-line startup code as a policy.
You are debugging complex DI graph issues and want the simplest possible dependency graph.

Feature Summary

Goal	How
Auto-load a config class into DI	`[ConfigSection]` + `[ConfigService]` on the class
Register a service	`[Service(Lifetime)]` on the class
Also register as concrete type	`RegisterAsSelf = true`
Register only when a config flag is set	`ConfigKey = "Section:Key"`
Register only when a flag is NOT set	`ConfigKey = "..."` + `Negate = true`
Register based on complex logic	`options.AddCondition("name", sp => ...)` + `Condition = "name"`
Fallback when condition fails	`Negate = true` (same condition)
Keyed registration	`Key = "myKey"`
Resolve keyed service	`provider.GetRequiredKeyedService<T>("myKey")`
One generic class → many registrations	`[RegistersFor(typeof(T))]` (multiple attributes)
Scalar config values as constructor args	`[ConstructFrom(typeof(Config), "Prop1", "Prop2")]`
Load config before container is built	`configuration.LoadConfiguration<T>()` then `preLoadedConfigs: instance`
Register one class manually	`services.AddKiwiConfig<T>()` or `services.AddKiwiService<T>()`
Named conditions from external logic	`options.AddCondition(name, sp => bool)`

DEV Community: Ajay Jain

Introducing Kiwi Config: Simplifying Configuration Management in .NET Ecosystems

Introduction to Kiwi Config

The Problem Kiwi Config Solves

Implicit vs. Explicit Schema

Source & Repository

Installation

NuGet Package

.NET CLI

Source Code

Related Articles

The Basics: Your First Config Class

[ConfigSection] - Declaring the Root Key

[ConfigKey] - Binding a Property

Setter support

No default

Property Initializers

Type Conversions

Integers, longs, doubles, decimals

Booleans

Enums

Strings

Default Value Resolution

Required Fields

The GetDefault Convention

Nested Configuration with [ConfigObject]

How path resolution works

Nested types and DI registration

Circular reference detection

Absolute Key Paths

Collections

⚠️ Collection Format Limitation

Edge cases

Using LoadConfiguration<T> Standalone

CLI tools

Test helpers

Pre-container startup code

Logging

Error Messages

Validation Beyond Required Fields

Performance Guidance

Complete Real-World Example

Configuration Reloading

When to Use Kiwi Config vs IOptions<T>

Mental Model

Feature Summary

Introducing Kiwi DI: Simplifying Dependency Injection in .NET Ecosystems

Introduction to Kiwi DI

The Problem Kiwi DI Solves

Source & Repository

Installation

NuGet Package

.NET CLI

Related Articles

Source Code

Quick Start

Mental Model

How AddKiwiServices Works

The Attributes

[ConfigService] - Auto-Loading Configuration

What [ConfigSection] alone does not do

[Service] - Registering a Service

Interface resolution

Registering as self too

Service lifetimes

Multiple Implementations of the Same Interface

Conditional Registration: Config-Key Conditions

The Fallback Pattern: Negate = true

Named Conditions: Complex Logic

Keyed Services

Generic Services: [RegistersFor]

Per-registration options

Generic type constraints

[ConstructFrom] - Scalar Values from Config

Single property from one source

Multiple properties from one source

Multiple sources

When to use vs regular injection

Constraint to know

Pre-Loaded Configs

`[ConfigSection]` - Declaring the Root Key

`[ConfigKey]` - Binding a Property

The `GetDefault` Convention

Nested Configuration with `[ConfigObject]`

Using `LoadConfiguration<T>` Standalone

When to Use Kiwi Config vs `IOptions<T>`

How `AddKiwiServices` Works

`[ConfigService]` - Auto-Loading Configuration

What `[ConfigSection]` alone does not do

`[Service]` - Registering a Service

The Fallback Pattern: `Negate = true`

Generic Services: `[RegistersFor]`

`[ConstructFrom]` - Scalar Values from Config

Retry handler - scalar value from config via `[ConstructFrom]`