Configo.Client

Configo.Client

A modern .NET client library for integrating with Configo configuration management.

Overview

This library provides seamless integration between your .NET 10.0+ applications and Configo, allowing you to retrieve configuration from a centralized Configo server and use it through the standard IConfiguration interface.

Features

• ✅ Full integration with IConfiguration and IOptions<T> patterns
• ✅ Support for hierarchical/nested configuration
• ✅ Automatic configuration refresh with AddConfigoAutoRefresh()
• ✅ JSON-based caching for offline support (when Configo server is unavailable)
• ✅ Strongly-typed configuration binding
• ✅ Compatible with ASP.NET Core, Worker Services, Console apps, and more
• ✅ Async/await throughout
• ✅ Built on .NET 10.0+

Installation

dotnet add package Configo.Client

Or via NuGet Package Manager:

Install-Package Configo.Client

Quick Start

Basic Usage

Add Configo as a configuration source during application startup:

using Configo.Client;

var builder = WebApplication.CreateBuilder(args);

// Add Configo configuration
builder.Configuration.AddConfigo(new ConfigoOptions
{
    Url = "https://your-configo-server.com",
    ApiKey = "your-api-key-here"
});

var app = builder.Build();

Now you can access configuration values through IConfiguration:

var companyName = builder.Configuration["Company:Name"];
var apiEndpoint = builder.Configuration["Api:Endpoint"];

Strongly-Typed Configuration

Use the standard IOptions<T> pattern for strongly-typed configuration:

// Define your configuration class
public class ApiSettings
{
    public string Endpoint { get; set; }
    public int Timeout { get; set; }
    public bool EnableRetry { get; set; }
}

// Register it
builder.Services.Configure<ApiSettings>(builder.Configuration.GetSection("Api"));

// Inject and use it
public class MyService
{
    private readonly ApiSettings _apiSettings;

    public MyService(IOptions<ApiSettings> apiSettings)
    {
        _apiSettings = apiSettings.Value;
    }

    public void DoWork()
    {
        var endpoint = _apiSettings.Endpoint;
        // ...
    }
}

Auto-Refresh Configuration

Enable automatic configuration refresh to pick up changes without restarting your application:

var configoOptions = new ConfigoOptions
{
    Url = "https://your-configo-server.com",
    ApiKey = "your-api-key-here",
    AutoRefreshInterval = TimeSpan.FromMinutes(5) // Refresh every 5 minutes
};

builder.Configuration.AddConfigo(configoOptions);

// Enable auto-refresh background service
builder.Services.AddConfigoAutoRefresh(configoOptions);

With auto-refresh, use IOptionsSnapshot<T> or IOptionsMonitor<T> to get updated values:

public class MyService
{
    private readonly IOptionsSnapshot<ApiSettings> _apiSettings;

    public MyService(IOptionsSnapshot<ApiSettings> apiSettings)
    {
        _apiSettings = apiSettings;
    }

    public void DoWork()
    {
        // This will get the latest refreshed configuration
        var currentSettings = _apiSettings.Value;
    }
}

Configuration Options

ConfigoOptions

Property	Type	Required	Default	Description
Url	string	Yes	-	The Configo server URL
ApiKey	string	Yes	-	The API key for authentication
CacheFileName	string	No	"appsettings.configo.json"	Cache file for offline support
AutoRefreshInterval	TimeSpan?	No	null	How often to refresh configuration (requires AddConfigoAutoRefresh())

Example with All Options

var configoOptions = new ConfigoOptions
{
    Url = "https://your-configo-server.com",
    ApiKey = "your-api-key-here",
    CacheFileName = "my-config-cache.json",
    AutoRefreshInterval = TimeSpan.FromMinutes(10)
};

builder.Configuration.AddConfigo(configoOptions);
builder.Services.AddConfigoAutoRefresh(configoOptions);

Caching and Offline Support

By default, configuration retrieved from Configo is cached in appsettings.configo.json. This cache file is used when:

• The Configo server is unreachable
• Network connectivity is lost
• The Configo server is temporarily down

Customize Cache Location

builder.Configuration.AddConfigo(new ConfigoOptions
{
    Url = "https://your-configo-server.com",
    ApiKey = "your-api-key-here",
    CacheFileName = "/app/config/configo-cache.json"
});

Disable Caching

builder.Configuration.AddConfigo(new ConfigoOptions
{
    Url = "https://your-configo-server.com",
    ApiKey = "your-api-key-here",
    CacheFileName = null // No caching
});

Configuration Format

Configo returns configuration as hierarchical JSON. All standard JSON structures are supported:

{
  "Company": {
    "Name": "Acme Corp",
    "Address": {
      "Street": "123 Main St",
      "City": "Springfield"
    }
  },
  "Api": {
    "Endpoint": "https://api.example.com",
    "Timeout": 30,
    "EnableRetry": true
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=myserver;Database=mydb;",
    "CacheConnection": "localhost:6379"
  },
  "Features": {
    "FeatureA": true,
    "FeatureB": false
  }
}

Access nested values using : as a separator:

var companyName = configuration["Company:Name"];
var street = configuration["Company:Address:Street"];
var apiEndpoint = configuration["Api:Endpoint"];
var connectionString = configuration["ConnectionStrings:DefaultConnection"];

Usage Scenarios

ASP.NET Core Web Application

var builder = WebApplication.CreateBuilder(args);

// Add Configo with auto-refresh
var configoOptions = new ConfigoOptions
{
    Url = "https://configo.example.com",
    ApiKey = builder.Configuration["Configo:ApiKey"], // Read from appsettings.json
    AutoRefreshInterval = TimeSpan.FromMinutes(5)
};
builder.Configuration.AddConfigo(configoOptions);

builder.Services.AddConfigoAutoRefresh(configoOptions);

// Configure services using Configo configuration
builder.Services.Configure<DatabaseSettings>(
    builder.Configuration.GetSection("Database"));

var app = builder.Build();
app.Run();

Worker Service / Background Service

var builder = Host.CreateDefaultBuilder(args);

builder.ConfigureAppConfiguration((context, config) =>
{
    config.AddConfigo(new ConfigoOptions
    {
        Url = "https://configo.example.com",
        ApiKey = Environment.GetEnvironmentVariable("CONFIGO_API_KEY"),
        AutoRefreshInterval = TimeSpan.FromMinutes(10)
    });
});

builder.ConfigureServices((context, services) =>
{
    services.AddConfigoAutoRefresh(new ConfigoOptions
    {
        Url = "https://configo.example.com",
        ApiKey = Environment.GetEnvironmentVariable("CONFIGO_API_KEY"),
        AutoRefreshInterval = TimeSpan.FromMinutes(10)
    });

    services.AddHostedService<MyBackgroundService>();
});

var host = builder.Build();
host.Run();

Console Application

var configuration = new ConfigurationBuilder()
    .AddConfigo(new ConfigoOptions
    {
        Url = "https://configo.example.com",
        ApiKey = "your-api-key"
    })
    .Build();

var setting = configuration["MySetting"];
Console.WriteLine($"Setting value: {setting}");

Using Custom HttpClient

If you need to customize the HTTP client (e.g., for proxy settings or custom headers):

var httpClient = new HttpClient
{
    BaseAddress = new Uri("https://configo.example.com"),
    Timeout = TimeSpan.FromSeconds(30)
};

// Add custom headers, configure proxy, etc.
httpClient.DefaultRequestHeaders.Add("X-Custom-Header", "value");

builder.Configuration.AddConfigo(httpClient, new ConfigoOptions
{
    Url = "https://configo.example.com",
    ApiKey = "your-api-key"
});

Error Handling

The library throws ConfigoException when:

• Configuration options are invalid (missing URL or API key)
• The Configo server is unreachable and no cache file exists
• The cache file cannot be written
• The API response cannot be parsed

try
{
    var configuration = new ConfigurationBuilder()
        .AddConfigo(new ConfigoOptions
        {
            Url = "https://configo.example.com",
            ApiKey = "your-api-key"
        })
        .Build();
}
catch (ConfigoException ex)
{
    // Handle Configo-specific errors
    Console.WriteLine($"Configo error: {ex.Message}");
    // Fall back to default configuration, log error, etc.
}

Best Practices

1. Store API Keys Securely

Never hardcode API keys. Use environment variables or Azure Key Vault:

builder.Configuration.AddConfigo(new ConfigoOptions
{
    Url = "https://configo.example.com",
    ApiKey = builder.Configuration["Configo:ApiKey"] // From appsettings.json or env var
});

2. Use Auto-Refresh for Long-Running Applications

For web apps and services that run continuously, enable auto-refresh:

var configoOptions = new ConfigoOptions
{
    Url = "https://configo.example.com",
    ApiKey = apiKey,
    AutoRefreshInterval = TimeSpan.FromMinutes(5)
};

builder.Configuration.AddConfigo(configoOptions);
builder.Services.AddConfigoAutoRefresh(configoOptions);

3. Use IOptionsSnapshot or IOptionsMonitor with Auto-Refresh

When using auto-refresh, inject IOptionsSnapshot<T> (scoped) or IOptionsMonitor<T> (singleton) instead of IOptions<T>:

// Good - gets updated values
public MyService(IOptionsSnapshot<MySettings> settings) { }

// Also good - can subscribe to change notifications
public MyService(IOptionsMonitor<MySettings> settings) { }

// Bad - won't see refreshed values
public MyService(IOptions<MySettings> settings) { }

4. Enable Caching for Resilience

Always use caching (enabled by default) for production applications to ensure availability when Configo is temporarily unavailable.

5. Set Appropriate Refresh Intervals

Choose refresh intervals based on your needs:

• High-frequency changes: 1-5 minutes
• Moderate changes: 10-30 minutes
• Infrequent changes: 1+ hours

Shorter intervals increase server load and network traffic.

.NET Framework Support

For .NET Framework 4.8 applications, use the separate Configo.Client.NetFramework package which provides integration with ConfigurationManager.AppSettings and ConfigurationManager.ConnectionStrings.

See the Configo.Client.NetFramework README for details.

Troubleshooting

Configuration not loading

1. Verify the Configo URL and API key are correct
2. Check that the Configo server is running and accessible
3. Look for a cached configuration file (appsettings.configo.json)
4. Check application logs for ConfigoException messages

Auto-refresh not working

1. Ensure AddConfigoAutoRefresh() is called in addition to AddConfigo()
2. Verify AutoRefreshInterval is set to a positive value
3. Use IOptionsSnapshot<T> or IOptionsMonitor<T> instead of IOptions<T>
4. Check that the Configo configuration provider is registered correctly

Cache file permissions

If you see caching errors:

1. Ensure the application has write permissions to the cache directory
2. Specify an explicit cache path in a writable location
3. Check disk space availability

License

See the main Configo repository for license information.

Support

For issues, feature requests, or questions, please open an issue on the Configo GitHub repository.