OnTheFlySettings 3.1.0

OnTheFlySettings

Packages	Version	Downloads
OnTheFlySettings
OnTheFlySettings.Client
OnTheFlySettings.AzureKeyVault.Client
OnTheFlySettings.AWSSecretManager.Client

Supports .NET 6/7/8/9/10.

This project is a AspNetCore library that provides a way to update API/App settings on-the-fly.

Zero downtime! At runtime! No need to restart your API/App!

You can keep your settings in appsettings.json or as secrets in Azure Key Vault, AWS Secret Manager.

There are .NET clients provided to get your secrets and update the settings in your API/App.

It supports various settings sources.

Demo application is available here.

Table of Contents

• Plugging in the framework
• Plugging in the Azure framework
• Plugging in the AWS framework
• Usage in your API/App
  • Accessing Current Settings
    • Using IOptionsSnapshot<T>
    • Using IOnTheFlySettings<TSettings>
  • Events
  • Map
• Endpoints - read/update settings on-the-fly

Plugging in the framework

You may keep your settings in your application's appsettings.json.

Create settings section

Create a section in your appsettings.json for the settings that you want to update on-the-fly:

{
  "MyHealthCheckBasicSettings": {
    "HealthCheckIntervalInMinutes": 15,
    "HealthCheckIntervalCronExpression": "* * * * *",
    "HealthCheckServerHubUrl": "https://localhost:5001/livehealthcheckshub",
    "PublishOnlyWhenNotHealthy": false,
    "AddHealthCheckMiddleware": false
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Create settings class

Create a settings class called MyHealthCheckBasicSettings (for eg.) in your application:

public class MyHealthCheckBasicSettings
{
    public int HealthCheckIntervalInMinutes { get; set; }
    public string HealthCheckIntervalCronExpression { get; set; }
    public string HealthCheckServerHubUrl { get; set; }
    public bool PublishOnlyWhenNotHealthy { get; set; }
    public bool AddHealthCheckMiddleware { get; set; }
}

Configuring the library

Then you can configure the library in your Startup.cs or Program.cs file.

Bind the section to the settings class & add to OnTheFlySettings framework:

using OnTheFlySettings;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
       .SetBasePath(Directory.GetCurrentDirectory())
       .AddJsonFile("appsettings.json", false, true);

var appBasicSettings = builder.Configuration.GetSection("MyHealthCheckBasicSettings")
                                            .Get<MyHealthCheckBasicSettings>();

if (appBasicSettings == null)
    throw new ApplicationException("Settings not found.");

// Add the settings to the OnTheFlySettings framework
builder.Services.AddOnTheFlySettings(appBasicSettings);

Library provides Minimal API endpoints for reading and updating settings. Read more.

Add the endpoints to your application:

app.MapGetOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.							

app.MapPutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.
							

Thats it!

Table of Contents

Plugging in the Azure framework

You may keep your settings as secrets in the Azure Key Vault.

The Key Vault name can be anything you want.

In that case, you can do as shown below.

Create settings class

Create a settings class called MyHealthCheckBasicSettings (for eg.) in your application:

public class MyHealthCheckBasicSettings
{
    public int HealthCheckIntervalInMinutes { get; set; }
    public string HealthCheckIntervalCronExpression { get; set; }
    public string HealthCheckServerHubUrl { get; set; }
    public bool PublishOnlyWhenNotHealthy { get; set; }
    public bool AddHealthCheckMiddleware { get; set; }
}

Configuring the library

Then you can configure the library in your Startup.cs or Program.cs file.

Fetch the settings from Azure Key Vault & add to OnTheFlySettings framework:

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using OnTheFlySettings;

var builder = WebApplication.CreateBuilder(args);

string keyVaultName = "ontheflysettings";
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var credential = new ClientSecretCredential("<<your tenantId here>>",
                                            "<<your clientId here>>",
                                            "<<your clientSecret here>>");

var client = new SecretClient(new Uri(kvUri), credential);

var appBasicSettings = new MyHealthCheckBasicSettings
{
    HealthCheckIntervalInMinutes = int.Parse((await client.GetSecretAsync("HealthCheckIntervalInMinutes")).Value.Value),
    HealthCheckIntervalCronExpression = (await client.GetSecretAsync("HealthCheckIntervalCronExpression")).Value.Value,
    HealthCheckServerHubUrl = (await client.GetSecretAsync("HealthCheckServerHubUrl")).Value.Value,
    PublishOnlyWhenNotHealthy = bool.Parse((await client.GetSecretAsync("PublishOnlyWhenNotHealthy")).Value.Value),
    AddHealthCheckMiddleware = bool.Parse((await client.GetSecretAsync("AddHealthCheckMiddleware")).Value.Value)
};

// Add the settings to the OnTheFlySettings framework
builder.Services.AddOnTheFlySettings(appBasicSettings);

Library provides Minimal API endpoints for reading and updating settings. Read more.

Add the endpoints to your application:

app.MapGetOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapPutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.
							

app.MapAzurePutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

Thats it!

Table of Contents

Plugging in the AWS framework

You may keep your settings as secrets in the AWS Secret Manager.

The Secret Id can be anything you want.

In that case, you can do as shown below.

Create settings class

Create a settings class called MyHealthCheckBasicSettings (for eg.) in your application:

public class MyHealthCheckBasicSettings
{
    public int HealthCheckIntervalInMinutes { get; set; }
    public string HealthCheckIntervalCronExpression { get; set; }
    public string HealthCheckServerHubUrl { get; set; }
    public bool PublishOnlyWhenNotHealthy { get; set; }
    public bool AddHealthCheckMiddleware { get; set; }
}

Configuring the library

Then you can configure the library in your Startup.cs or Program.cs file.

Fetch the settings from AWS Secret Manager & add to OnTheFlySettings framework:

using Amazon.Runtime;
using Amazon.SecretsManager;
using Amazon.SecretsManager.Model;
using OnTheFlySettings;

var builder = WebApplication.CreateBuilder(args);

var credentials = new BasicAWSCredentials("<<Your access key id here>>", "<<Your secret access key here>>");
var client = new AmazonSecretsManagerClient(credentials, Amazon.RegionEndpoint.APSoutheast2); // RegionEndpoint as per your regiom

var secretRequest = new GetSecretValueRequest
{
    SecretId = "MyHealthCheckBasicSettings", // Your secret id here
    VersionStage = "AWSCURRENT"
};

var secretResponse = await client.GetSecretValueAsync(secretRequest);

var appBasicSettingsDictionary = JsonSerializer.Deserialize<IDictionary<string, string>>(secretResponse.SecretString);

if (appBasicSettingsDictionary == null)
    throw new ApplicationException("Settings not found");

var appBasicSettings = new MyHealthCheckBasicSettings
{
    HealthCheckIntervalInMinutes = int.Parse(appBasicSettingsDictionary["HealthCheckIntervalInMinutes"]),
    HealthCheckIntervalCronExpression = appBasicSettingsDictionary["HealthCheckIntervalCronExpression"],
    HealthCheckServerHubUrl = appBasicSettingsDictionary["HealthCheckServerHubUrl"],
    PublishOnlyWhenNotHealthy = bool.Parse(appBasicSettingsDictionary["PublishOnlyWhenNotHealthy"]),
    AddHealthCheckMiddleware = bool.Parse(appBasicSettingsDictionary["AddHealthCheckMiddleware"])
};

// Add the settings to the OnTheFlySettings framework
builder.Services.AddOnTheFlySettings(appBasicSettings);

Library provides Minimal API endpoints for reading and updating settings. Read more.

Add the endpoints to your application:

app.MapGetOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapPutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapAWSPutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

Thats it!

Table of Contents

Usage in your API/App

Accessing Current Settings

Using IOptionsSnapshot<T>

The library supports AspNetCore's IOptionsSnapshot<T> for accessing the current settings in your API/App.

private readonly MyHealthCheckBasicSettings _basicSettings;

// Constructor
public MyService(
                    IOptionsSnapshot<MyHealthCheckBasicSettings> settings
                )
{            
    _basicSettings = settings.Value;
}

Table of Contents

Using IOnTheFlySettings<TSettings>

The library provides a IOnTheFlySettings<TSettings> interface that you use in your API/App.

The interface has Current & Old properties to access the current & previous settings.

Using dependency injection

You can also use the interface to access the current settings at any time:

var basicSettings = _serviceProvider.GetRequiredService<IOnTheFlySettings<MyHealthCheckBasicSettings>>().Current;

or

via constructor injection in your class:

private readonly MyHealthCheckBasicSettings _basicSettings;

// Constructor
public MyService(
                    IOnTheFlySettings<MyHealthCheckBasicSettings> settingsHolder
                )
{            
    _basicSettings = settingsHolder.Current;
}

Using global variable

Create a static Globals class in your application.

public static class Globals
{
    public static MyHealthCheckBasicSettings? BasicSettings { get; set; }
}

Then, subscribe to OnSettingsChanged event in your Program.cs or Startup.cs.

Update the Globals property in the event handler.

var settingsHolder = app.Services.GetRequiredService<IOnTheFlySettings<MyHealthCheckBasicSettings>>();

settingsHolder.OnSettingsChanged += async (oldSettings, newSettings) =>
{
    lock(_lockObj)
    {
        Globals.BasicSettings = newSettings;
    }
};

Use Globals.BasicSettings in your code.

Table of Contents

Events

The interface has an event OnSettingsChanged.

You can subscribe to the event in your own class, for example in a service class.

Just inject the IOnTheFlySettings<TSettings> interface into your class and subscribe to the event:

private readonly IOnTheFlySettings<MyHealthCheckBasicSettings> _settingsHolder;

// Constructor
public MyService(
                    IOnTheFlySettings<MyHealthCheckBasicSettings> settingsHolder
                )
{            
    _settingsHolder = settingsHolder;
    _settingsHolder.OnSettingsChanged += SettingsHolder_OnSettingsChanged;
}

private async Task SettingsHolder_OnSettingsChanged(MyHealthCheckBasicSettings? oldSettings, MyHealthCheckBasicSettings newSettings)
{
    // Handle the settings change event here
}

or

you can also subscribe to the event in your Startup.cs or Program.cs file:

var settingsHolder = app.Services.GetRequiredService<IOnTheFlySettings<MyHealthCheckBasicSettings>>();

settingsHolder.OnSettingsChanged += async (oldSettings, newSettings) =>
{
    // Handle the settings change event here
};

Table of Contents

Map

If you want to have different names for your settings than the property names in your class,

you can use the map overload to map your settings to properties in you class.

// Add the settings to the OnTheFlySettings framework
builder.Services.AddOnTheFlySettings(appBasicSettings, Map);


static void Map (IDictionary<string, string> dictionary, MyHealthCheckBasicSettings settings)
{
    settings.HealthCheckIntervalInMinutes = int.Parse(dictionary["intervalInMinutes"]);
    settings.HealthCheckIntervalCronExpression = dictionary["intervalCronExpression"];
    settings.HealthCheckServerHubUrl = dictionary["serverHubUrl"];
    settings.PublishOnlyWhenNotHealthy = bool.Parse(dictionary["onlyWhenNotHealthy"]);
    settings.AddHealthCheckMiddleware = bool.Parse(dictionary["addMiddleware"]);
}

Table of Contents

Endpoints - read/update settings on-the-fly

Library provides Minimal API endpoints for managing settings, including reading, and updating settings.

You can secure these endpoints using authentication and authorization mechanisms provided by ASP.NET Core.

To add the endpoints to your application, you can use the following code in your Startup.cs or Program.cs file:

app.MapGetOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapPutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapAzurePutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapAWSPutReplaceOnTheFlySettings()
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

Default routes to the endpoints are:

• GET /settings

• PUT /settings/replace

• PUT /settings/azure/replace

• PUT /settings/aws/replace

but you can customize the routes by providing your own route templates:

app.MapGetOnTheFlySettings("/my-custom-route")
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapPutReplaceOnTheFlySettings("/my-custom-route/replace")
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapAzurePutReplaceOnTheFlySettings("/my-custom-route/azure/replace")
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

app.MapAWSPutReplaceOnTheFlySettings("/my-custom-route/aws/replace")
   .RequireAuthorization(); // Provide your own authorization policy here
                            // or remove this line to allow anonymous access.

Get settings

Replace settings

When using the Azure/AWS PUT endpoint, all setting values must be strings.

These endpoints are meant to automate fetching and updating settings from Azure Key Vault/AWS Secret Manager which store string values.

Table of Contents