Interface IOptionsRegistry

Namespace

Acuit.Pinpoint.Workstation.Configuration

Assembly

Acuit.Pinpoint.Workstation.Abstractions.dll

The options registry.

public interface IOptionsRegistry

Remarks

The options registry service provides a way to bind key/value configuration settings to options objects, similar to the options pattern in .NET (which is fully supported in Acuit Pinpoint Workstation), but enhanced to support common usage scenarios in Acuit Pinpoint Workstation:

• Automatic validation via data annotation attributes and/or IValidatableObject.
• Automatic reporting of options binding and validation problems via a health check.
• Injection of dependencies via the options class constructor.
• Asynchronous initialization and/or validation.

Options object types:

• Must be a nullable reference type.
• Must provide a single public constructor, with optional parameters for injectable dependencies (e.g., which can be any dependencies provided by Acuit Pinpoint Workstation or by any loaded plug-ins). This constructor should not throw any exceptions.
• Should provide public settable properties for any configurable settings, which will be set via the options binder against the applicable configurable section, when appropriate. These properties will be set once, immediately after constructing the options instance. If any configuration settings change after the options instance is created, a new options instance will be created, as needed.
• Should not implement IDisposable, as the options registry will never dispose of options instances.
• Should use data annotation attributes on the properties or class to provide validation rules. Any validation mechanisms supported by RecursiveValidator can be used. If there are any validation errors, a health check problem will be raised. This validation occurs only once, after the properties have been initialized from the configuration settings.
• Can implement IInitializableOptions to perform additional options initialization and/or validation.

Methods

GetOptions<TOptions>(string?)

Gets an accessor for an options type.

IOptionsAccessor<TOptions> GetOptions<TOptions>(string? name = null) where TOptions : class

Parameters

name string

An optional name to identify the options.

Returns

IOptionsAccessor<TOptions>

An IOptionsAccessor<TOptions> that can be used to access the options.

Type Parameters

TOptions

The options type.

Remarks

This will always succeed, even if the matching options haven't yet been registered, allowing this to get called before RegisterOptions<TOptions>(string, string?).

Exceptions

InvalidOperationException

This must be called from the main application dispatcher thread.

RegisterOptions<TOptions>(string, string?)

Registers an options type's source configuration section.

IOptionsAccessor<TOptions> RegisterOptions<TOptions>(string configurationSectionKey, string? name = null) where TOptions : class

Parameters

configurationSectionKey string

The key of the configuration section to use for the options.

name string

An optional name to identify these options, which can be used when calling GetOptions<TOptions>(string?) to retrieve a specific set of options when multiple options of a particular type have been registered.

Returns

IOptionsAccessor<TOptions>

An IOptionsAccessor<TOptions> that can be used to access the options.

Type Parameters

TOptions

The options type. See the remarks for IOptionsRegistry for more details.

Exceptions

ArgumentNullException

configurationSectionKey is null.

InvalidOperationException

A registration already exists for the same TOptions and name.

InvalidOperationException

This must be called from the main application dispatcher thread.