Cloudstrap.Core 0.2.0-preview.83

Cloudstrap.Core

The typed, fail-fast-validated settings model behind the Cloudstrap library suite.

Describe your application once — identity, logging, telemetry, correlation, health probes and outbound HTTP clients — in a Cloudstrap: configuration section. Every Cloudstrap package reads that same model instead of inventing its own keys, and a typo in appsettings.json stops the app at startup with a message naming the offending setting.

Cloudstrap.Core is a leaf package: settings, validation, and two entry points. It registers no middleware, no exporters, no health checks and no HTTP handlers, and it takes no dependency on ASP.NET Core — so it loads from web apps, workers, console apps and Blazor WebAssembly alike.

Install

dotnet add package Cloudstrap.Core

Use it

From a host — AddCloudstrapCore()

using Cloudstrap.Core;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddCloudstrapCore();

This binds the Cloudstrap section and every subsection, and validates all of them at startup. After the call, IOptions<T> resolves for CloudstrapOptions and for each section type — ApplicationOptions, LoggingOptions, OpenTelemetryOptions, CorrelationOptions, HealthChecksOptions:

public sealed class OrderService(IOptions<ApplicationOptions> application)
{
    private readonly ApplicationOptions _application = application.Value;
}

Invalid configuration fails host startup with the framework's OptionsValidationException, naming the offending settings. Binding reads the IConfiguration in the container, which the standard host builders register for you.

Before the host exists — GetCloudstrapOptions()

Bootstrap logging and key-vault configuration run before dependency injection. For those, bind eagerly:

using Cloudstrap.Core;

CloudstrapOptions options = builder.Configuration.GetCloudstrapOptions();

It validates before returning, and throws ConfigurationValidationException when the Cloudstrap section is missing or any rule fails. The message lists every failure, and Failures exposes them individually:

The 'Cloudstrap' configuration section is invalid.
Application:SystemName: The ApplicationOptions.SystemName field is required.
Logging:File:Path is required when File:Enabled is true.
OpenTelemetry:Endpoint is required when Mode is Otlp.
HttpClients:CatalogApi:BaseAddress must be an absolute URI.

Both entry points apply exactly the same rules — one validator implementation, two doors.

Want a tolerant read instead? Bind without validating:

CloudstrapOptions? options = configuration
    .GetSection(CloudstrapOptions.SectionName)
    .Get<CloudstrapOptions>();

Overriding values in code

There is deliberately no configure callback on AddCloudstrapCore(). Layer overrides with the standard options idiom, after the call:

builder.Services.AddCloudstrapCore();
builder.Services.PostConfigure<ApplicationOptions>(options => options.PathBase = "/orders");

Configuration

{
  "Cloudstrap": {
    "Application": {
      "SystemName": "Contoso",          // required
      "SubsystemName": "Orders",        // required
      "SubsystemType": "Api",           // required
      "PathBase": "/orders",
      "EnvironmentTier": "acceptance"
    },
    "Logging": {
      "Level": "Information",
      "LevelOverrides": { "Microsoft.AspNetCore": "Warning" },
      "EnrichProperties": { "Team": "Fulfilment" },
      "Console": { "Enabled": true },
      "File": { "Enabled": false }
    },
    "OpenTelemetry": {
      "Mode": "Otlp",                   // Disabled | Console | Otlp | AzureMonitor
      "Endpoint": "https://collector.example.com/",
      "Headers": { "X-Api-Key": "..." }
    },
    "Correlation": {
      "HeaderName": "X-Correlation-ID"
    },
    "HealthChecks": {
      "LivenessPath": "/healthz",
      "ReadinessPath": "/ready"
    },
    "HttpClients": {
      "CatalogApi": {
        "BaseAddress": "https://catalog.example.com/",
        "Timeout": "00:00:10",
        "AddClientAccessToken": true,
        "TokenRequestParameters": { "Scope": "catalog.read" }
      }
    }
  }
}

Defaults

⚠️ Collections append, they do not replace. The configuration binder populates pre-initialized collections in place, so values you configure for Correlation:Request:HealthEndpoints are added to the ["/healthz", "/ready"] defaults rather than replacing them. The same holds for every other collection and dictionary in this model — though only HealthEndpoints ships with non-empty defaults.

Validation rules

Mode = AzureMonitor requires nothing extra here; exporter settings belong to the Azure Monitor package.

Conventions

Every convention has an override.

License

MIT