Confio 2.0.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. .NET Framework 4.6.2 This package targets .NET Framework 4.6.2. The package is compatible with this framework or higher. 
dotnet add package Confio --version 2.0.0
                    


                    

                
NuGet\Install-Package Confio -Version 2.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Confio" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Confio" Version="2.0.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Confio" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Confio --version 2.0.0
                    


                    

                
#r "nuget: Confio, 2.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Confio@2.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Confio&version=2.0.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Confio&version=2.0.0
                    


                            Install as a Cake Tool

Confio

English | 简体中文

A strongly typed configuration file library for .NET. Read and write JSON, YAML, TOML, and INI with the same models and APIs, including model defaults, validation, and protection for sensitive fields.

NuGet · User guide · Interactive sample · Changelog · Repository

Detailed guides and the sample UI are currently in Chinese.

Version 2.0 adds typed dictionary sections and preserves empty INI sections. Persisted dictionaries replace constructor entries. See the upgrade notes and dictionary guide.

Features

  • Direct file access: create a ConfigurationFile and start reading or writing. Both synchronous and asynchronous APIs are available, with automatic loading on the first operation.
  • One set of models, four formats: JSON, YAML/YML, TOML 1.1, and INI, with support for a root object or named configuration sections.
  • Defaults and validation: declare defaults in your models, with support for nested objects, collections, record/init, and business validation rules.
  • Sensitive field protection: mark strings, value types, or nested objects with [Protected] for automatic encryption and decryption. Windows DPAPI and cross-platform AES-256-GCM are built in.
  • Source generation and Native AOT: the source generator ships in the NuGet package. JIT and AOT use the same APIs.
  • Optional container integration: use ordinary DI, associate models with separate files, or integrate with native Configuration / Options / Host APIs.

Supported platforms

Application target Platforms Deployment
.NET 10 LTS Windows, Linux, macOS JIT, Native AOT
.NET 8 / 9 Windows, Linux, macOS JIT, Native AOT
.NET Framework 4.6.2–4.8.1 Windows Managed applications

Use an SDK-style project, PackageReference, and C# 12 or later. Building this repository requires the .NET 10 SDK. The compiler toolchain and the application runtime are separate requirements. Each supported Framework version has a matching package asset; .NET 9 uses the net8.0 asset. See the support matrix for toolchain requirements and verified environments.

Installation

Install from NuGet.org:

dotnet add package Confio --version 2.0.0

The default nuget.org feed is sufficient; no additional package source is required. See the installation guide for compiler requirements. To try the source, run the sample or build a local candidate package.

Version 1.0 establishes the public API and persisted configuration format baseline. Breaking changes require a major version increment. Read the changelog before upgrading.

Quick start

The following is a complete Program.cs. Declare your model and JSON context; the source generator supplies the configuration declarations:

using Confio;
using System.Text.Json.Serialization;

using var config = new ConfigurationFile(
    AppSettingsContext.Default, path: "settings.json");

var mail = await config.ReadAsync<MailSettings>();
mail.Host = "smtp.example.com";
mail.Port = 465;
mail.Password = "example-password";
await config.SaveAsync(mail);

[SettingsSection("Mail")]
public sealed class MailSettings
{
    public string Host { get; set; } = "localhost";
    public int Port { get; set; } = 587;

    [Protected]
    public string Password { get; set; } = "";
}

[JsonSerializable(typeof(MailSettings))]
public partial class AppSettingsContext : JsonSerializerContext
{
}

If the file does not exist, reading returns the model defaults. Saving writes the Mail section to the file and encrypts the password as a value starting with enc:v1:. Reading through the API returns the decrypted value.

For synchronous operations, use Read<MailSettings>() and Save(mail) on the same instance. Omitting path selects the current user's application configuration directory. Use [SettingsSection] without a name to read and write the file's root object.

Common operations

Task API Behavior
Read configuration Read<T>() / ReadAsync<T>() Return an independent copy of the most recently loaded or committed configuration
Save edits Save(model) / SaveAsync(model) Replace the entire section associated with the model
Update the latest file contents Update<T>(edit) / UpdateAsync<T>(edit) Read the latest values from disk, apply the edit, and save
Restore defaults Reset<T>() / ResetAsync<T>() Remove the model's persisted content and restore its declared defaults
Read external changes Reload() / ReloadAsync() Reload the file; retain the last successful snapshot if loading fails
Subscribe to changes OnChange<T>(listener) Notify after a successful commit or reload; dispose the returned subscription to unsubscribe

All asynchronous operations accept a CancellationToken. Changes to a returned model must be saved explicitly. External file edits require an explicit reload; subscriptions do not watch the file system.

Field protection

By default, Windows uses DPAPI for the current user. Linux and macOS use AES-256-GCM with an automatically persisted key. The key is generated once and reused across application launches.

You can explicitly select AES with an automatically managed key on every supported platform:

using var config = new ConfigurationFile(
    AppSettingsContext.Default,
    path: "settings.json",
    options: new ConfigurationFileOptions
    {
        Protection = ConfigurationProtection.AesGcm
    });

To share encrypted configuration across machines, supply the same stable 32-byte key through EncryptionKey. Use KeyFilePath to customize the location of an automatically managed key. Inspect config.Path and config.KeyFilePath to see the resolved paths.

When loading existing plaintext, protected fields are encrypted and written back by default. Set ProtectPlaintextOnLoad = false to disable this write-back. Missing keys or authentication failures produce an error and leave the configuration intact. See the field protection guide for key storage, cross-machine use, and file prefix rules.

File formats and behavior

The file extension selects the format. Use ConfigurationFileOptions.Format to specify it explicitly for .conf files or files without an extension.

Files default to UTF-8 without a BOM. Set ConfigurationFileOptions.Encoding to select another encoding, including Encoding.Default or GBK for INI. A Unicode BOM determines the input encoding; saving, including automatic plaintext protection, uses the selected output encoding. YAML supports UTF-8/16/32, and TOML requires UTF-8. See the encoding guide for examples and failure behavior.

Format Extensions Main constraints
JSON .json Supports null; accepts comments and trailing commas on input
YAML .yaml, .yml YAML 1.2 Core with string-keyed mappings
TOML .toml TOML 1.1; no native null
INI .ini Uses : for hierarchy and consecutive array indices; supports empty object/dictionary sections; no null, empty arrays/lists, or multiline values

Saving preserves data in other sections, but does not guarantee preservation of comments, formatting, or unknown properties in the section being saved. Values that a format cannot represent produce an error with the affected path and reason. See the format guide for details.

Run the sample

ConfioSample is an Avalonia desktop application. It shows draft values, values read by the application, and values saved on disk side by side. Try saving, reloading, encryption, Save / Update comparisons, and container integration.

Run from the repository root:

dotnet run --project samples/ConfioSample/ConfioSample.csproj -c Release

Build and verify

dotnet build Confio.sln -c Release
dotnet test tests/ConfioTests/ConfioTests.csproj -c Release --no-build

See development and verification for consumer, Native AOT, isolated NuGet, WSL, and publishing commands. Platform verification status is maintained in the verification records.

Contributing

Report issues or suggest improvements through the repository. Include the package version, operating system, target framework, a minimal model, and steps to reproduce. Remove real passwords and keys from reports.

Follow the development guidelines and include verification for behavior changes. Product contracts and technical decisions are documented in the design.

License

Confio is licensed under the MIT License. Commercial use, modification, and distribution are permitted. Distributions must retain the copyright notice and license text.

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

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.0 141 9/24/2026
1.1.0 110 9/18/2026
1.0.0 112 9/18/2026

Adds typed dictionary sections across JSON, YAML, TOML, and INI using the existing APIs. Breaking changes: persisted dictionaries replace constructor entries, and empty INI sections represent empty objects or dictionaries. Mutable dictionary instances must implement System.Collections.IDictionary. Includes source-generated metadata and Native AOT verification. Release notes: https://github.com/zeekmeta/Confio/blob/main/CHANGELOG.md