GroundControl.Link 1.0.68-preview

GroundControl.Link

.NET client SDK for GroundControl — plugs directly into Microsoft.Extensions.Configuration so your app receives real-time configuration updates with zero custom plumbing.

Installation

dotnet add package GroundControl.Link

Quick Start

Integration is a two-step process: register the configuration source, then register the background services.

var builder = WebApplication.CreateBuilder(args);

// 1. Add GroundControl as a configuration source
builder.Configuration.AddGroundControl(options =>
{
    options.ServerUrl    = new Uri("https://groundcontrol.example.com");
    options.ClientId     = "<client-id>";
    options.ClientSecret = "<client-secret>";
});

// 2. Register background services (connection strategy, health check, metrics)
builder.Services.AddGroundControl(builder.Configuration);

var app = builder.Build();

Configuration is available immediately after step 1 completes (the SDK fetches the active snapshot synchronously during startup). Step 2 keeps the configuration synchronized in the background via SSE or polling.

Values are accessed through the standard IConfiguration API:

var connectionString = app.Configuration["Database:ConnectionString"];

Connection Modes

The ConnectionMode option controls how the SDK stays synchronized after startup:

builder.Configuration.AddGroundControl(options =>
{
    // ...
    options.ConnectionMode = ConnectionMode.Polling;
    options.PollingInterval = TimeSpan.FromMinutes(2);
});

Local Caching

When EnableLocalCache is true (the default), the SDK writes the active snapshot to a local JSON file. On the next startup, if the server is unreachable, the SDK serves configuration from the cache so the application can still start.

options.EnableLocalCache = true;
options.CacheFilePath    = "./groundcontrol-cache.json"; // default

Cached values are written in plaintext by default. To encrypt sensitive values at rest, implement IConfigurationProtector and assign it to options.Protector:

options.Protector = new MyProtector(); // implements IConfigurationProtector

Only entries the server has marked as sensitive are passed through the protector; non-sensitive entries (feature flags, URLs, thresholds) remain inspectable as plaintext in the cache file. The SDK treats the ciphertext returned by Protect as opaque — key rotation and algorithm versioning are the implementation's responsibility. If Unprotect throws (tampering, wrong key, unrecognized format), the cache file is invalidated and the SDK refetches from the server. The same happens when the cache was written under a different protector configuration than the current one.

Health Checks

The SDK registers a health check named GroundControl:

The health check is tagged with ready by default and can be customized via GroundControlOptions.HealthCheckTags.

Metrics

The SDK emits OpenTelemetry metrics under the GroundControl.Link meter:

Options Reference

Documentation

See the full SDK documentation for detailed guides on connection modes, caching, and configuration patterns.