Occasus.JSONRepository
8.1.7
Prefix Reserved
See the version list below for details.
dotnet add package Occasus.JSONRepository --version 8.1.7
NuGet\Install-Package Occasus.JSONRepository -Version 8.1.7
<PackageReference Include="Occasus.JSONRepository" Version="8.1.7" />
paket add Occasus.JSONRepository --version 8.1.7
#r "nuget: Occasus.JSONRepository, 8.1.7"
// Install Occasus.JSONRepository as a Cake Addin #addin nuget:?package=Occasus.JSONRepository&version=8.1.7 // Install Occasus.JSONRepository as a Cake Tool #tool nuget:?package=Occasus.JSONRepository&version=8.1.7
Occasus
.net core IOptions manager and UI
Breaking changes
- Going from 7.0.x to 8.0.x requires .net 8
- Going to 8.1.x will change the encryption method, settings will be scrambled. Copy the settings out to clipboard/file and delete the encrypted settings from storage before upgrading.
What is it?
At it's core Occasus is an easy way to move .Net Options from the appSettings.json file to another storage repository.
It also has an optional UI to allow editing of those values during runtime.
What is supported?
Currently .Net core 8; Console Applications, Blazor Apps and API, and Azure Functions.
If you have a dependancy injected IConfigurationBuilder and IServiceCollection you should be good to go.
How do I get started?
First of all you need to pick one (or more) of the repository packages for Occasus, and possibly a UI package. See more below.
Then you can use them in your configuration:
Start with an IConfigurationBuilder
var builder = WebApplication.CreateBuilder(args);
builder.UseSettingsFrom...(options)
Where the UseSettingsFrom... is an extension from a Occasus repository package
Then add your options to the IServiceCollection
.WithOptions<MyOptionsClass>()
Note: Here the WithOptions is an extension to the repository added to the builder.
You can also refer back to the Configured Option, just like regular Option injecting, where you can use the OptionsBuilder:
.WithOptions<MyOptions>(out var optionsBuilder);
optionsBuilder.Validate(x => x.SomeRequiredValue != null && x.ListOfStrings.Any(), "MyOptions Strings must have some value");
So you can validate on startup here too.
Finally
You can inject the .Net IOptions<MyOptionsClass>
into your application.
private readonly MyOptionsClass myoptions;
public MyService(IOptionsSnapshot<MyOptionsClass> myoptions)
{
this.myoptions = myoptions.Value;
}
You can read more in the link above but if your usinbg IOptionsSnapshot, this is a Scoped access and the value will be retrieved everytime you start a new scope. This means any changes in the UI should be reflected without having to restart the application.
Example
So if you were getting settings from SQL using the Occasus SQLEFRepository and using the Blazor UI package
var builder = WebApplication.CreateBuilder(args);
builder.AddOccasusUI()
.UseOptionsFromSQLEF(settings =>
{
settings.WithSQLConnection(sqlConnBuilder =>
{
sqlConnBuilder.ConnectionString = builder.Configuration["ConnectionStrings:SettingsConnectionString"];
});
})
.WithOptions<ApplicationOptions>()
Where ApplicationOptions
is a class or record for the options from your application.
Occasus.JSONRepository
dotnet add package Occasus.JSONRepository
Install-Package Occasus.JSONRepository
This allows you to use a .json file as a repository for settings, it also allows you to use the appSettings.json file.
Simple usage:
UseOptionsFromJsonFile(string filePath)
builder.UseOptionsFromJsonFile("settings/settings.json")
.WithOptions<ApplicationOptions>();
Advanced JSON Options:
UseOptionsFromJsonFile(string filePath, Action<JsonSourceSettings> jsonSourceSettings)
builder.UseOptionsFromJsonFile("appsettings.json", settings =>
{
settings.JsonWriterOptions((ref JsonWriterOptions options) => options.Indented = true);
settings.JsonNodeOptions((ref JsonNodeOptions options) => options.PropertyNameCaseInsensitive = true);
})
.WithOptions<TestAppSettingsJson>();
JsonSourceSettings
JsonSourceSettings is a class that configures the repository:
- ClearWholeFile - Boolean flag, when writing to the file, start with a clean file, or leave other json Nodes alone. This options is useful during development when your application options may change.
Occasus.JsonRepository uses System.Text.Json and the following actions are passed directly to that:
- JsonDocumentOptions(ActionRef<JsonDocumentOptions> options) - this is a ref for the JsonDocumentOptions configuration action.
- JsonNodeOptions(ActionRef<JsonNodeOptions> options) - this is a ref for the JsonNodeOptions configuration action.
- JsonSerializerOptions(Action<JsonSerializerOptions> options) - this is not a ref but it's an action for the JsonSerializerOptions
- JsonWriterOptions(ActionRef<JsonWriterOptions> options) - this is a ref for the JsonWriterOptions configuration action.
Occasus.SQLRepository & Occasus.SQLEFRepository
Occasus.SQLRepository
dotnet add package Occasus.SQLRepository
Install-Package Occasus.SQLRepository
Occasus.SQLEFRepository
dotnet add package Occasus.SQLEFRepository
Install-Package Occasus.SQLEFRepository
This allows you to use a SQL Server for settings.
Usage example:
builder.AddOccasusUI()
.UseOptionsFromSQL(settings =>
{
settings.EncryptSettings = true;
settings.EncryptionKey = "a password";
settings.WithSQLConnection(sqlConnBuilder =>
{
sqlConnBuilder.ConnectionString = builder.Configuration["ConnectionStrings:SettingsConnectionString"];
sqlConnBuilder.PersistSecurityInfo = true;
});
})
Using EF DbOptions example:
...
.UseOptionsFromSQLEF(settings =>
{
...
settings.WithSQLConnection(sqlConnBuilder =>
{
sqlConnBuilder.ConnectionString = builder.Configuration["ConnectionStrings:SettingsConnectionString"];
}, dbOptions =>
{
dbOptions.EnableRetryOnFailure(3, new(0, 0, 5), null);
});
})
SQLEFSourceSettings
SQLEFSourceSettings is a class that configures the repository:
- ConnectionString - Your typical SQL connection string.
- TableName - (string) What table to use in SQL (Default "Settings")
- KeyColumnName - (string) The Key column name to use (Default "Key")
- ValueColumnName - (string) The Value column name to use (Default "Value")
- EncryptSettings - (bool) Whether or not to encrypt the value using Salted AES (Default false)
- EncryptionKey - (string) The key passed to AES, minimum length is 12 charicters;
SQLEFSourceSettings has a handy WithSQLConnection(Action<SqlConnectionStringBuilder> builder, Action\<SqlServerDbContextOptionsBuilder>? sqlServerDbContextOptionsBuilder)
method
SQLSourceSettings has a handy WithSQLConnection(Action<SqlConnectionStringBuilder> builder)
method
These allow you to build the connection string and the DbContext options fluently, like you would any normal SQL Connection.
System.Data.SqlClient.SqlConnectionStringBuilder
Microsoft.EntityFrameworkCore.Infrastructure.SqlServerDbContextOptionsBuilder
AES is provided by System.Security.Cryptography
BlockBitSize = 128;
KeyBitSize = 256;
SaltBitSize = 64;
Iterations = 10000;
Occasus.BlazorUI
dotnet add package Occasus.BlazorUI
Install-Package Occasus.BlazorUI
The Blazor UI package adds a UI component to the configurable path /occasus
Simple usage:
var builder = WebApplication.CreateBuilder(args);
builder.AddOccasusUI()
var app = builder.Build();
app.UseOccasusUI("mypassword");
Or if you need to move Occasus to another URL you can use:
var app = builder.Build();
app.UseOccasusUI("mypassword", "/other");
Attributes
You can decorate your Options Class with several attributes to determing how the control is shown in the UI.
public record UserDetails
{
[Display(Name = "A User Name"), Required]
public string? User { get; set; }
[Input(InputType.Password), RestartRequired]
public string? Password { get; set; }
}
The 'RestartRequired' attribute is used to tell the UI to display a message whenever the class or the property (depending on where you put the Attribute) is changed, that the application needs restarting for the option to have an effect. Note: Whether or not the option has an effect is down to your application, Occasus will change it real time regardless.
Occasus.FeatureManagement
dotnet add package Occasus.FeatureManagement
Install-Package Occasus.FeatureManagement
FeatureManagement integrates with Microsoft.FeatureManagement.AspNetCore
Usage:
.WithFeatureFlagOptions<FeatureManagement>(builder.Configuration);
In order to add feature flags the method requres the IConfiguration interface. This makes it hard to use with Console Apps and Azure Functions. But the inteded use of Feature Flags is API and UI apps.
WithFeatureFlagOptions
also supports the OptionsBuilder parameter.
Example Feature Flag (This is using the standard .Net feature)
public FeatureManagedService(IFeatureManager featureManager)
{
...
}
public string GetValue(string flag)
{
...
return featureManager.IsEnabledAsync(flag) ? "Yes" : "No";
}
As you can see feature flags are only ever booleans, and as such a feature flag class added to Occasus should just be booleans. However, the FeatureManagement system from Microsoft does support extended information to vary the feature flag by various different inputs. This, in theory should still work with Occasus if you structure your class correctly. It is untested at this time.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Occasus (>= 8.1.7)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
8.1.9 | 238 | 6/4/2024 |
8.1.8 | 91 | 6/4/2024 |
8.1.7 | 91 | 6/4/2024 |
8.1.6 | 102 | 5/14/2024 |
8.1.4 | 99 | 5/14/2024 |
8.1.3 | 117 | 3/11/2024 |
8.1.1 | 91 | 3/11/2024 |
7.0.13 | 91 | 3/11/2024 |
7.0.12 | 99 | 3/11/2024 |
7.0.11 | 112 | 3/11/2024 |
7.0.9 | 109 | 3/9/2024 |
7.0.8 | 120 | 3/9/2024 |
7.0.7 | 283 | 2/22/2024 |
7.0.6 | 236 | 12/8/2023 |
6.0.55 | 177 | 10/19/2023 |
6.0.54 | 135 | 10/19/2023 |
6.0.53 | 143 | 10/19/2023 |
6.0.51 | 142 | 10/18/2023 |
6.0.50 | 264 | 7/20/2023 |
6.0.49 | 320 | 2/10/2023 |
6.0.48 | 329 | 12/19/2022 |
6.0.47 | 304 | 12/19/2022 |
6.0.46 | 306 | 12/19/2022 |
6.0.45 | 318 | 12/15/2022 |
6.0.44 | 325 | 11/23/2022 |
6.0.43 | 349 | 11/23/2022 |
6.0.42 | 322 | 11/23/2022 |
6.0.40 | 328 | 11/22/2022 |
6.0.39 | 336 | 11/21/2022 |
6.0.38 | 312 | 11/21/2022 |
6.0.37 | 335 | 11/21/2022 |
6.0.36 | 342 | 11/17/2022 |
6.0.35 | 359 | 11/15/2022 |
6.0.34 | 335 | 11/15/2022 |
6.0.33 | 359 | 11/15/2022 |
6.0.32 | 374 | 10/28/2022 |
6.0.31 | 371 | 10/27/2022 |
6.0.30 | 376 | 10/27/2022 |
6.0.27 | 420 | 10/21/2022 |
6.0.26 | 431 | 10/16/2022 |
6.0.25 | 401 | 10/16/2022 |
6.0.23 | 405 | 10/16/2022 |
6.0.22 | 397 | 10/16/2022 |
1.0.0 | 416 | 10/15/2022 |