Class OptionsBuilderUpdateableOptionsExtensions

Namespace

Acuit.Pinpoint.Common.Options

Assembly

Acuit.Pinpoint.Common.dll

Extension members for configuring updateable options.

public static class OptionsBuilderUpdateableOptionsExtensions

Inheritance

object

OptionsBuilderUpdateableOptionsExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

BindUpdateableJsonFile<TOptions>(OptionsBuilder<TOptions>, Func<IServiceProvider, string>, JsonSerializerOptions?, Action<TOptions>?)

Registers the services to make a particular type of options updateable, reading initial values from and writing updates to a JSON file.

public static OptionsBuilder<TOptions> BindUpdateableJsonFile<TOptions>(this OptionsBuilder<TOptions> optionsBuilder, Func<IServiceProvider, string> fileNameFactory, JsonSerializerOptions? jsonSerializerOptions = null, Action<TOptions>? configureInitialOptions = null) where TOptions : class

Parameters

optionsBuilder OptionsBuilder<TOptions>

fileNameFactory Func<IServiceProvider, string>

A method delegate that will return the name of the JSON file.

jsonSerializerOptions JsonSerializerOptions

The JSON serializer options to use when serializing and deserializing the options to and from the JSON file, or null to use the default options for General, but with these changes:

• PreferredObjectCreationHandling is set to Populate.
• WriteIndented is set to true.

configureInitialOptions Action<TOptions>

An optional action used to configure the initial options. If provided, it will only be invoked when the JSON file does not initially exist. This can be used to migrate settings from a previous version.

Returns

OptionsBuilder<TOptions>

The OptionsBuilder<TOptions> so that additional calls can be chained.

Type Parameters

TOptions

Remarks

The IOptionsUpdater<TOptions> service should be used to update these options.

The JSON file is not watched for changes. If the file is changed by any method other than the IOptionsUpdater<TOptions> service, the options will not be updated.

Note that any other options configuration registered for TOptions will still be applied as usual. This registers an IConfigureOptions<TOptions> that will update an options instance, populating its members that are specified in the JSON file. The options initialization sequence, which occurs when the options are first initialized as well as every time they are updated, is:

1. A default instance of TOptions is created.
2. Any IConfigureOptions<TOptions>'s registered before this method was called will be invoked to configure the options instance.
3. The JSON file is read, applying settings found in it to the options instance.
4. Any IConfigureOptions<TOptions>'s registered after this method was called will be invoked to configure the options instance.

Updating the options (i.e., via IOptionsUpdater<TOptions>.UpdateValue(string?, TOptions)) only updates the JSON file used in step 3 above; it does not affect any other configuration that may be applied in steps 2 or 4. Thus, typically no other options configurers should be registered for TOptions to avoid unexpected behavior. To perform default initialization when there is no initial JSON file, configureInitialOptions should be used, not a separate registered options configurer.

Exceptions

ArgumentNullException

fileNameFactory is null.

BindUpdateableJsonFile<TOptions>(OptionsBuilder<TOptions>, string, JsonSerializerOptions?, Action<TOptions>?)

Registers the services to make a particular type of options updateable, reading initial values from and writing updates to a JSON file.

public static OptionsBuilder<TOptions> BindUpdateableJsonFile<TOptions>(this OptionsBuilder<TOptions> optionsBuilder, string fileName, JsonSerializerOptions? jsonSerializerOptions = null, Action<TOptions>? configureInitialOptions = null) where TOptions : class

Parameters

optionsBuilder OptionsBuilder<TOptions>

fileName string

The name of the JSON file.

jsonSerializerOptions JsonSerializerOptions

The JSON serializer options to use when serializing and deserializing the options to and from the JSON file, or null to use the default options for General, but with these changes:

• PreferredObjectCreationHandling is set to Populate.
• WriteIndented is set to true.

configureInitialOptions Action<TOptions>

An optional action used to configure the initial options. If provided, it will only be invoked when the JSON file does not initially exist. This can be used to migrate settings from a previous version.

Returns

OptionsBuilder<TOptions>

The OptionsBuilder<TOptions> so that additional calls can be chained.

Type Parameters

TOptions

Remarks

The IOptionsUpdater<TOptions> service should be used to update these options.

The JSON file is not watched for changes. If the file is changed by any method other than the IOptionsUpdater<TOptions> service, the options will not be updated.

Note that any other options configuration registered for TOptions will still be applied as usual. This registers an IConfigureOptions<TOptions> that will update an options instance, populating its members that are specified in the JSON file. The options initialization sequence, which occurs when the options are first initialized as well as every time they are updated, is:

1. A default instance of TOptions is created.
2. Any IConfigureOptions<TOptions>'s registered before this method was called will be invoked to configure the options instance.
3. The JSON file is read, applying settings found in it to the options instance.
4. Any IConfigureOptions<TOptions>'s registered after this method was called will be invoked to configure the options instance.

Updating the options (i.e., via IOptionsUpdater<TOptions>.UpdateValue(string?, TOptions)) only updates the JSON file used in step 3 above; it does not affect any other configuration that may be applied in steps 2 or 4. Thus, typically no other options configurers should be registered for TOptions to avoid unexpected behavior. To perform default initialization when there is no initial JSON file, configureInitialOptions should be used, not a separate registered options configurer.

Exceptions

ArgumentNullException

fileName is null.

MakeUpdateableInMemory<TOptions>(OptionsBuilder<TOptions>)

Registers the services to make a particular type of options updateable, with updates simply kept in memory. Changes are not persisted across restarts.

public static OptionsBuilder<TOptions> MakeUpdateableInMemory<TOptions>(this OptionsBuilder<TOptions> optionsBuilder) where TOptions : class

Parameters

optionsBuilder OptionsBuilder<TOptions>

Returns

OptionsBuilder<TOptions>

The OptionsBuilder<TOptions> so that additional calls can be chained.

Type Parameters

TOptions

Remarks

The IOptionsUpdater<TOptions> service should be used to update these options.

Internally, updated option values are serialized to JSON, kept in memory. The JSON serializer uses the default options for General, but with these changes:

• PreferredObjectCreationHandling is set to Populate.