Quick Start

This guide will help you get started with Apq.Cfg in 5 minutes.

Installation

dotnet add package Apq.Cfg

Create Configuration File

Create a config.json file:

{
    "App": {
        "Name": "MyApp",
        "Port": 8080,
        "Debug": true
    },
    "Database": {
        "Host": "localhost",
        "Port": 5432,
        "Name": "mydb"
    }
}

Read Configuration

using Apq.Cfg;

// Build configuration
var cfg = new CfgBuilder()
    .AddJsonFile("config.json")  // Uses default level 0
    .Build();

// Read string value
var appName = cfg["App:Name"];
Console.WriteLine($"App Name: {appName}");

// Read typed value
var port = cfg.GetValue<int>("App:Port");
Console.WriteLine($"Port: {port}");

// Read boolean value
var debug = cfg.GetValue<bool>("App:Debug");
Console.WriteLine($"Debug: {debug}");

Use Configuration Sections

// Get configuration section
var dbSection = cfg.GetSection("Database");

// Read values from section
var host = dbSection["Host"];
var dbPort = dbSection.GetValue<int>("Port");
var dbName = dbSection["Name"];

Console.WriteLine($"Database: {host}:{dbPort}/{dbName}");

Multi-Source Configuration

Each configuration source has a default level. Higher level values override lower level values:

Source Type	Default Level
Json, Ini, Xml, Yaml, Toml	0
Redis, Database	100
Consul, Etcd, Nacos, Apollo, Zookeeper	200
Vault	300
.env, EnvironmentVariables	400

var cfg = new CfgBuilder()
    .AddJsonFile("config.json")                              // Uses default level 0
    .AddJsonFile("config.local.json", level: 50, optional: true)
    .AddEnvironmentVariables(prefix: "APP_")             // Uses default level 400
    .Build();

Hot Reload

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", reloadOnChange: true)  // Uses default level 0
    .Build();

// Subscribe to configuration changes
cfg.ConfigChanges.Subscribe(e =>
{
    Console.WriteLine("Configuration updated!");
    foreach (var (key, change) in e.Changes)
    {
        Console.WriteLine($"  [{change.Type}] {key}: {change.OldValue} -> {change.NewValue}");
    }
});

Writable Configuration

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", writeable: true, isPrimaryWriter: true)  // Uses default level 0
    .Build();

// Modify configuration
cfg["App:Name"] = "NewAppName";
cfg["App:Port"] = "9090";

// Save to file
await cfg.SaveAsync();

Next Steps

• Installation - Detailed installation guide
• Basic Usage - Learn more usage patterns
• Config Sources - Explore all configuration sources