options library

Provides types for implementing the options pattern for strongly-typed configuration.

This library enables the options pattern inspired by Microsoft.Extensions.Options, allowing applications to bind configuration sections to strongly-typed objects with validation and change notification.

Basic Usage

Register and use options:

services
  ..configure<MyOptions>((options) {
    options.setting1 = 'value1';
    options.setting2 = 42;
  });

final options = provider.getRequiredService<Options<MyOptions>>();
print(options.value.setting1);

Configuration Binding

Bind configuration sections to options:

services.configure<MyOptions>(
  configuration.getSection('MySettings'),
);

Named Options

Register multiple option instances under different names:

services
  ..configure<MyOptions>(
    MyOptions.new,
    (options) => options.option = 'Primary options value',
    name: _primaryOptionsName,
  )
  ..configure<MyOptions>(
    MyOptions.new,
    (options) => options.option = 'Secondary options value',
    name: _secondaryOptionsName,
  )

Resolve them through an OptionsSnapshot:

print('$_primaryOptionsName: ${options.get(_primaryOptionsName)?.option}');
print(
  '$_secondaryOptionsName: '
  '${options.get(_secondaryOptionsName)?.option}',
);

Options Monitoring

React to configuration changes at runtime:

final monitor = provider.getRequiredService<OptionsMonitor<MyOptions>>();
monitor.onChange((opts, name) {
  print('Options changed: $name');
});

Classes

ConfigurationChangeTokenSource<TOptions>
Creates ChangeTokens so that OptionsMonitor gets notified when Configuration changes.
ConfigureNamedOptions<TOptions>
Represents something that configures the TOptions type.
ConfigureOptions<TOptions>
Represents something that configures the TOptions type. Note: These are run before all PostConfigureOptions.
Options<TOptions>
Used to retrieve configured TOptions instances.
OptionsChangeTokenSource<TOptions>
Used to fetch ChangeToken used for tracking options changes.
OptionsFactory<TOptions>
Used to create TOptions instances.
OptionsMonitor<TOptions>
Used for notifications when TOptions instances change.
OptionsMonitorCache<TOptions>
Used by OptionsMonitor to cache TOptions instances.
OptionsSnapshot<TOptions>
Used to access the value of TOptions for the lifetime of a request.
PostConfigureOptions<TOptions>
Represents something that configures the TOptions type.
ValidateOptions<TOptions>
Interface used to validate options.
ValidateOptions0<TOptions>
Implementation of ValidateOptions<TOptions>
ValidateOptions1<TOptions, TDep>
ValidateOptions2<TOptions, TDep1, TDep2>
ValidateOptions3<TOptions, TDep1, TDep2, TDep3>
ValidateOptions4<TOptions, TDep1, TDep2, TDep3, TDep4>
ValidateOptions5<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5>
ValidateOptionsResult
Represents the result of an options validation.

Extensions

OptionsServiceCollectionExtensions on ServiceCollection
Extension methods for adding options services to the DI container.

Typedefs

ValidationCallback0<TOptions> = bool Function(TOptions options)
ValidationCallback1<TOptions, TDep> = bool Function(TOptions options, TDep dependency)
ValidationCallback2<TOptions, TDep1, TDep2> = bool Function(TOptions options, TDep1 dependency1, TDep2 dependency2)
ValidationCallback3<TOptions, TDep1, TDep2, TDep3> = bool Function(TOptions options, TDep1 dependency1, TDep2 dependency2, TDep3 dependency3)
ValidationCallback4<TOptions, TDep1, TDep2, TDep3, TDep4> = bool Function(TOptions options, TDep1 dependency1, TDep2 dependency2, TDep3 dependency3, TDep4 dependency4)
ValidationCallback5<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5> = bool Function(TOptions options, TDep1 dependency1, TDep2 dependency2, TDep3 dependency3, TDep4 dependency4, TDep5 dependency5)