GroundControl.Link 1.0.64-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

If ASP.NET Core Data Protection is registered, cached values are encrypted at rest automatically.

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.