Configo.Client.NetFramework

Configo.Client.NetFramework

A .NET Framework 4.8 client library for integrating with Configo configuration management.

Overview

This library provides a simple way for .NET Framework applications (Web applications, Windows Services, Console apps) to retrieve configuration from a Configo server and automatically populate ConfigurationManager.AppSettings and ConfigurationManager.ConnectionStrings using the standard Microsoft.Configuration.ConfigurationBuilders pattern.

Features

• ✅ Built on Microsoft.Configuration.ConfigurationBuilders - the standard way to extend configuration in .NET Framework
• ✅ Automatic population of ConfigurationManager.AppSettings
• ✅ Automatic population of ConfigurationManager.ConnectionStrings
• ✅ JSON-based caching for offline support (when Configo server is unavailable)
• ✅ Declarative configuration via Web.config/App.config
• ✅ Compatible with .NET Framework 4.8

Installation

Install-Package Configo.Client.NetFramework

Or via .NET CLI:

dotnet add package Configo.Client.NetFramework

Usage

Basic Setup (Web.config or App.config)

Add the Configo configuration builder to your configBuilders section and apply it to appSettings and connectionStrings:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="configBuilders" 
             type="System.Configuration.ConfigurationBuildersSection, System.Configuration, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" 
             restartOnExternalChanges="false" 
             requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="configoAppSettings" 
           type="Configo.Client.NetFramework.ConfigoConfigurationBuilder, Configo.Client.NetFramework"
           url="https://your-configo-server.com"
           apiKey="your-api-key-here"
           section="AppSettings"
           cacheFileName="appsettings.configo.json" />
      <add name="configoConnectionStrings" 
           type="Configo.Client.NetFramework.ConfigoConfigurationBuilder, Configo.Client.NetFramework"
           url="https://your-configo-server.com"
           apiKey="your-api-key-here"
           section="ConnectionStrings"
           cacheFileName="appsettings.configo.json" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="configoAppSettings">
    <!-- Your existing app settings here (optional) -->
    <!-- Configo will add/override these values -->
  </appSettings>

  <connectionStrings configBuilders="configoConnectionStrings">
    <!-- Your existing connection strings here (optional) -->
    <!-- Configo will add/override these values -->
  </connectionStrings>

  <!-- Rest of your configuration -->
</configuration>

That's it! No code changes needed. The configuration builder will automatically:

1. Fetch configuration from your Configo server at application startup
2. Cache it to appsettings.configo.json for offline scenarios
3. Populate ConfigurationManager.AppSettings and ConfigurationManager.ConnectionStrings

Configuration Builder Attributes

Advanced Configuration

Using Environment Variables for API Key

For security, you can use environment variables or other config sources for sensitive values:

<configBuilders>
  <builders>
    <add name="Environment" 
         type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment" />
    <add name="Configo" 
         type="Configo.Client.NetFramework.ConfigoConfigurationBuilder, Configo.Client.NetFramework"
         url="https://your-configo-server.com"
         apiKey="${CONFIGO_API_KEY}"
         section="AppSettings"
         cacheFileName="appsettings.configo.json" />
  </builders>
</configBuilders>

<appSettings configBuilders="Environment,Configo">
  <!-- Environment builder will resolve ${CONFIGO_API_KEY} before Configo builder runs -->
</appSettings>

Custom Cache Location

<add name="Configo" 
     type="Configo.Client.NetFramework.ConfigoConfigurationBuilder, Configo.Client.NetFramework"
     url="https://your-configo-server.com"
     apiKey="your-api-key-here"
     section="AppSettings"
     cacheFileName="C:\ProgramData\MyApp\configo-cache.json" />

Disable Caching

Set cacheFileName to an empty string to disable caching:

<add name="Configo" 
     type="Configo.Client.NetFramework.ConfigoConfigurationBuilder, Configo.Client.NetFramework"
     url="https://your-configo-server.com"
     apiKey="your-api-key-here"
     section="AppSettings"
     cacheFileName="" />

Accessing Configuration in Code

Once configured, access settings normally through ConfigurationManager:

using System.Configuration;

// AppSettings
var mySetting = ConfigurationManager.AppSettings["MySetting"];
var apiEndpoint = ConfigurationManager.AppSettings["ApiEndpoint"];

// ConnectionStrings
var connString = ConfigurationManager.ConnectionStrings["MyDatabase"].ConnectionString;

Configuration Format

The Configo server should return JSON in the following format:

{
  "AppSettings": {
    "Setting1": "Value1",
    "Setting2": "Value2",
    "ApiEndpoint": "https://api.example.com"
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=myserver;Database=mydb;Trusted_Connection=true;",
    "CacheConnection": "Server=cache;Database=redis;..."
  }
}

Only the AppSettings and ConnectionStrings sections are processed. Other sections in the JSON will be ignored.

Caching and Offline Support

By default, configuration is cached in appsettings.configo.json in the application's working directory. This cache file is used when:

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

When using the cache fallback, a warning is written to the trace output.

Error Handling

The configuration builder will throw ConfigurationErrorsException when:

• Required attributes (url, apiKey) are missing
• The URL is not a valid absolute URI
• The Configo server is unreachable and no cache file exists
• The cache file exists but cannot be parsed

These errors occur during application startup, which is the standard behavior for configuration errors in .NET Framework.

Integration with Other ConfigBuilders

Configo works seamlessly with other configuration builders. You can chain multiple builders:

<configBuilders>
  <builders>
    <add name="Environment" 
         type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment" />
    <add name="Configo" 
         type="Configo.Client.NetFramework.ConfigoConfigurationBuilder, Configo.Client.NetFramework"
         url="https://configo.example.com"
         section="AppSettings"
         apiKey="${CONFIGO_API_KEY}" />
    <add name="UserSecrets" 
         type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />
  </builders>
</configBuilders>

<appSettings configBuilders="Environment,Configo,UserSecrets">
  <!-- Builders are applied in order: Environment → Configo → UserSecrets -->
</appSettings>

Limitations

This is a simplified implementation for .NET Framework with the following limitations compared to the .NET Core version:

• ✋ No auto-refresh support (configuration is loaded once at startup)
• ✋ Only supports AppSettings and ConnectionStrings sections
• ✋ No nested/hierarchical configuration support beyond these sections
• ✋ No strongly-typed configuration binding (use .NET Core's IOptions<T> for that)

For more advanced scenarios, consider migrating to .NET Core/5+ and using Configo.Client.

Comparison with Configo.Client (.NET Core)

Troubleshooting

Configuration builder not loading

1. Verify the configSections element is at the top of your config file
2. Check that the type attribute exactly matches the assembly-qualified name
3. Ensure Configo.Client.NetFramework.dll is in your application's bin directory
4. Check the Application Event Log for any startup errors

Configo server connection errors

1. Verify the URL and API key are correct
2. Check network connectivity to the Configo server
3. Look for a cached configuration file (appsettings.configo.json)
4. Check trace output for warnings about cache fallback

Configuration values not appearing

1. Verify the section uses configBuilders="Configo"
2. Check that the Configo server is returning data in the correct format
3. Inspect the cache file to verify the data structure
4. Enable trace output to see what the builder is doing

License

See the main Configo repository for license information.