> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET SDK - ASP.NET Core IConfiguration

> Plug Westyx Nexus into ASP.NET Core's configuration pipeline with IOptions and live reload support.

The .NET SDK ships a built-in `IConfigurationSource` / `IConfigurationProvider` implementation. With a single `AddWestyx(...)` call, all Nexus config values are exposed through `IConfiguration` — so you can bind them to `IOptions<T>` classes, read them via `configuration["key"]`, and receive live `IOptionsMonitor<T>` updates when a value changes in the console.

## Basic setup

```csharp theme={null}
var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddWestyx(new NexusConfig
{
    BaseUrl = "https://<slug>.westyx.dev",
    ApiKey  = Environment.GetEnvironmentVariable("NEXUS_API_KEY")!,
});

var app = builder.Build();
app.Run();
```

`AddWestyx` performs a **blocking initial sync** inside `Build()` — the same pattern used by Azure App Configuration and other standard providers. All Nexus config values are available from the moment `builder.Build()` returns.

The SSE live-update stream starts automatically (`enableStream: true` is the default). Turn it off if you prefer TTL-only polling:

```csharp theme={null}
builder.Configuration.AddWestyx(config, enableStream: false);
```

## Binding to IOptions\<T>

After calling `AddWestyx`, bind Nexus configs to a strongly-typed class the same way you would bind any other configuration section:

```csharp theme={null}
// Nexus config keys use dot notation: "database.host", "database.port"
// These map to IConfiguration keys of the same name.
builder.Services.Configure<DatabaseSettings>(builder.Configuration.GetSection("database"));
```

```csharp theme={null}
public sealed class DatabaseSettings
{
    public string Host { get; set; } = "";
    public int    Port { get; set; } = 5432;
}
```

Inject `IOptions<DatabaseSettings>` where you need it:

```csharp theme={null}
public sealed class ProductRepository(IOptions<DatabaseSettings> db)
{
    public async Task<Product[]> GetAllAsync()
    {
        // db.Value.Host => "db.internal"
        // db.Value.Port => 5432
    }
}
```

## Live reload with IOptionsMonitor\<T>

When the SSE stream is running, the configuration provider calls `IConfiguration.Reload()` automatically after every sync that returns new data. This means `IOptionsMonitor<T>` receives change notifications within milliseconds of a value being updated in the Nexus console — **without a restart**.

```csharp theme={null}
// Use IOptionsMonitor instead of IOptions to get live updates.
builder.Services.Configure<FeatureSettings>(builder.Configuration.GetSection("feature"));
```

```csharp theme={null}
public sealed class FeatureService(IOptionsMonitor<FeatureSettings> features)
{
    public bool IsNewCheckoutEnabled =>
        features.CurrentValue.NewCheckout;

    public void RegisterChangeCallback()
    {
        features.OnChange(settings =>
        {
            // Called automatically when Nexus pushes an update.
            Console.WriteLine($"feature.new_checkout changed to {settings.NewCheckout}");
        });
    }
}
```

<Info>
  Live reload requires `ConnectStream()` to be active. `AddWestyx(config)` starts the stream automatically. If you use the pre-created client overload, call `client.ConnectStream()` yourself before registering the source.
</Info>

## Pre-created client (WIF, advanced lifetime)

If you need WIF authentication or want to manage the client lifetime yourself, pass an existing `NexusClient` to the overload:

```csharp theme={null}
var client = await NexusClient.CreateAsync(new NexusConfig
{
    BaseUrl = "https://<slug>.westyx.dev",
    Wif     = new WIFConfig { Enabled = true, Provider = WIFProvider.Kubernetes },
});
client.ConnectStream();

// Register as singleton so DI disposes it on shutdown.
builder.Services.AddSingleton(client);

// Wire into IConfiguration.
builder.Configuration.AddWestyx(client);
```

With this overload, **you are responsible** for starting the stream and disposing the client. The `builder.Services.AddSingleton(client)` registration ensures the host shuts the client down cleanly.

## Reading configs directly from IConfiguration

You can also read Nexus config values directly without binding to a class:

```csharp theme={null}
var host    = app.Configuration["database.host"];  // "db.internal"
var timeout = app.Configuration.GetValue<int>("api.timeout_ms");  // 3000
var debug   = app.Configuration.GetValue<bool>("app.debug");      // true
```

<Note>
  Nexus config keys use dot notation (`database.host`). IConfiguration treats dots as part of the key name, not as path separators — so `configuration["database.host"]` and `configuration.GetSection("database")["host"]` are different lookups. Use `GetSection("database")["host"]` only if your key names match section-style navigation.
</Note>

## Value type serialization

Nexus config values are JSON. The provider serializes them to strings for IConfiguration:

| Nexus JSON value  | IConfiguration string        |
| ----------------- | ---------------------------- |
| `"hello"`         | `hello`                      |
| `42`              | `42`                         |
| `3.14`            | `3.14`                       |
| `true`            | `True`                       |
| `false`           | `False`                      |
| `{"key":"value"}` | `{"key":"value"}` (raw JSON) |
| `null`            | *(key absent)*               |

Standard binding (`IOptions<T>`) handles strings, numbers, and booleans natively. JSON object values must be parsed manually if bound to a property.

## Combining with other configuration sources

`AddWestyx` stacks with the other sources in the builder. The last source wins for duplicate keys — so to let local environment variables override Nexus values (useful during development), add Nexus before environment variables:

```csharp theme={null}
builder.Configuration
    .AddWestyx(nexusConfig)          // Nexus loaded first
    .AddEnvironmentVariables();       // env vars override (last wins)
```

Or add it after to give Nexus higher priority than `appsettings.json` but lower than environment variables:

```csharp theme={null}
// Default ASP.NET Core order: appsettings → appsettings.{env} → env vars
// Insert Nexus after appsettings, before env vars:
builder.Configuration.Sources.Insert(
    builder.Configuration.Sources.Count - 1,
    new NexusConfigurationSource(nexusConfig));
```