https://github.com/replane-dev/replane-dotnet
Dynamic configuration for C# and .NET
https://github.com/replane-dev/replane-dotnet
asp-net-core csharp dotnet dynamic-config dynamic-log-level environment-variables feature-flags kill-switches operational-tuning remote-config
Last synced: about 2 months ago
JSON representation
Dynamic configuration for C# and .NET
- Host: GitHub
- URL: https://github.com/replane-dev/replane-dotnet
- Owner: replane-dev
- Created: 2025-12-20T14:17:00.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-11T02:44:15.000Z (2 months ago)
- Last Synced: 2026-05-11T04:38:49.444Z (2 months ago)
- Topics: asp-net-core, csharp, dotnet, dynamic-config, dynamic-log-level, environment-variables, feature-flags, kill-switches, operational-tuning, remote-config
- Language: C#
- Homepage: https://replane.dev
- Size: 134 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
Replane .NET SDK
Dynamic configuration for .NET applications.
[Replane](https://github.com/replane-dev/replane) is a dynamic configuration manager that lets you tweak your software without running scripts or building your own admin panel. Store feature flags, rate limits, UI text, log level, rollout percentage, and more. Delegate editing to teammates and share config across services. No redeploys needed.
## Why Dynamic Configuration?
- **Feature flags** – toggle features, run A/B tests, roll out to user segments
- **Operational tuning** – adjust limits, TTLs, and timeouts without redeploying
- **Per-environment settings** – different values for production, staging, dev
- **Incident response** – instantly revert to a known-good version
- **Cross-service configuration** – share settings with realtime sync
- **Non-engineer access** – safe editing with schema validation
## Installation
```bash
dotnet add package Replane
```
## Quick Start
```csharp
using Replane;
// Create client and connect
await using var replane = new ReplaneClient();
await replane.ConnectAsync(new ConnectOptions
{
BaseUrl = "https://replane.example.com",
SdkKey = "your-sdk-key"
});
// Get a config value
var featureEnabled = replane.Get("feature-enabled");
var maxItems = replane.Get("max-items", defaultValue: 100);
```
## Features
- **Real-time updates** via Server-Sent Events (SSE)
- **Client-side evaluation** - context never leaves your application
- **Gradual rollouts** with percentage-based segmentation
- **Override rules** with flexible conditions
- **Type-safe** configuration access
- **Async/await** support throughout
- **In-memory test client** for unit testing
## Usage
### Basic Configuration Access
```csharp
// Get typed config values
var enabled = replane.Get("feature-enabled");
var limit = replane.Get("rate-limit");
var apiKey = replane.Get("api-key");
// With default values
var timeout = replane.Get("timeout-ms", defaultValue: 5000);
```
### Complex Types
Configs can store complex objects that are deserialized on demand:
```csharp
// Define your config type
public record ThemeConfig
{
public bool DarkMode { get; init; }
public string PrimaryColor { get; init; } = "";
public int FontSize { get; init; }
}
// Get complex config
var theme = replane.Get("theme");
Console.WriteLine($"Dark mode: {theme.DarkMode}, Color: {theme.PrimaryColor}");
// Works with overrides too - different themes for different users
var userTheme = replane.Get("theme", new ReplaneContext { ["plan"] = "premium" });
```
### Context-Based Overrides
Evaluate configs based on user context:
```csharp
// Create context for override evaluation
var context = new ReplaneContext
{
["user_id"] = "user-123",
["plan"] = "premium",
["region"] = "us-east"
};
// Get config with context
var premiumFeature = replane.Get("premium-feature", context);
```
### Default Context
Set default context that's merged with per-call context:
```csharp
var replane = new ReplaneClient(new ReplaneClientOptions
{
BaseUrl = "https://your-server.com",
SdkKey = "your-key",
Context = new ReplaneContext
{
["app_version"] = "2.0.0",
["platform"] = "ios"
}
});
```
### Real-time Updates
Subscribe to config changes using the `ConfigChanged` event:
```csharp
// Subscribe to all config changes
replane.ConfigChanged += (sender, e) =>
{
Console.WriteLine($"Config '{e.ConfigName}' updated");
};
// Get typed value from the event
replane.ConfigChanged += (sender, e) =>
{
if (e.ConfigName == "feature-flag")
{
var enabled = e.GetValue();
Console.WriteLine($"Feature flag changed to: {enabled}");
}
};
// Works with complex types too
replane.ConfigChanged += (sender, e) =>
{
if (e.ConfigName == "theme")
{
var theme = e.GetValue();
Console.WriteLine($"Theme updated: dark={theme?.DarkMode}");
}
};
// Unsubscribe when needed
void OnConfigChanged(object? sender, ConfigChangedEventArgs e)
{
Console.WriteLine($"Config changed: {e.ConfigName}");
}
replane.ConfigChanged += OnConfigChanged;
// Later...
replane.ConfigChanged -= OnConfigChanged;
```
### Default Values
Provide default values for when configs aren't loaded:
```csharp
var replane = new ReplaneClient(new ReplaneClientOptions
{
Defaults = new Dictionary
{
["feature-enabled"] = false,
["rate-limit"] = 100
}
});
```
### Required Configs
Ensure specific configs are present on initialization:
```csharp
var replane = new ReplaneClient(new ReplaneClientOptions
{
Required = ["essential-config", "api-endpoint"]
});
// ConnectAsync will throw if required configs are missing
await replane.ConnectAsync(new ConnectOptions
{
BaseUrl = "https://your-server.com",
SdkKey = "your-key"
});
```
## Testing
Use the in-memory client for unit tests:
```csharp
using Replane.Testing;
[Fact]
public void TestFeatureFlag()
{
// Create test client with initial configs
using var client = TestClient.Create(new Dictionary
{
["feature-enabled"] = true,
["max-items"] = 50
});
// Use like the real client
client.Get("feature-enabled").Should().BeTrue();
client.Get("max-items").Should().Be(50);
}
```
### Testing with Overrides
```csharp
[Fact]
public void TestOverrides()
{
using var client = TestClient.Create();
// Set up config with overrides
client.SetConfigWithOverrides(
name: "premium-feature",
value: false,
overrides: [
new OverrideData
{
Name = "premium-users",
Conditions = [
new ConditionData
{
Operator = "equals",
Property = "plan",
Expected = "premium"
}
],
Value = true
}
]);
// Test with different contexts
client.Get("premium-feature", new ReplaneContext { ["plan"] = "free" })
.Should().BeFalse();
client.Get("premium-feature", new ReplaneContext { ["plan"] = "premium" })
.Should().BeTrue();
}
```
### Testing Segmentation
```csharp
[Fact]
public void TestABTest()
{
using var client = TestClient.Create();
client.SetConfigWithOverrides(
name: "ab-test",
value: "control",
overrides: [
new OverrideData
{
Name = "treatment-group",
Conditions = [
new ConditionData
{
Operator = "segmentation",
Property = "user_id",
FromPercentage = 0,
ToPercentage = 50,
Seed = "experiment-seed"
}
],
Value = "treatment"
}
]);
// Result is deterministic for each user
var result = client.Get("ab-test", new ReplaneContext { ["user_id"] = "user-123" });
// Will consistently be either "control" or "treatment" for this user
}
```
### Testing Config Changes
```csharp
[Fact]
public void TestConfigChangeEvent()
{
using var client = TestClient.Create();
var receivedEvents = new List();
client.ConfigChanged += (sender, e) => receivedEvents.Add(e);
client.Set("feature", true);
client.Set("feature", false);
receivedEvents.Should().HaveCount(2);
receivedEvents[0].GetValue().Should().BeTrue();
receivedEvents[1].GetValue().Should().BeFalse();
}
```
### Testing Complex Types
```csharp
public record FeatureFlags
{
public bool NewUI { get; init; }
public List EnabledModules { get; init; } = [];
}
[Fact]
public void TestComplexType()
{
var flags = new FeatureFlags
{
NewUI = true,
EnabledModules = ["dashboard", "analytics"]
};
using var client = TestClient.Create(new Dictionary
{
["features"] = flags
});
var result = client.Get("features");
result!.NewUI.Should().BeTrue();
result.EnabledModules.Should().Contain("dashboard");
}
[Fact]
public void TestComplexTypeWithOverrides()
{
using var client = TestClient.Create();
var defaultTheme = new ThemeConfig { DarkMode = false, PrimaryColor = "#000", FontSize = 12 };
var premiumTheme = new ThemeConfig { DarkMode = true, PrimaryColor = "#FFD700", FontSize = 16 };
client.SetConfigWithOverrides(
name: "theme",
value: defaultTheme,
overrides: [
new OverrideData
{
Name = "premium-theme",
Conditions = [
new ConditionData { Operator = "equals", Property = "plan", Expected = "premium" }
],
Value = premiumTheme
}
]);
client.Get("theme", new ReplaneContext { ["plan"] = "free" })!
.DarkMode.Should().BeFalse();
client.Get("theme", new ReplaneContext { ["plan"] = "premium" })!
.DarkMode.Should().BeTrue();
}
```
## Dependency Injection
Both `ReplaneClient` and `InMemoryReplaneClient` implement the `IReplaneClient` interface, making it easy to swap implementations for testing or use with dependency injection:
### ASP.NET Core Registration
```csharp
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// Register Replane client as the interface
builder.Services.AddSingleton(sp =>
{
var client = new ReplaneClient(new ReplaneClientOptions
{
BaseUrl = builder.Configuration["Replane:BaseUrl"]!,
SdkKey = builder.Configuration["Replane:SdkKey"]!
});
return client;
});
var app = builder.Build();
// Connect on startup
var replane = app.Services.GetRequiredService();
if (replane is ReplaneClient realClient)
{
await realClient.ConnectAsync();
}
// Use in controllers/services
app.MapGet("/api/items", (IReplaneClient replane) =>
{
var maxItems = replane.Get("max-items", defaultValue: 100);
return Results.Ok(new { maxItems });
});
app.Run();
```
### Using in Services
```csharp
public class FeatureService
{
private readonly IReplaneClient _replane;
public FeatureService(IReplaneClient replane)
{
_replane = replane;
}
public bool IsFeatureEnabled(string userId)
{
return _replane.Get("new-feature", new ReplaneContext
{
["user_id"] = userId
});
}
}
```
### Testing with DI
```csharp
[Fact]
public void TestFeatureService()
{
// Create test client implementing IReplaneClient
using var testClient = TestClient.Create(new Dictionary
{
["new-feature"] = true
});
// Inject into service
var service = new FeatureService(testClient);
// Test the service
service.IsFeatureEnabled("user-123").Should().BeTrue();
}
```
## Configuration Options
### ReplaneClientOptions
Options passed to the constructor. Connection options are provided via `ConnectAsync`.
| Option | Type | Default | Description |
| ------------ | ----------------------------- | ------- | ------------------------------- |
| `Context` | `ReplaneContext` | `null` | Default context for evaluations |
| `Defaults` | `Dictionary` | `null` | Default values |
| `Required` | `IReadOnlyList` | `null` | Required config names |
| `HttpClient` | `HttpClient` | `null` | Custom HttpClient |
| `Debug` | `bool` | `false` | Enable debug logging |
| `Logger` | `IReplaneLogger` | `null` | Custom logger implementation |
### ConnectOptions
Connection options passed to `ConnectAsync`.
| Option | Type | Default | Description |
| -------------------- | -------- | -------- | -------------------------- |
| `BaseUrl` | `string` | required | Replane server URL |
| `SdkKey` | `string` | required | SDK key for authentication |
| `RequestTimeoutMs` | `int` | `2000` | HTTP request timeout |
| `ConnectionTimeoutMs`| `int` | `5000` | Initial connection timeout |
| `RetryDelayMs` | `int` | `200` | Initial retry delay |
| `InactivityTimeoutMs`| `int` | `30000` | SSE inactivity timeout |
| `Agent` | `string` | `null` | Agent identifier |
## Debug Logging
Enable debug logging to troubleshoot issues:
```csharp
var replane = new ReplaneClient(new ReplaneClientOptions
{
Debug = true
});
await replane.ConnectAsync(new ConnectOptions
{
BaseUrl = "https://your-server.com",
SdkKey = "your-key"
});
```
This outputs detailed logs including:
- Client initialization with all options
- SSE connection lifecycle (connect, reconnect, disconnect)
- Every `Get()` call with config name, context, and result
- Override evaluation details (which conditions matched/failed)
- Raw SSE event data
Example output:
```
[DEBUG] Replane: Initializing ReplaneClient with options:
[DEBUG] Replane: BaseUrl: https://your-server.com
[DEBUG] Replane: SdkKey: your...key
[DEBUG] Replane: Connecting to SSE: https://your-server.com/api/sdk/v1/replication/stream
[DEBUG] Replane: SSE event received: type=init
[DEBUG] Replane: Initialization complete: 5 configs loaded
[DEBUG] Replane: Get("feature-flag") called
[DEBUG] Replane: Config "feature-flag" found, base value: false, overrides: 1
[DEBUG] Replane: Evaluating override #0 (conditions: property(plan equals "premium"))
[DEBUG] Replane: Condition: property "plan" ("premium") equals "premium" => Matched
[DEBUG] Replane: Override #0 matched, returning: true
```
### Custom Logger
Provide your own logger implementation:
```csharp
public class MyLogger : IReplaneLogger
{
public void Log(LogLevel level, string message, Exception? exception = null)
{
// Forward to your logging framework
_logger.Log(MapLevel(level), exception, message);
}
}
var replane = new ReplaneClient(new ReplaneClientOptions
{
BaseUrl = "https://your-server.com",
SdkKey = "your-key",
Logger = new MyLogger()
});
```
## Condition Operators
The SDK supports the following condition operators for overrides:
| Operator | Description |
| ----------------------- | -------------------------- |
| `equals` | Exact match |
| `in` | Value is in list |
| `not_in` | Value is not in list |
| `less_than` | Less than comparison |
| `less_than_or_equal` | Less than or equal |
| `greater_than` | Greater than comparison |
| `greater_than_or_equal` | Greater than or equal |
| `segmentation` | Percentage-based bucketing |
| `and` | All conditions must match |
| `or` | Any condition must match |
| `not` | Negate a condition |
## Error Handling
```csharp
try
{
await replane.ConnectAsync();
var value = replane.Get("my-config");
}
catch (AuthenticationException)
{
// Invalid SDK key
}
catch (ConfigNotFoundException ex)
{
// Config doesn't exist
Console.WriteLine($"Config not found: {ex.ConfigName}");
}
catch (ReplaneTimeoutException ex)
{
// Operation timed out
Console.WriteLine($"Timeout after {ex.TimeoutMs}ms");
}
catch (ReplaneException ex)
{
// Other errors
Console.WriteLine($"Error [{ex.Code}]: {ex.Message}");
}
```
## Examples
See the [examples](./examples/) directory for complete working examples:
| Example | Description |
| -------------------------------------------------------- | -------------------------------------------------- |
| [BasicUsage](./examples/BasicUsage/) | Simple console app with basic config reading |
| [ConsoleWithOverrides](./examples/ConsoleWithOverrides/) | Context-based overrides and user segmentation |
| [BackgroundWorker](./examples/BackgroundWorker/) | Long-running service with real-time config updates |
| [WebApiIntegration](./examples/WebApiIntegration/) | ASP.NET Core Web API with middleware and DI |
| [UnitTesting](./examples/UnitTesting/) | Unit testing with the in-memory test client |
Each example is self-contained and can be copied and run independently.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.
## Community
Have questions or want to discuss Replane? Join the conversation in [GitHub Discussions](https://github.com/orgs/replane-dev/discussions).
## License
MIT