Table of Contents

Class OptionsProvider<TOptions>

Namespace
Acuit.Pinpoint.Workstation.Configuration
Assembly
Acuit.Pinpoint.Workstation.Interfaces.dll

Provides a standard base implementation for IOptionsProvider<TOptions> that validates options and provides a health check for the options.

[Obsolete("This is deprecated and will be removed in a future version; Acuit.Pinpoint.Workstation.Configuration.IOptionsRegistry should be used instead. Note that IOptionsRegistry.RegisterOptions<TOptions> does NOT schedule initial loading from configuration settings to occur asynchronously via IApplicationDispatcher.")]
public class OptionsProvider<TOptions> : IOptionsProvider<TOptions>, IHealthCheck, IDisposable where TOptions : class, new()

Type Parameters

TOptions

The options instance type.

Inheritance
OptionsProvider<TOptions>
Implements
Inherited Members

Remarks

The TOptions class can use data annotation attributes to easily provide validation rules. Any validation mechanisms supported by RecursiveValidator can be used. If there are any validation errors for the options values, a health check problem will be raised. The health check name will be similar to "Config:Section options", where "Config:Section" is the configuration section key provided to the constructor.

Changes to configuration settings (either due to retrieving them from Acuit Pinpoint Server during startup, or due to changes to local settings.json files while running) are handled automatically, providing notifications when they are ready via OptionsChanged and IsReadyChanged. The following sequence occurs at startup, and then subsequently whenever configuration settings change (asynchronously, from the main application dispatcher/user interface thread):

  1. Bind the latest configuration settings to a new instance of TOptions. If an error occurs (e.g., due to an error binding a setting value to an option property) or if there are no settings to bind, start with a default instance of TOptions (i.e., from its default constructor).
  2. If the previous step succeeded, validate the options using RecursiveValidator.
  3. Allow derived classes to process options via PrepareUpdatedOptionsAsync(TOptions, IOptionsLoader<TOptions>). Derived classes can do things like retrieve files referenced by options from Acuit Pinpoint Server, or calculate derived option values. Note that this step will occur even if any errors occurred in the previous steps.
  4. If any error(s) occurred in the previous steps, report the first one that occurred via the health check.
  5. Update Options.
  6. Update IsReady, if appropriate.
  7. Trigger the pending change token (retrieved via GetOptionsChangedToken()).
  8. Raise OptionsChanged.
  9. Raise IsReadyChanged, if appropriate.

Typically, a plug-in will supply a class derived from this class that is exported as IOptionsProvider<TOptions> which can be imported elsewhere in the plug-in implementation. Virtual methods can be overridden as required to retrieve files from the server or derive other options values.

Upon initial construction of this object, Options will be a default instance of type TOptions. Initial loading from configuration settings will be scheduled to occur asynchronously via the IApplicationDispatcher provided to the constructor. This is to allow the constructor of a type derived from this class to execute before the derived class's PrepareUpdatedOptionsAsync(TOptions, IOptionsLoader<TOptions>) method is called.

Constructors

OptionsProvider(string, IApplicationDispatcher, IErrorHandler, IHealthCheckService, IWorkstationService)

Initializes a new instance of the OptionsProvider<TOptions> class.

public OptionsProvider(string configurationSectionKey, IApplicationDispatcher applicationDispatcher, IErrorHandler errorHandler, IHealthCheckService healthCheckService, IWorkstationService workstationService)

Parameters

configurationSectionKey string

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

applicationDispatcher IApplicationDispatcher

The IApplicationDispatcher service.

errorHandler IErrorHandler

The error handler that will be used to handle errors upon asynchronous task faults.

healthCheckService IHealthCheckService

The IHealthCheckService service.

workstationService IWorkstationService

The IWorkstationService service.

Exceptions

ArgumentNullException

configurationSectionKey is null.

ArgumentNullException

applicationDispatcher is null.

ArgumentNullException

errorHandler is null.

ArgumentNullException

healthCheckService is null.

ArgumentNullException

workstationService is null.

OptionsProvider(string, IApplicationDispatcher, IHealthCheckService, IWorkstationService)

Initializes a new instance of the OptionsProvider<TOptions> class.

[Obsolete("This is deprecated and will be removed in a future version; OptionsProvider(string,IApplicationDispatcher,IErrorHandler,IHealthCheckService,IWorkstationService) should be used instead.")]
public OptionsProvider(string configurationSectionKey, IApplicationDispatcher applicationDispatcher, IHealthCheckService healthCheckService, IWorkstationService workstationService)

Parameters

configurationSectionKey string

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

applicationDispatcher IApplicationDispatcher

The IApplicationDispatcher service.

healthCheckService IHealthCheckService

The IHealthCheckService service.

workstationService IWorkstationService

The IWorkstationService service.

Exceptions

ArgumentNullException

configurationSectionKey is null.

ArgumentNullException

applicationDispatcher is null.

ArgumentNullException

healthCheckService is null.

ArgumentNullException

workstationService is null.

Properties

IsReady

Gets whether Options reflects all settings (i.e., from Acuit Pinpoint Server).

public bool IsReady { get; }

Property Value

bool

Remarks

This will initially be false, and then will change to true once and only once after all settings have been loaded (i.e, the station has started).

Clients that are costly to initialize or that can only be initialized once should wait until this is true before initializing.

Options

Gets the options.

public TOptions Options { get; }

Property Value

TOptions

Remarks

This will never be null. Before options have been loaded, or when there is an error binding the configuration setting values to the TOptions object, this will be set to a default set of options (i.e., an instance of TOptions created using its default constructor).

These options may be invalid (i.e., they fail data annotations validation). Implementations or clients can validate options via TryValidateObject(object, ICollection<ValidationResult>) if desired.

Methods

CheckHealthAsync(HealthCheckRegistration, CancellationToken)

Runs the health check, returning the status of the component being checked.

public Task<HealthCheckResult> CheckHealthAsync(HealthCheckRegistration registration, CancellationToken cancellationToken = default)

Parameters

registration HealthCheckRegistration

The health check registration associated with the current execution.

cancellationToken CancellationToken

A CancellationToken that can be used to cancel the health check.

Returns

Task<HealthCheckResult>

A Task<TResult> that completes when the health check has finished, yielding the status of the component being checked.

Dispose()

Closes and releases all resources used by the object.

public void Dispose()

Dispose(bool)

Closes and releases all resources used by the OptionsProvider<TOptions>.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true when this is in response to a call to Dispose().

Remarks

Derived classes should override this when they have any resources that should be disposed.

GetOptionsChangedToken()

Gets a IChangeToken that can be used to listen when options change.

public IChangeToken GetOptionsChangedToken()

Returns

IChangeToken

A IChangeToken.

Remarks

This is useful for clients that perform asynchronous work in response to options changes.

PrepareUpdatedOptionsAsync(TOptions, IOptionsLoader<TOptions>)

Updates derived options.

protected virtual Task PrepareUpdatedOptionsAsync(TOptions options, IOptionsLoader<TOptions> optionsLoader)

Parameters

options TOptions

The options instance.

optionsLoader IOptionsLoader<TOptions>

The options loader, which provides services for recording health problems or retrieving files from Acuit Pinpoint Server.

Returns

Task

Remarks

Derived classes should override this method to finish preparing the options for use, doing things like:

  • Retrieving files from Acuit Pinpoint Server.
  • Calculating derived options values.

Any configuration problems that occur within overrides of this method should be handled by calling RecordHealthCheckProblem(HealthCheckResult) of optionsLoader. Any exception thrown from an overriden method will result in an unhandled application exception.

This will be called even if there was a problem binding or validating the options from the configuration settings. The HealthCheckResult property of optionsLoader can be checked to determine whether there were any problems.

When updating any options, the options instance should be updated, not the Options instance, which reflects the previous options settings.

The default implementation currently does nothing, but overridden methods should still call the base method as good practice.

This will be called from the main application dispatcher/user interface thread.

Events

IsReadyChanged

Occurs when IsReady changes to true.

public event EventHandler IsReadyChanged

Event Type

EventHandler

Remarks

This will be raised once, after the station has started, ensuring settings from Acuit Pinpoint Server have been retrieved.

This event will always be raised on the main application dispatcher (i.e., user interface) thread.

OptionsChanged

Occurs when Options changes.

public event EventHandler OptionsChanged

Event Type

EventHandler

Remarks

This event will always be raised on the main application dispatcher (i.e., user interface) thread.