DEV Community: Ajay Jain

Terminal Output Infrastructure for .NET Applications - Kiwify.Kiwi.Presentation

Ajay Jain — Fri, 29 May 2026 18:11:11 +0000

Part of the Kiwi Foundation

Kiwify.Kiwi.Presentation is the terminal output infrastructure layer of the Kiwi Foundation - a trio of libraries (Presentation, Renderer, CLI) that together provide the core infrastructure for building professional .NET command-line and operational tooling applications: styled output, structured data display, and argument parsing.

Presentation is the foundation of the stack. Renderer uses IOutputWriter and TextStyle to colour table cells and JSON tokens. CLI uses IOutput and StyledConsole to format help text and validation errors. All three libraries share a common output pipeline with no external package dependencies.

Source and installation

GitHub: kiwifylabs/kiwi-foundation-tooling - Kiwify.Kiwi.Presentation

NuGet: Kiwify.Kiwi.Presentation

dotnet add package Kiwify.Kiwi.Presentation

Design philosophy

Presentation is organized around two abstractions that the rest of the Kiwi Foundation builds on.

IOutputWriter is the low-level writer interface: a styled Write / WriteLine / Flush contract backed by an ANSI-aware implementation, a plain-text implementation, and an in-memory implementation for testing. All rendering in Kiwi Renderer flows through IOutputWriter. OutputWriterFactory resolves the appropriate implementation at construction time based on terminal capabilities - ANSI support, output redirection - without any application-level conditionals.

IOutput is the semantic channel abstraction: WriteInfo, WriteResult, WriteError, WriteProgress. These channels carry intent, not just text. CLI uses them to separate user-facing status from structured output, enabling reliable test assertions against specific channel content and clean separation of stdout and stderr behaviour.

On top of these two abstractions, Presentation provides four independent controls - styled text, prompts, progress bars, and choice selectors - each usable in isolation. The controls are architecturally independent and can be used individually without coupling application code to the others.

The library ships as a single assembly with no NuGet dependencies beyond the BCL. It can be adopted in any .NET application without version conflicts or transitive package concerns, and it remains available as a standalone output layer outside of Kiwi Foundation contexts.

Intent

Building a terminal tool that behaves consistently across environments involves several distinct concerns: applying colour and emphasis without hardcoding ANSI escape sequences; falling back gracefully when output is redirected or the terminal lacks ANSI support; reading validated, type-safe input from the user; reporting progress on long-running operations; and presenting navigable option lists without reimplementing keyboard handling each time.

These concerns span the full lifecycle of a terminal interaction. Presentation addresses them through a shared output pipeline and four independent controls, each with a builder interface. Application code specifies intent; the library handles terminal capabilities, encoding, and fallback behaviour.

Architectural benefits

Benefit	Description
Shared output abstraction	`IOutputWriter` and `IOutput` are the integration point for the entire Kiwi stack. Renderer renders through `IOutputWriter`. CLI channels through `IOutput`. All output participates in the same pipeline and can be redirected, captured, or replaced at a single boundary.
Runtime capability detection	`OutputWriterFactory` selects between ANSI-aware and plain-text writer implementations at construction time, based on `Console.IsOutputRedirected` and Windows Console API availability. No application-level conditionals required.
Testable by design	`StringOutput` captures all semantic channels (`WriteResult`, `WriteError`, etc.) in memory. `CollectorWriter` captures `IOutputWriter` writes. No mocking of `Console` or `TextWriter` required.
Independent controls	`TextPrompt<T>`, `ConsoleProgressBar`, `ConsoleChoiceSelector`, and `StyledConsole` are independent. Use any subset without pulling in the rest.
Composable with Renderer and CLI	A writer or output instance created in Presentation can be passed directly into Renderer or CLI without adapters. The three libraries compose through shared abstractions, not shared implementation.
Zero external dependencies	Ships as a single assembly. No transitive NuGet packages. Compatible with any .NET Standard 2.1+ application.

Where it fits

Presentation is the appropriate output infrastructure for any .NET application that writes to a terminal and requires consistent, testable behaviour.

CLI and DevOps tooling - styled output, progress reporting, and interactive prompts, with test coverage through StringOutput and IOutput channel assertions.
Automated pipelines - OutputWriterFactory strips styling automatically when output is redirected; no application code changes when running in CI.
Administrative and support tools - choice selectors and prompts for interactive sessions; IOutput channels for structured result and error separation.
Long-running background tools - dual-bar progress reporting with category labels for jobs with multiple stages.
Any Kiwi Foundation tool - Presentation is the shared output pipeline for CLI and Renderer. Adopting it ensures all output - from prompts to table rendering - flows through a single consistent abstraction.

Comparison with alternatives

vs. Spectre.Console

Spectre.Console is a comprehensive .NET terminal library offering rich widgets - trees, tables with live rendering, exception displays, and advanced layout composition. It is a strong choice for applications where sophisticated terminal presentation is the primary concern.

Presentation focuses on output infrastructure and operational interaction patterns - semantic output channels, capability-aware writers, prompts, selectors, and progress reporting - rather than a comprehensive terminal widget model. It provides the output pipeline that Renderer and CLI build on: IOutputWriter, IOutput, ANSI-aware capability detection, and testable output capture. Its controls - styled text, prompts, progress bars, choice selectors - cover the common interactive patterns in tooling contexts without the weight of a full terminal widget framework. For teams building on the Kiwi Foundation stack, Presentation provides the shared output infrastructure across all three layers.

vs. Pastel

Pastel provides string-extension methods for ANSI colour wrapping. It is minimal and has essentially no learning curve.

Kiwi Presentation covers a wider surface: terminal capability detection, the IOutputWriter / IOutput abstractions, validated prompts, progress bars, and choice selectors. Where Pastel applies colour, Presentation manages the full output pipeline.

vs. ConsoleTables / ConsoleMenu

These libraries each solve one problem - ASCII tables and menu navigation. Kiwi Presentation covers interactive selection through ConsoleChoiceSelector and integrates with the Kiwi Renderer table engine through the shared IOutputWriter abstraction.

vs. McMaster.Extensions.CommandLineUtils

That library bundles output alongside argument parsing. Kiwi Presentation is independent of the CLI layer and can be used in any context that writes to a terminal - long-running services, test harnesses, batch jobs - without coupling to argument parsing concerns.

How it is used - detailed walkthrough

Styled output

All markup parsing happens at call time; there is no compile step or pre-processing:

StyledConsole.WriteLine("[bold cyan]Build started[/]");
StyledConsole.WriteLine("[green]  ✓ Compiled[/]   [grey]0 warnings, 0 errors[/]");
StyledConsole.WriteLine("[red]  ✗ Tests failed[/] [yellow]3 of 47[/]");
StyledConsole.WriteLine("[white on darkblue] PUBLISHED [/] v2.3.1");
StyledConsole.WriteLine("[#ff8800]Hex colour[/]   [rgb(100,200,50)]RGB colour[/]");

Tags nest. Inner tags override the colour of the outer tag but inherit modifiers (bold, underline):

StyledConsole.WriteLine("[bold yellow]WARNING[/] [bold grey](check logs)[/]");

Use StyledConsole.StripMarkup(markup) to measure display width before padding, since markup characters have no visual width.

Writing through IOutputWriter

StyledConsole writes to Console.Out by default. Inject a writer to redirect output:

IOutputWriter writer = OutputWriterFactory.CreateConsoleWriter();
StyledConsole.WriteLine(writer, "[bold red]Critical:[/] out of disk space");

OutputWriterFactory.CreatePlainWriter(TextWriter) strips all styling - useful for log files, CI pipelines, and test assertions on raw text.

IOutput semantic channels

IOutput provides named channels with different semantics:

IOutput output = new ConsoleOutput(verbose: !args.Contains("--quiet"));

output.WriteInfo("Scanning…");          // Suppressed when verbose=false
output.WriteResult("42 issues found");  // Always shown; goes to stdout
output.WriteError("Permission denied"); // Always shown; goes to stderr
output.WriteProgress(".");

FileOutput writes to a file. StringOutput captures in memory for tests:

var out = new StringOutput();
MyCommand.Execute(out);
Assert.Contains("42 issues found", out.GetResults());

Prompts

TextPrompt<T> converts and validates in one step:

string name = new TextPrompt<string>()
    .WithPromptText("Your name")
    .Required("Name is required.")
    .Show();

int port = new TextPrompt<int>()
    .WithPromptText("Port")
    .WithRange(1024, 65535)
    .WithDefaultValue(8080)
    .Show();

Uri endpoint = new TextPrompt<Uri>()
    .WithPromptText("API endpoint")
    .WithConverter(raw => new Uri(raw))
    .WithConversionErrorMessage("Must be a valid URL")
    .Show();

Multiple validators chain in order; the first failure short-circuits:

string cs = new TextPrompt<string>()
    .WithPromptText("Connection string")
    .Required()
    .WithRegex(@"^Server=", "Must start with 'Server='")
    .WithValidation(s => s.Contains("Database="), "Must include 'Database='")
    .Show();

Progress bars

// Single bar
using var bar = new ConsoleProgressBar(ProgressBarStyle.Solid);
for (int i = 0; i <= 100; i++)
{
    bar.Report(i / 100.0);
    await Task.Delay(20);
}
bar.Complete();

// Dual bar: overall + current category
using var bar = new MultiConsoleProgressBar("Deploying", labelWidth: 20);
bar.NextCategory("Building",     overallValue: 0.0);
bar.ReportCategory(1.0);
bar.NextCategory("Uploading",    overallValue: 0.4);
for (double p = 0; p <= 1.0; p += 0.05) { bar.ReportCategory(p); }
bar.NextCategory("Verifying",    overallValue: 0.9);
bar.ReportCategory(1.0);
bar.Complete();

Choice selectors

string region = new ConsoleChoiceSelector()
    .WithCaption("Select region:")
    .AddOption("US East",  "us-east-1")
    .AddOption("EU West",  "eu-west-1")
    .AddOption("AP South", "ap-south-1")
    .Show();

IReadOnlyList<string> features = new ConsoleMultiChoiceSelector()
    .WithCaption("Enable features:")
    .AddOption("Audit logging",   "audit")
    .AddOption("Two-factor auth", "2fa")
    .AddOption("Rate limiting",   "rate")
    .Show();

Sample screens

Styled console output

Build started
  ✓ Compiled   0 warnings, 0 errors
  ✗ Tests failed  3 of 47
 PUBLISHED  v2.3.1

Build started is bold cyan. The success line is green with the suffix in grey. The failure line is red with the count in yellow. PUBLISHED is white text on a dark blue background.

TextPrompt - interactive session

Your name: Alice Chen

Port [1024-65535, default: 8080]: 99
  ✗ Value must be between 1024 and 65535.

Port [1024-65535, default: 8080]: 3000

Connection string: Server=db;Database=
  ✗ Must include 'Database='.

Connection string: Server=db;Database=orders;

Prompts re-display after each validation failure. The first failing validator short-circuits; subsequent rules run only once earlier ones pass.

ConsoleChoiceSelector - single select

Select region:
  ❯ US East
    EU West
    AP South

Arrow keys move the cursor. Enter confirms. The returned value is the bound string passed to AddOption, not the display label - so selecting US East returns "us-east-1".

ConsoleMultiChoiceSelector - multi-select

Enable features:
  [✓] Audit logging
  [ ] Two-factor auth
  [✓] Rate limiting

  Space to toggle · Enter to confirm

Returns the bound values of all checked items as IReadOnlyList<string>.

Progress bars

Single bar:

  [████████████████████████████████████░░░░]  90%

Dual bar with phase labels (MultiConsoleProgressBar):

Deploying
  Building   [████████████████████████████████████████] 100%
  Uploading  [████████████████████████░░░░░░░░░░░░░░░░]  60%

The overall bar advances with each NextCategory call; the category bar resets and tracks the current phase independently.

Thread safety notes

StyledConsole is stateless - the markup parser creates new state per call. Multiple threads can call Write / WriteLine concurrently, but interleaved writes will produce interleaved output. Lock the writer if concurrent rendering to the same sink is required.

Progress bars and prompts are single-threaded controls: construct from one thread, report from one thread.

Structured Rendering for .NET CLI and Automation Tools - Kiwify.Kiwi.Renderer

Ajay Jain — Fri, 29 May 2026 18:10:47 +0000

Part of the Kiwi Foundation

Kiwify.Kiwi.Renderer is the data-display layer of the Kiwi Foundation - a trio of libraries (Presentation, Renderer, CLI) that together cover the full surface of building a professional .NET command-line tool.

Renderer sits above Presentation: it writes through IOutputWriter and uses TextStyle / OutputTheme from that library. CLI tools use Renderer to display query results, configuration dumps, and structured status output. The dependency flows one way: Renderer → Presentation. The CLI layer depends on both.

Source and installation

GitHub: kiwifylabs/kiwi-foundation-tooling - Kiwify.Kiwi.Renderer

NuGet: Kiwify.Kiwi.Renderer

dotnet add package Kiwify.Kiwi.Renderer

Design philosophy

Renderer is built around a three-layer separation: data shaping, rendering, and output transport. These layers compose independently.

Data shaping is handled by the JSON parsing pipeline or the low-level grid API. The rendering layer - TextGridRenderer, HtmlGridRenderer, RtfGridRenderer, and their object-table counterparts - operates on DataGrid, a format-agnostic column and row model, with no dependency on how that model was populated. Output transport is handled entirely by IOutputWriter from Kiwi Presentation, which decouples the rendering layer from the output destination.

This means the same rendering pipeline can target an ANSI-capable terminal, a redirected console stream (where styling is stripped automatically), an HTML file, an RTF document, or any custom sink that implements IOutputWriter. Format selection is a runtime parameter, not an architectural decision.

The practical implication is that applications can evolve from simple terminal-only tools into multi-format reporting pipelines without restructuring display infrastructure. The rendering configuration stays the same; only the format constant and the output writer change.

Kiwi Presentation and Kiwi Renderer compose through shared abstractions - IOutputWriter, TextStyle, OutputTheme - rather than through shared implementation. Renderer adds structured-data rendering capabilities while preserving the same output pipeline model that Presentation uses for prompts, progress bars, and styled console output. The libraries are intentionally modular: each can be used independently, and they integrate seamlessly when used together.

Intent

Displaying structured data in a terminal involves more mechanics than it first appears. Column widths must accommodate the widest value in any row, not just the header. Alignment and padding must be applied consistently across rows. The same dataset may need to appear in different forms across different contexts - a terminal table during an operator session, an HTML export for an archived report, an RTF document for a stakeholder summary - without duplicating formatting logic. A single JSON object and a JSON array of objects require fundamentally different layouts: key/value vs. multi-column.

Beyond format concerns, the source data is often already in JSON form: API responses, serialized configuration, pipeline outputs, ORM projections. Introducing a deserialization step and an intermediate view model adds friction without adding value when the goal is presentation, not processing.

Renderer addresses these concerns through a unified rendering pipeline. At the highest abstraction level, it accepts a JSON string and produces formatted output in the requested format. At the lowest level, it provides a DataGrid API that accepts programmatic rows without any JSON at all. The boundary between the two is well-defined and explicit - JSON is treated as an input and transport format, not as the rendering model itself.

Architectural benefits

Benefit	Description
JSON-first, not JSON-only	The high-level pipeline accepts `string`, `byte[]`, or `JsonDocument`. The low-level grid API operates without JSON, enabling programmatic construction and non-JSON data sources. JSON is the input format; the rendering model is `DataGrid`.
Multi-target rendering	The same rendering configuration produces text, HTML, and RTF output. Switching format is a single string constant. Custom formats can be registered at runtime via `GridRendererFactory` without modifying the library.
Output abstraction	All rendering flows through `IOutputWriter` from Kiwi Presentation. The output destination - terminal, file, stream, in-memory buffer - is external to the rendering logic and can be substituted freely.
Theme isolation	`OutputTheme` is never mutated by renderers. Theme objects can be shared across concurrent render calls without defensive copying.
Extensible format registry	`GridRendererFactory` and `ObjectTableRendererFactory` back their registrations with `ConcurrentDictionary`. Registration is thread-safe and can be called from module initializers.
Interactive paging	`PagedDataGrid<T>` layers keyboard navigation onto any grid without altering the data model or rendering configuration. Falls through silently when stdin is redirected.
Modular composition	Renderer and Presentation are independently deployable and share abstractions, not implementation. Applications that already use Presentation can add Renderer without restructuring their output infrastructure.

Where it fits

Renderer is applicable across a range of tooling and automation scenarios that extend well beyond interactive terminal display.

CLI and DevOps tooling - display query results, deployment history, configuration state, and pipeline summaries in the terminal; export the same data as HTML or RTF without a separate rendering path.
Operational reporting - produce structured reports from the same dataset that drives terminal display, with no divergence in data preparation logic.
CI/CD diagnostics - render test summaries, coverage reports, and dependency audits to terminal and file simultaneously from the same renderer instance.
Automated exports - scheduled jobs that produce HTML or RTF reports alongside terminal logging, using shared rendering configuration.
Support and administrative tooling - render infrastructure state, resource inventory, and audit log entries in both terminal and document formats.
API explorers and REST clients - display JSON responses as readable tables without a schema, view model, or deserialization step.
AI-generated output review - render structured JSON produced by language model pipelines as formatted terminal tables for operator inspection.

The rendering pipeline is designed to support all of these without requiring format-specific code paths in the application layer.

Comparison with alternatives

vs. ConsoleTables

ConsoleTables provides a clean ASCII table from typed objects. It is well-suited for straightforward terminal display where JSON input, multi-format output, and column schema control are not requirements.

Kiwi Renderer covers a wider surface: JSON input without deserialization, multi-format rendering across text/HTML/RTF, predefined column schemas, key/value layout for single objects, JSON syntax highlighting, interactive paging, and the IOutputWriter output abstraction pipeline.

vs. Spectre.Console

Spectre.Console is a comprehensive terminal rendering framework. It excels at rich interactive console layouts - widgets, live updates, trees, panels, and advanced visual composition. For applications where sophisticated terminal presentation is the primary concern, it is a strong and well-maintained choice.

Kiwi Renderer is optimized for a different set of concerns: structured-data rendering with portability across terminal, HTML, and RTF targets; JSON-first input without intermediate models; and integration with the Kiwi Presentation output pipeline. The two libraries share some surface area - both can render tables - but they address different primary problems and operate at different abstraction levels.

If your application needs live terminal widgets, cursor-positioned updates, or rich interactive console layouts, Spectre.Console is the appropriate tool. If your focus is rendering structured data consistently across output formats within a shared output pipeline - particularly in automation, reporting, and tooling contexts - Kiwi Renderer provides a purpose-built model for that problem.

vs. CsvHelper

CsvHelper handles CSV serialization and deserialization. It has no terminal rendering capability. The two libraries are complementary: CsvHelper for structured file I/O, Kiwi Renderer for formatted display.

vs. Dapper / EF Core

Neither Dapper nor EF Core provides result display. Renderer integrates naturally with database-backed CLI tools: query results can be projected to JSON or passed through the low-level grid API and displayed as formatted tables without an intermediate view layer.

How it is used - detailed walkthrough

JSON array → terminal table

The simplest path - pass a JSON string, chain the builder, call AsTable():

var json = """
[
  { "Id": 1, "Name": "Alice", "Role": "Engineer", "Salary": 95000 },
  { "Id": 2, "Name": "Bob",   "Role": "Designer",  "Salary": 72000 }
]
""";

RenderEngine.Create(json)
    .WithTitle("Team Directory")
    .WithLeftMargin(2)
    .Build()
    .AsTable();

Output:

  Team Directory
  ┌────┬───────┬──────────┬────────┐
  │ Id │ Name  │ Role     │ Salary │
  ├────┼───────┼──────────┼────────┤
  │  1 │ Alice │ Engineer │  95000 │
  │  2 │ Bob   │ Designer │  72000 │
  └────┴───────┴──────────┴────────┘

Columns are auto-discovered from the first row. Integer values are right-aligned automatically.

Applying a theme

var theme = new OutputTheme
{
    Header = new TextStyle(ConsoleColor.DarkCyan) { Bold = true },
    Border = new TextStyle(ConsoleColor.DarkGray),
    Cell   = new TextStyle(ConsoleColor.White)
};

RenderEngine.Create(json)
    .WithTitle("Team Directory")
    .WithTheme(theme)
    .WithLeftMargin(2)
    .Build()
    .AsTable();

OutputTheme is also used for Warning (no-data messages) and Error (render failures). The same theme object can be reused across multiple RenderEngine.Create() calls - renderers never write back to the theme.

PredefinedColumn - subset, rename, align

var columns = new List<PredefinedColumn>
{
    new PredefinedColumn { FieldName = "Name",   Title = "Employee", Width = 14 },
    new PredefinedColumn { FieldName = "Role",   Title = "Dept",     Width = 12 },
    new PredefinedColumn { FieldName = "Salary", Title = "Salary $", Width = 10, RightAlign = true }
};

RenderEngine.Create(json)
    .WithTitle("Salary Report")
    .WithTheme(theme)
    .WithPredefinedColumns(columns)
    .Build()
    .AsTable();

FieldName is the JSON property name (case-insensitive). Title is the column header. Width is the minimum width; the column grows if a value is wider.

Single object → key/value table

When the JSON root is an object, AsTable() renders a two-column key/value layout:

var profile = """
{ "Id": 1, "Name": "Alice", "Role": "Engineer", "Location": "London" }
""";

RenderEngine.Create(profile)
    .WithTitle("Employee Profile")
    .WithTheme(theme)
    .Build()
    .AsTable();

  Employee Profile
  ┌──────────┬───────────┐
  │ Id       │ 1         │
  ├──────────┼───────────┤
  │ Name     │ Alice     │
  ├──────────┼───────────┤
  │ Role     │ Engineer  │
  ├──────────┼───────────┤
  │ Location │ London    │
  └──────────┴───────────┘

JSON syntax highlighting

RenderEngine.Create(profile)
    .WithLeftMargin(2)
    .WithJsonTheme(JsonTheme.DefaultTheme)
    .Build()
    .AsFormattedJson();

DefaultTheme uses a VS Code-inspired palette. Every token type has its own TextStyle:

Token	DefaultTheme colour
Key	Cyan
StringValue	Green
NumberValue	Yellow
BooleanValue	DarkCyan
NullValue	DarkGray
Punctuation	DarkGray

Custom theme:

var jsonTheme = new JsonTheme
{
    Key         = new TextStyle(ConsoleColor.White) { Bold = true },
    StringValue = new TextStyle(ConsoleColor.Green),
    NullValue   = new TextStyle(ConsoleColor.DarkRed)
};

HTML output

using var writer = new StreamWriter("report.html", append: false, Encoding.UTF8);

RenderEngine.Create(json)
    .WithTitle("Sales Report")
    .WithWriter(writer)
    .Build()
    .AsTable(OutputFormat.Html);

With Bootstrap CSS classes

HtmlGridStyleDescriptor attaches CSS framework class names to table elements alongside the renderer's generated CSS classes:

var htmlTheme = new OutputTheme
{
    HtmlGridStyle = new HtmlGridStyleDescriptor
    {
        TableClasses  = { "table", "table-bordered", "table-striped" },
        HeaderClasses = { "table-dark" },
        RowClasses    = { "table-row" },
        CellClasses   = { "text-nowrap" }
    }
};

The renderer always emits a <style> block with generated CSS classes for the theme's colours. HtmlGridStyle class names are appended to element class attributes alongside the generated ones - both sources of styling are active simultaneously.

RTF output

RenderEngine.Create(json)
    .WithFileName("report.rtf")
    .WithTheme(rtfTheme)
    .Build()
    .AsTable(OutputFormat.Rtf);

The RTF renderer uses a pre-built colour table derived from the theme's TextStyle values. The resulting .rtf file opens correctly in Microsoft Word and LibreOffice.

Auto-formatted column names

When JSON field names follow camelCase or PascalCase conventions, WithProperCasedTitles() converts them to readable column headers via StringExtensions.ToSpacedWords - no WithPredefinedColumns() required:

// orderId → "Order Id",  customerName → "Customer Name",  totalAmount → "Total Amount"
RenderEngine.Create(json)
    .WithProperCasedTitles()
    .Build()
    .AsTable();

Works for both array (multi-column) and single-object (key/value) rendering. Has no effect when WithPredefinedColumns() is used - predefined Title values take precedence.

Fragment mode

WithWrappingTags(false) suppresses document-level wrappers so the output can be embedded in an existing page or document:

// HTML: emits <style> + <table>, no <!DOCTYPE>/html/head/body wrappers
// RTF:  emits table rows only, no {\rtf1…} header or colour table
RenderEngine.Create(json)
    .WithTheme(theme)
    .WithWriter(writer)
    .WithWrappingTags(false)
    .Build()
    .AsTable(OutputFormat.Html);   // or OutputFormat.Rtf

HTML fragments always include the <style> block so generated CSS classes resolve correctly when injected into a parent page. RTF fragments omit the colour table; the receiving document must declare compatible colour entries at matching indices.

Low-level grid API

Use the grid API directly for non-JSON data or when rows need to be constructed programmatically:

var grid = new DataGrid { LeftMargin = 2 };
grid.AddColumn(new Column("ID",    6,  rightAlign: true));
grid.AddColumn(new Column("Name", 24));
grid.AddColumn(new Column("Cost", 10, rightAlign: true));

var renderer = new TextGridRenderer(grid, theme: theme);
renderer.RenderTitle("Inventory");
renderer.RenderHeader();
renderer.RenderRow("001", "Widget Pro",  "$49.99");
renderer.RenderRow("002", "Gadget Lite", "$39.99");
renderer.RenderFooter();

DataGrid.UpdateColumnWidth(caption, candidateWidth) dynamically grows a column as rows are added.

Interactive paging

var pagedGrid = new PagedDataGrid<Product>(
    grid:     grid,
    rows:     products,       // IReadOnlyList<Product>
    pageSize: 20,
    toValues: p => new[] { p.Id.ToString(), p.Name, p.Price.ToString("F2") },
    theme:    theme);

pagedGrid.Render();

The user navigates with n (next), p (previous), q (quit). When stdin is redirected, the grid renders all rows and exits without prompting.

Sample screens

Auto-formatted column names (`WithProperCasedTitles`)

camelCase and PascalCase JSON field names are converted to readable column headers automatically:

JSON field	Column header
`orderId`	`Order Id`
`customerName`	`Customer Name`
`orderTotal`	`Order Total`
`fulfillmentStatus`	`Fulfillment Status`

  ┌──────────┬───────────────┬─────────────┬────────────────────┐
  │ Order Id │ Customer Name │ Order Total │ Fulfillment Status │
  ├──────────┼───────────────┼─────────────┼────────────────────┤
  │     1001 │ Alice Chen    │      249.99 │ Shipped            │
  │     1002 │ Bob Müller    │       89.50 │ Pending            │
  │     1003 │ Carol Smith   │      412.00 │ Delivered          │
  └──────────┴───────────────┴─────────────┴────────────────────┘

PredefinedColumn - subset, renamed, and aligned

Three columns selected and renamed from a wider dataset, with Salary $ right-aligned:

  Salary Report
  ┌──────────────┬──────────────┬──────────┐
  │ Employee     │ Dept         │ Salary $ │
  ├──────────────┼──────────────┼──────────┤
  │ Alice Chen   │ Engineering  │    95000 │
  │ Bob Müller   │ Design       │    72000 │
  │ Carol Smith  │ Engineering  │   108000 │
  └──────────────┴──────────────┴──────────┘

JSON syntax highlighting (`AsFormattedJson`)

Token colours with DefaultTheme (VS Code-inspired palette):

{
  "id": 1,
  "name": "Alice Chen",
  "role": "Engineer",
  "active": true,
  "salary": null
}

Token	Colour
Keys (`"id"`, `"name"`, ...)	Cyan
String values	Green
Number values	Yellow
`true` / `false`	Dark cyan
`null`	Dark grey
Braces, colons, commas	Dark grey

Interactive paging (`PagedDataGrid`)

  Inventory (showing 1-20 of 74)
  ┌─────┬──────────────────────────┬──────────┐
  │  ID │ Name                     │     Cost │
  ├─────┼──────────────────────────┼──────────┤
  │ 001 │ Widget Pro               │   $49.99 │
  │ 002 │ Gadget Lite              │   $39.99 │
  │ 003 │ Sensor Module X          │  $124.00 │
  │ 004 │ Relay Board v2           │   $18.50 │
  │ ... │ ...                      │      ... │
  └─────┴──────────────────────────┴──────────┘

  n - next page   p - previous page   q - quit

When stdin is redirected (CI, piped output), all rows render without the navigation prompt.

HTML output

The renderer emits a <style> block with generated short-form CSS class names. Bootstrap or Tailwind class names supplied via HtmlGridStyleDescriptor are appended to the same elements alongside the generated ones:

<style>
  .k4f7a2 { color: #008b8b; font-weight: bold; }
  .k9e3b1 { color: #f8f8f2; }
</style>
<h2>Team Directory</h2>
<table>
  <tr>
    <th class="k4f7a2">Id</th>
    <th class="k4f7a2">Name</th>
    <th class="k4f7a2">Role</th>
    <th class="k4f7a2">Salary</th>
  </tr>
  <tr>
    <td class="k9e3b1">1</td>
    <td class="k9e3b1">Alice</td>
    <td class="k9e3b1">Engineer</td>
    <td class="k9e3b1" style="text-align:right">95000</td>
  </tr>
</table>

In fragment mode (WithWrappingTags(false)), the <!DOCTYPE>, <html>, <head>, and <body> wrappers are omitted; the <style> block and <table> element are emitted as-is for injection into an existing page.

Architectural notes

Theme immutability. Renderers store a snapshot of HtmlGridStyleDescriptor in a private field at construction time. They never write back to OutputTheme. Multiple threads can share a theme object.
Format registration. GridRendererFactory and ObjectTableRendererFactory use ConcurrentDictionary. Register() is safe from any thread including module initializers.
TextStyle value equality. TextStyle implements IEquatable<TextStyle> with value-based equality. The HTML renderer uses this to deduplicate CSS class assignments - two properties with identical styles produce one CSS class, not two.
RTF colour safety. RtfHelper.ApplyTextStyle uses TryGetValue - colours not registered in the document's colour table are silently skipped rather than throwing.

Argument Parsing and Command Routing for .NET CLI Tools - Kiwify.Kiwi.CLI

Ajay Jain — Fri, 29 May 2026 18:10:08 +0000

Part of the Kiwi Foundation

Kiwify.Kiwi.CLI is the argument-parsing and command-routing layer of the Kiwi Foundation - a trio of libraries (Presentation, Renderer, CLI) that together provide composable infrastructure for building .NET command-line and operational tooling applications.

CLI sits above Presentation: it uses IOutput and StyledConsole to format help text and validation errors. The dependency flows one way: CLI → Presentation. Renderer composes alongside CLI when applications need structured-data rendering, reporting, or multi-format output.

Source and installation

GitHub:

Package	Source
`Kiwify.Kiwi.CLI`	Kiwify.Kiwi.CLI
`Kiwify.Kiwi.CLI.Declarative`	Kiwify.Kiwi.CLI.Declarative
`Kiwify.Kiwi.CLI.Configuration`	Kiwify.Kiwi.CLI.Configuration
`Kiwify.Kiwi.CLI.DependencyInjection`	Kiwify.Kiwi.CLI.DependencyInjection

NuGet:

dotnet add package Kiwify.Kiwi.CLI
dotnet add package Kiwify.Kiwi.CLI.Declarative           # attribute-based command definition
dotnet add package Kiwify.Kiwi.CLI.Configuration         # IConfiguration bridge
dotnet add package Kiwify.Kiwi.CLI.DependencyInjection   # DI command resolver

Design philosophy

CLI is built around the principle that command objects should be ordinary C# classes - no required base types, no framework interfaces at the call site. The library binds parsed argument values to properties through Expression<Func<TCommand, object?>> selectors compiled at registration time, so member resolution occurs during registration rather than repeatedly during parsing.

Two configuration paths - fluent (programmatic) and declarative (attribute-based) - both produce the same Command<T> internally. The choice between them is a project convention decision, not an architectural one. Teams can mix styles across commands in the same application.

Parsing, validation, and command execution are intentionally separated into distinct stages. A command can be parsed and validated without invoking its handler, making it straightforward to inspect parsed state, run pre-execution checks, and test validation behaviour in isolation. This separation also supports dry-run scenarios and custom hosting arrangements where the application controls when - and whether - the handler is invoked.

All user-facing output - help text, validation errors, command results - flows through IOutput from Kiwi Presentation. CLI output participates in the same pipeline used by Presentation controls: consistent, testable, and redirectable without special handling. StringOutput captures all output in unit tests without mocking Console.

Validation is a first-class concern rather than middleware. Cross-property constraints - conditional requirements, all-or-none groups, exactly-one-of groups - are expressed as typed rule builders that operate on the command object directly, not on raw argument strings.

Command activation is separated from argument parsing and validation. Commands may be instantiated directly or resolved through dependency injection, allowing CLI applications to integrate naturally with broader application infrastructure while keeping command models framework-light. Kiwi CLI integrates with standard .NET dependency injection patterns and the Kiwi declarative registration extensions built on top of Microsoft.Extensions.DependencyInjection.

Intent

Argument parsing involves more than matching flags to properties. Options need multiple aliases, type conversion, and constraint checking - including cross-property constraints that cannot be expressed per-option. Different commands share an application host but need independent option sets. Help text must be generated, formatted, and wrapped consistently. Large codebases benefit from convention-based registration to reduce per-command ceremony. In operational tooling, parsed values often need to flow into IConfiguration to participate in the broader application configuration graph alongside JSON files and environment variables.

CLI addresses these concerns by separating argument parsing, command routing, and output into distinct, independently testable layers. Command objects remain framework-free; the library acts as a wiring layer that connects raw string[] arguments to typed, validated command state and then invokes a handler.

Architectural benefits

Benefit	Description
Plain command objects	Command types are ordinary C# classes. No framework base types or marker interfaces required. Properties are bound via `Expression<Func<TCommand, object?>>` - member resolution happens at registration, making the parse-time path straightforward.
Two configuration paths	Fluent (programmatic) and declarative (attribute-based) both produce the same `Command<T>`. Switch between them per-command or per-project without any architectural difference.
First-class validation	Four built-in rule builders (custom, conditional required, group-or-none, exactly-one-group) cover cross-property constraints without middleware. Option-level constraints are checked before cross-property rules, producing clear, ordered error messages.
Complex type support	Collections, dictionaries, and nested objects from inline `key=value` pairs or loader syntax (`json::`, `text::`, `env::`) - without requiring custom converters for typical configuration-style data structures.
IConfiguration integration	CLI arguments participate in the standard .NET `IConfiguration` layering model. Parsed values can be pushed into `IConfigurationBuilder` and overlay JSON, environment, and other configuration sources using the standard priority chain. Only explicitly set properties are contributed, preserving configuration semantics.
IOutput integration	All output - help, errors, results - flows through `IOutput` from Kiwi Presentation. Swap in `StringOutput` for unit tests without any other changes.
Infrastructure-friendly composition	Commands may be instantiated directly or resolved through standard .NET dependency injection, allowing CLI tools to integrate cleanly with logging, configuration, and application services without imposing framework coupling on command models.
Zero external dependencies	Core package has no NuGet dependencies beyond the BCL and `Microsoft.Extensions.Configuration.Abstractions`. DI support is opt-in via a separate package.

Where it fits

CLI is designed for .NET applications where argument parsing, command routing, and output behaviour need to be independently testable and precisely controlled.

Single-command tools - parse a flat set of options and invoke a handler, with typed validation and help generation included.
Multi-command applications - route verb [options] invocations to independent command objects, each with its own option set and validation rules.
DevOps and automation tooling - CLI arguments layer naturally on top of environment-specific JSON config through IConfiguration integration, without custom merging logic.
Plugin architectures - declarative mode supports scanning external assemblies for [CliCommand]-decorated types at runtime.
Hosted and operational tooling - command handlers can participate in broader application composition, including logging, configuration, and dependency injection infrastructure, while the command model itself remains a plain C# class.
Testable CLI applications - StringOutput and direct Command<T>.Parse() / .Execute() make it straightforward to unit-test option parsing and validation without spinning up a full application host.

Comparison with alternatives

vs. System.CommandLine

System.CommandLine is the official Microsoft library. It is feature-rich and actively maintained, with a middleware pipeline and DragonFruit binder.

Kiwi CLI takes a different approach in several areas: expression-based property binding rather than Option<T> objects threaded through handler lambdas; cross-property validation as typed rule builders rather than middleware; native IOutput / IOutputWriter integration with the Kiwi Foundation; and no external NuGet dependencies in the core package.

vs. CommandLineParser (CommandLine)

CommandLineParser uses attribute decoration and a global Parser.Default.ParseArguments<T>() entry point. Kiwi CLI is similar in philosophy but adds a parallel fluent configuration path, first-class cross-property validation rule builders, ComplexPropertyParser for nested objects and loader syntax, IConfiguration integration, and IOutput / Presentation integration.

vs. CliFx

CliFx is a clean, attribute-first library with DI support and async-first handlers. Where it focuses on command composition and async execution, Kiwi CLI focuses on typed validation rules, two-mode configuration, and IConfiguration layering. Command handlers in Kiwi CLI may be synchronous or asynchronous depending on application requirements; the parsing and validation pipeline is independent of the execution model. CliFx has no equivalent of the cross-property validation rule builders.

vs. Cocona

Cocona maps methods directly to commands using naming conventions and DI. It is well-suited for microservice-style CLIs where each command is a method. Kiwi CLI is a stronger fit when explicit control over command objects, validation rules, and IConfiguration integration are requirements.

How it is used - detailed walkthrough

Fluent registration

Define a plain command object:

public class DeployOptions
{
    public string Environment { get; set; } = string.Empty;
    public string Version     { get; set; } = string.Empty;
    public bool   DryRun      { get; set; }
    public int    Timeout     { get; set; } = 60;
}

var deployCommand = new Command<DeployOptions>("deploy", (opts, output) =>
{
    if (opts.DryRun)
        output.WriteInfo("[DRY RUN] No changes applied.");
    output.WriteResult($"Deployed {opts.Version} to {opts.Environment}.");
})
.AddOption(
    new GenericOption("--env", "-e")
        .SetHelpText("Target environment")
        .FieldRequired()
        .SetValidValues("dev", "staging", "prod"),
    c => c.Environment)
.AddOption(
    new GenericOption("--version", "-v")
        .SetHelpText("Version tag")
        .FieldRequired(),
    c => c.Version)
.AddOption(
    new BooleanOption("--dry-run")
        .SetHelpText("Print plan without applying"),
    c => c.DryRun)
.AddOption(
    new GenericOption("--timeout", "-t")
        .SetDefaultValue("60"),
    c => c.Timeout);

Wire up the application:

var app = new CommandLineApplication("myapp", "1.0.0", "Deployment tool");
app.AddCommand(deployCommand);
app.Execute(args);

Cross-property validation

Validation rules chain directly onto the command:

using Kiwify.Kiwi.CLI.Validation.Extensions;

deployCommand
    .CreateRequiredWhen<DeployOptions>()
        .AddCondition(opts => opts.Environment == "prod")
        .AddField(opts => opts.Version)
        .SetErrorMessage("--version is required in prod")
        .AttachRule()
    .CreateRequiredWholeFieldGroupOrNone<DeployOptions>()
        .AddField(opts => opts.CertPath)
        .AddField(opts => opts.CertPassword)
        .SetErrorMessage("Provide both --cert-path and --cert-password, or neither")
        .AttachRule()
    .CreateRequiredOnlyOneFieldGroupValidationRule<DeployOptions>()
        .AddGroup(g => g.AddField(opts => opts.SourceFile))
        .AddGroup(g => g.AddField(opts => opts.SourceUrl))
        .AttachRule();

When validation fails, the error is printed via IOutput.WriteError and Execute returns without calling the handler.

Enum options

EnumOption<TEnum> derives valid values from the enum automatically:

public enum LogLevel { Trace, Debug, Info, Warning, Error }

command.AddOption(
    new EnumOption<LogLevel>("--log-level", "-l")
        .SetHelpText("Minimum log level")
        .SetDefaultValue("Info"),
    c => c.LogLevel);

Parsing is case-insensitive. Invalid values produce a descriptive error listing the allowed names.

Complex types and loader syntax

public class ImportOptions
{
    public Dictionary<string, string> Mapping  { get; set; } = new();
    public string[]                   Tags     { get; set; } = Array.Empty<string>();
    public ConnectionConfig           Db       { get; set; } = new();
}

Command line:

myapp import --mapping key1=val1,key2=val2 --tags alpha,beta,gamma --db json::./db.json

--mapping populates a Dictionary<string, string> from inline key=value pairs.
--tags populates string[] from a comma-separated list.
--db json::./db.json deserializes ./db.json into ConnectionConfig.

Declarative mode

Decorate the command class:

[CliCommand("deploy", Description = "Deploy the application")]
[RequiredWhen("Environment", "prod",
    RequiredFields = new[] { "Version" },
    ErrorMessage   = "--version is required in prod")]
[RequiredWholeFieldGroupOrNone("CertPath", "CertPassword")]
[CustomValidation(nameof(ValidateTimeout),
    ErrorMessage = "--timeout must be between 10 and 300")]
public class DeployOptions
{
    [CliOption("--env", "-e", IsRequired = true)]
    public string Environment { get; set; } = string.Empty;

    [CliOption("--version", "-v")]
    public string Version { get; set; } = string.Empty;

    [CliOption("--timeout", "-t", DefaultValue = 60)]
    public int Timeout { get; set; }

    [CliOption("--cert-path")]
    public string CertPath { get; set; } = string.Empty;

    [CliOption("--cert-password")]
    public string CertPassword { get; set; } = string.Empty;

    public static bool ValidateTimeout(DeployOptions opts)
        => opts.Timeout is >= 10 and <= 300;

    [CliHandler]
    public void Handle(IOutput output)
    {
        output.WriteInfo($"Deploying {Version} to {Environment}...");
    }
}

Load in the application:

app.LoadCommandsFromAssembly();   // scans calling assembly
app.Execute(args);

Or load from a plugin assembly:

app.LoadCommandsFromAssembly("/plugins/myapp.commands.dll");

Dependency injection

Command objects can receive services through constructor injection. ICommandResolver is the abstraction CLI uses when activating commands; ServiceProviderCommandResolver (available in the separate Kiwify.Kiwi.CLI.DependencyInjection package) implements it against any IServiceProvider:

// Command with constructor-injected services
public class DeployOptions
{
    private readonly IDeploymentService _deploy;
    private readonly ILogger<DeployOptions> _logger;

    public DeployOptions(IDeploymentService deploy, ILogger<DeployOptions> logger)
    {
        _deploy = deploy;
        _logger = logger;
    }

    public string Environment { get; set; } = string.Empty;
    public string Version     { get; set; } = string.Empty;

    [CliHandler]
    public void Handle(IOutput output)
    {
        _logger.LogInformation("Deploying {Version} to {Env}", Version, Environment);
        _deploy.Deploy(Version, Environment);
        output.WriteResult($"Deployed {Version} to {Environment}.");
    }
}

Wire the resolver during application setup:

var services = new ServiceCollection()
    .AddSingleton<IDeploymentService, DeploymentService>()
    .AddLogging()
    .BuildServiceProvider();

var app = new CommandLineApplication("myapp", "1.0.0", "Deployment tool");
app.SetCommandResolver(new ServiceProviderCommandResolver(services));
app.LoadCommandsFromAssembly();
app.Execute(args);

ServiceProviderCommandResolver is container-agnostic - any IServiceProvider-compatible container works. The parsing and validation pipeline operates independently of how the command instance is created; handler invocation is the only point at which the resolver is called.

Applications using the Kiwi declarative DI extensions (Kiwify.Kiwi.DI, built on top of Microsoft.Extensions.DependencyInjection) can register command types alongside other application services using attribute-driven patterns, including conditional registration based on configuration keys, environment names, or named conditions:

// Kiwi DI attribute registration - command registered as transient service,
// active only when the "Features:Deploy" configuration key is enabled
[Service(ServiceLifetime.Transient, ConfigKey = "Features:Deploy")]
public class DeployOptions
{
    public DeployOptions(IDeploymentService deploy, ILogger<DeployOptions> logger) { ... }
    // options and handler as above
}

This lets command types participate in the same declarative service-scanning model as other application services - useful in operational tooling where configuration flags or environment conditions govern which commands are active.

IConfiguration integration

Parsed CLI arguments participate in the standard .NET configuration layering model alongside JSON files, environment variables, and other sources:

var configBuilder = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddKiwiCommandModel(deployCommand, sectionPrefix: "Deploy");

IConfiguration config = configBuilder.Build();

// CLI values overlay the JSON file
string env = config["Deploy:Environment"]!;

Only properties that were explicitly set on the command line are contributed. Unset properties - even those with default values - are omitted, so the standard priority chain is preserved and existing configuration values are not accidentally overridden. In operational tooling where different environments have different JSON configuration files, this means a single invocation pattern can accommodate environment-specific configuration without conditional logic in the command layer.

Testing

Commands can be parsed and validated without invoking handlers, which makes it straightforward to unit-test argument parsing and validation rules in isolation:

var result = deployCommand.Parse(new[] { "--env", "staging", "--version", "v2.0.0" });

Assert.True(result.Success);
Assert.Equal("staging", result.Command!.Environment);

Use StringOutput from Presentation to capture output. Pass it directly to a Command<T> for unit tests, or use app.SetOutput for integration tests that route through the full application:

// Unit test - exercise one command in isolation
var output = new StringOutput();
deployCommand.Execute(new[] { "--env", "prod" }, output);
Assert.Contains("--version is required in prod", output.GetErrors());

// Integration test - route through CommandLineApplication
var captured = new StringOutput();
app.SetOutput(captured);
app.Execute(new[] { "deploy", "--env", "prod" });
Assert.Contains("--version is required in prod", captured.GetErrors());

Sample screens

Multi-command application help

$ myapp --help

myapp 1.0.0 - Deployment tool

Commands:
  deploy    Deploy the application
  rollback  Roll back to a previous version
  status    Show deployment status

Run 'myapp <command> --help' for command-specific help.

Single-command help

$ myapp deploy --help

myapp 1.0.0

Usage: myapp deploy [options]

Options:
  --env,     -e    Target environment (required) [dev | staging | prod]
  --version, -v    Version tag (required)
  --dry-run        Print plan without applying
  --timeout, -t    Timeout in seconds [default: 60]
  --help,    -h    Show this help

Validation errors

Missing required fields:

$ myapp deploy

Error: --env is required
Error: --version is required

Cross-property constraint (--version required when environment is prod):

$ myapp deploy --env prod

Error: --version is required in prod

Invalid enum value:

$ myapp deploy --env live --version v1.0

Error: --env: 'live' is not a valid value. Allowed: dev, staging, prod

Successful execution

$ myapp deploy --env staging --version v2.1.0

Deployed v2.1.0 to staging.

With --dry-run:

$ myapp deploy --env prod --version v2.1.0 --dry-run

[DRY RUN] No changes applied.
Deployed v2.1.0 to prod.

Architectural notes

Prefix-agnostic parsing. ArgumentParser<T> matches switches by exact name after stripping leading dashes. --env, -e, and (if registered) env all resolve to the same option.
Expression-based binding. Property selectors use Expression<Func<TCommand, object?>> rather than strings. The expression is compiled and the member name extracted at registration time, not re-evaluated during each parse call.
Validation order. Option-level constraints (required, valid values, regex, custom) are checked before cross-property rules. This prevents confusing errors about conditional requirements when a primary option is missing.
Declarative loader isolation. CommandLoader.CreateCommandFrom<T>() instantiates the class, reflects on its attributes, and produces the same Command<T> as the fluent path. It does not cache anything; each call produces a fresh command instance.

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

Terminal Output Infrastructure for .NET Applications - Kiwify.Kiwi.Presentation

Part of the Kiwi Foundation

Source and installation

Design philosophy

Intent

Architectural benefits

Where it fits

Comparison with alternatives

vs. Spectre.Console

vs. Pastel

vs. ConsoleTables / ConsoleMenu

vs. McMaster.Extensions.CommandLineUtils

How it is used - detailed walkthrough

Styled output

Writing through IOutputWriter

IOutput semantic channels

Prompts

Progress bars

Choice selectors

Sample screens

Styled console output

TextPrompt - interactive session

ConsoleChoiceSelector - single select

ConsoleMultiChoiceSelector - multi-select

Progress bars

Thread safety notes

See also

Structured Rendering for .NET CLI and Automation Tools - Kiwify.Kiwi.Renderer

Part of the Kiwi Foundation

Source and installation

Design philosophy

Intent

Architectural benefits

Where it fits

Comparison with alternatives

vs. ConsoleTables

vs. Spectre.Console

vs. CsvHelper

vs. Dapper / EF Core

How it is used - detailed walkthrough

JSON array → terminal table

Applying a theme

PredefinedColumn - subset, rename, align

Single object → key/value table

JSON syntax highlighting

HTML output

With Bootstrap CSS classes

RTF output

Auto-formatted column names

Fragment mode

Low-level grid API

Interactive paging

Sample screens

Auto-formatted column names (WithProperCasedTitles)

PredefinedColumn - subset, renamed, and aligned

JSON syntax highlighting (AsFormattedJson)

Interactive paging (PagedDataGrid)

HTML output

Architectural notes

See also

Argument Parsing and Command Routing for .NET CLI Tools - Kiwify.Kiwi.CLI

Part of the Kiwi Foundation

Source and installation

Design philosophy

Intent

Architectural benefits

Where it fits

Comparison with alternatives

vs. System.CommandLine

vs. CommandLineParser (CommandLine)

vs. CliFx

vs. Cocona

How it is used - detailed walkthrough

Fluent registration

Cross-property validation

Enum options

Complex types and loader syntax

Declarative mode

Dependency injection

Auto-formatted column names (`WithProperCasedTitles`)

JSON syntax highlighting (`AsFormattedJson`)

Interactive paging (`PagedDataGrid`)

`[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