Interface ILocalSettingsService

Namespace

OpenSettings.Services.Interfaces

Assembly

OpenSettings.dll

Provides methods to manage and retrieve local settings in an application.

public interface ILocalSettingsService

Methods

DeleteSettings(string)

Deletes all locally stored settings associated with the specified identifier name. If the identifier name matches the runtime identifier name specified in IdentifierName, the operation is skipped. Additionally, if the identifier has not been fetched, no settings will be removed.

void DeleteSettings(string identifierName)

Parameters

identifierName string

The name of the identifier whose associated local settings are to be deleted.

GetLocalSettingsAsync(IServiceProvider, Guid, ConfigSource, CancellationToken)

Retrieves the local setting based on the specified computed identifier and configuration source. If the setting is not found, an error corresponding to the configSource retrieval is returned. If the operation is successful, the retrieved setting is available in the Data field of the response.

Task<IResponse> GetLocalSettingsAsync(IServiceProvider serviceProvider, Guid computedIdentifier, ConfigSource configSource, CancellationToken cancellationToken = default)

Parameters

serviceProvider IServiceProvider

The service provider used to resolve dependencies required for the operation.

computedIdentifier Guid

A unique identifier used to locate the specific local setting.

configSource ConfigSource

The source of the configuration that determines how the setting is retrieved.

cancellationToken CancellationToken

A token that can be used to cancel the asynchronous operation.

Returns

Task<IResponse>

A task representing the asynchronous operation. The result contains a JSON response with the retrieved local setting or an error message if the setting is not found.

GetSettingAsync(IServiceProvider, Guid, params ConfigSource[])

Retrieves a local setting object by a unique identifier, based on the provided config sources. Returns the default value if not found.

Task<object> GetSettingAsync(IServiceProvider serviceProvider, Guid computedIdentifier, params ConfigSource[] configSources)

Parameters

serviceProvider IServiceProvider

The IServiceProvider used to resolve dependencies.

computedIdentifier Guid

A unique identifier for the setting.

configSources ConfigSource[]

An array of config sources to attempt to fetch the value from, in the given order.

Returns

Task<object>

A task that represents the asynchronous operation, containing the setting object, or the default value if not found.

Remarks

Note: If serviceProvider is resolving from a Singleton, an exception will be thrown if IOptionsSnapshot<TOptions> is used because it is scoped and cannot be resolved from a Singleton instance.

GetSettingAsync(IServiceProvider, Guid, CancellationToken, params ConfigSource[])

Retrieves a local setting object by a unique identifier, based on the provided config sources. Returns the default value if not found.

Task<object> GetSettingAsync(IServiceProvider serviceProvider, Guid computedIdentifier, CancellationToken cancellationToken, params ConfigSource[] configSources)

Parameters

serviceProvider IServiceProvider

The IServiceProvider used to resolve dependencies.

computedIdentifier Guid

A unique identifier for the setting.

cancellationToken CancellationToken

A token used to cancel the operation if requested.

configSources ConfigSource[]

An array of config sources to attempt to fetch the value from, in the given order.

Returns

Task<object>

A task that represents the asynchronous operation, containing the setting object, or the default value if not found.

Remarks

Note: If serviceProvider is resolving from a Singleton, an exception will be thrown if IOptionsSnapshot<TOptions> is used because it is scoped and cannot be resolved from a Singleton instance.

GetSettingAsync<T>(IServiceProvider, params ConfigSource[])

Gets a local setting object of type T or returns the default value if not found. If configuration sources are not provided, the default value of T is returned. Based on the order of config sources, it will attempt to retrieve the value. The config sources are: File, Local, Singleton, Options, OptionsSnapshot, or OptionsMonitor. If the first config source does not contain the value, it will try the second one, and so on.

Task<T> GetSettingAsync<T>(IServiceProvider serviceProvider, params ConfigSource[] configSources)

Parameters

serviceProvider IServiceProvider

The IServiceProvider used to resolve dependencies.

configSources ConfigSource[]

An array of config sources to attempt to fetch the value from, in the given order.

Returns

Task<T>

A task that represents the asynchronous operation, containing the settings object of type T or the default value if not found.

Type Parameters

T

The type of the settings object.

Remarks

Note: If serviceProvider is resolving from a Singleton, an exception will be thrown if IOptionsSnapshot<TOptions> is used because it is scoped and cannot be resolved from a Singleton instance.

GetSettingAsync<T>(IServiceProvider, CancellationToken, params ConfigSource[])

Gets a local setting object of type T or returns the default value if not found. If configuration sources are not provided, the default value of T is returned. Based on the order of config sources, it will attempt to retrieve the value. The config sources are: File, Local, Singleton, Options, OptionsSnapshot, or OptionsMonitor. If the first config source does not contain the value, it will try the second one, and so on.

Task<T> GetSettingAsync<T>(IServiceProvider serviceProvider, CancellationToken cancellationToken, params ConfigSource[] configSources)

Parameters

serviceProvider IServiceProvider

The IServiceProvider used to resolve dependencies.

cancellationToken CancellationToken

A token used to cancel the operation if requested.

configSources ConfigSource[]

An array of config sources to attempt to fetch the value from, in the given order.

Returns

Task<T>

A task that represents the asynchronous operation, containing the settings object of type T or the default value if not found.

Type Parameters

T

The type of the settings object.

Remarks

Note: If serviceProvider is resolving from a Singleton, an exception will be thrown if IOptionsSnapshot<TOptions> is used because it is scoped and cannot be resolved from a Singleton instance.

GetSettingAsync<T>(string, CancellationToken)

Asynchronously retrieves a settings object of type T using the specified identifier name.

Task<T> GetSettingAsync<T>(string identifierName, CancellationToken cancellationToken = default) where T : ISettings

Parameters

identifierName string

The identifier name used to retrieve the settings object. It cannot be null, empty, or whitespace.

cancellationToken CancellationToken

A token used to cancel the asynchronous operation if requested. The default value is None.

Returns

Task<T>

A task representing the asynchronous operation, with a result of type T that implements ISettings.

Type Parameters

T

Exceptions

ArgumentException

Thrown when the identifierName is null, empty, or whitespace.

TaskCanceledException

Thrown if the operation is canceled before completion.

GetSetting<T>()

Gets a local setting object of type T or returns the default value if not found.

T GetSetting<T>() where T : ISettings

Returns

T

The settings object of type T or the default value if not found.

Type Parameters

T

The type of the settings object.

ReloadSettingsAsync(string, CancellationToken)

Attempts to reload all settings based on the specified identifier name.

Task<bool> ReloadSettingsAsync(string identifierName, CancellationToken cancellationToken = default)

Parameters

identifierName string

The identifier name of the settings to reload. It cannot be null, empty, or whitespace.

cancellationToken CancellationToken

A token used to cancel the operation if requested. The default is None.

Returns

Task<bool>

A task representing the asynchronous operation. The task result is true if the reload was successful, otherwise false.

Exceptions

ArgumentException

Thrown when the identifierName is null, empty, or whitespace.

ReloadSettingsAsync(CancellationToken)

Reloads all settings in the current identifier without specifying a name.

Task<bool> ReloadSettingsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token used to cancel the operation if requested. The default is None.

Returns

Task<bool>

A task representing the asynchronous operation. The task result is true if the reload was successful, otherwise false.

Exceptions

ArgumentException

Thrown when the identifier name is null, empty, or whitespace.

SettingDataChangeNotifiedAsync(Guid, CancellationToken)

When a change notification is triggered, this method attempts to fetch the latest value for the specified computedIdentifier based on recent updates.

Task SettingDataChangeNotifiedAsync(Guid computedIdentifier, CancellationToken cancellationToken = default)

Parameters

computedIdentifier Guid

The identifier for the data that was changed and needs to be reloaded.

cancellationToken CancellationToken

A token used to cancel the operation if requested. The default is None.

Returns

Task

A task that represents the asynchronous operation.