Options pattern in ASP.NET Core

Transcription

1 Options pattern in ASP.NET Core By Luke Latham The options pattern uses classes to represent groups of related settings. When configuration settings are isolated by scenario into separate classes, the app adheres to two important software engineering principles: The Interface Segregation Principle (ISP): Scenarios (classes) that depend on configuration settings depend only on the configuration settings that they use. Separation of Concerns: Settings for different parts of the app aren't dependent or coupled to one another. View or download sample code (how to download) This article is easier to follow with the sample app. Prerequisites Add a package reference to the Microsoft.Extensions.Options.ConfigurationExtensions package. Basic options configuration Basic options configuration is demonstrated as Example #1 in the sample app. An options class must be non-abstract with a public parameterless constructor. The following class, MyOptions, has two properties, Option1 and Option2. Setting default values is optional, but the class constructor in the following example sets the default value of Option1. Option2 has a default value set by initializing the property directly (Models/MyOptions.cs): public class MyOptions public MyOptions() // Set default value. Option1 = "value1_from_ctor"; public string Option1 get; set; public int Option2 get; set; = 5; The MyOptions class is added to the service container with Configure<TOptions>(IServiceCollection, IConfiguration) and bound to configuration:

2 // Example #1: Basic options // Register the Configuration instance which MyOptions binds against. services.configure<myoptions>(configuration); The following page model uses constructor dependency injection with IOptions<TOptions> to access the settings (Pages/Index.cshtml.cs): private readonly MyOptions _options; public IndexModel( IOptions<MyOptions> optionsaccessor, IOptions<MyOptionsWithDelegateConfig> optionsaccessorwithdelegateconfig, IOptions<MySubOptions> suboptionsaccessor, IOptionsSnapshot<MyOptions> snapshotoptionsaccessor, IOptionsSnapshot<MyOptions> namedoptionsaccessor) _options = optionsaccessor.value; _optionswithdelegateconfig = optionsaccessorwithdelegateconfig.value; _suboptions = suboptionsaccessor.value; _snapshotoptions = snapshotoptionsaccessor.value; _named_options_1 = namedoptionsaccessor.get("named_options_1"); _named_options_2 = namedoptionsaccessor.get("named_options_2"); // Example #1: Simple options var option1 = _options.option1; var option2 = _options.option2; SimpleOptions = $"option1 = option1, option2 = option2"; The sample's appsettings.json file specifies values for option1 and option2: JSON "option1": "value1_from_json", "option2": -1, "subsection": "suboption1": "subvalue1_from_json", "suboption2": 200, "Logging": "LogLevel": "Default": "Warning", "AllowedHosts": "*" When the app is run, the page model's OnGet method returns a string showing the option class values: HTML option1 = value1_from_json, option2 = -1

3 Note When using a custom ConfigurationBuilder to load options configuration from a settings file, confirm that the base path is set correctly: var configbuilder = new ConfigurationBuilder().SetBasePath(Directory.GetCurrentDirectory()).AddJsonFile("appsettings.json", optional: true); var config = configbuilder.build(); services.configure<myoptions>(config); Explicitly setting the base path isn't required when loading options configuration from the settings file via CreateDefaultBuilder. Configure simple options with a delegate Configuring simple options with a delegate is demonstrated as Example #2 in the sample app. Use a delegate to set options values. The sample app uses the MyOptionsWithDelegateConfig class (Models/MyOptionsWithDelegateConfig.cs): public class MyOptionsWithDelegateConfig public MyOptionsWithDelegateConfig() // Set default value. Option1 = "value1_from_ctor"; public string Option1 get; set; public int Option2 get; set; = 5; In the following code, a second IConfigureOptions<TOptions> service is added to the service container. It uses a delegate to configure the binding with MyOptionsWithDelegateConfig: // Example #2: Options bound and configured by a delegate services.configure<myoptionswithdelegateconfig>(myoptions => myoptions.option1 = "value1_configured_by_delegate"; myoptions.option2 = 500; ); Index.cshtml.cs:

4 private readonly MyOptionsWithDelegateConfig _optionswithdelegateconfig; public IndexModel( IOptions<MyOptions> optionsaccessor, IOptions<MyOptionsWithDelegateConfig> optionsaccessorwithdelegateconfig, IOptions<MySubOptions> suboptionsaccessor, IOptionsSnapshot<MyOptions> snapshotoptionsaccessor, IOptionsSnapshot<MyOptions> namedoptionsaccessor) _options = optionsaccessor.value; _optionswithdelegateconfig = optionsaccessorwithdelegateconfig.value; _suboptions = suboptionsaccessor.value; _snapshotoptions = snapshotoptionsaccessor.value; _named_options_1 = namedoptionsaccessor.get("named_options_1"); _named_options_2 = namedoptionsaccessor.get("named_options_2"); // Example #2: Options configured by delegate var delegate_config_option1 = _optionswithdelegateconfig.option1; var delegate_config_option2 = _optionswithdelegateconfig.option2; SimpleOptionsWithDelegateConfig = $"delegate_option1 = delegate_config_option1, " + $"delegate_option2 = delegate_config_option2"; You can add multiple configuration providers. Configuration providers are available in NuGet packages. They're applied in the order that they're registered. Each call to Configure<TOptions> adds an IConfigureOptions<TOptions> service to the service container. In the preceding example, the values of Option1 and Option2 are both specified in appsettings.json, but the values of Option1 and Option2 are overridden by the configured delegate. When more than one configuration service is enabled, the last configuration source specified wins and sets the configuration value. When the app is run, the page model's OnGet method returns a string showing the option class values: HTML delegate_option1 = value1_configured_by_delgate, delegate_option2 = 500 Suboptions configuration Suboptions configuration is demonstrated as Example #3 in the sample app. Apps should create options classes that pertain to specific scenario groups (classes) in the app. Parts of the app that require configuration values should only have access to the configuration values that they use. When binding options to configuration, each property in the options type is bound to a configuration key of the form property[:sub-property:]. For example, the

5 MyOptions.Option1 property is bound to the key Option1, which is read from the option1 property in appsettings.json. In the following code, a third IConfigureOptions<TOptions> service is added to the service container. It binds MySubOptions to the section subsection of the appsettings.json file: // Example #3: Sub-options // Bind options using a sub-section of the appsettings.json file. services.configure<mysuboptions>(configuration.getsection("subsection")); The GetSection extension method requires the Microsoft.Extensions.Options.ConfigurationExtensions NuGet package. If the app uses the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later), the package is automatically included. The sample's appsettings.json file defines a subsection member with keys for suboption1 and suboption2: JSON "option1": "value1_from_json", "option2": -1, "subsection": "suboption1": "subvalue1_from_json", "suboption2": 200, "Logging": "LogLevel": "Default": "Warning", "AllowedHosts": "*" The MySubOptions class defines properties, SubOption1 and SubOption2, to hold the options values (Models/MySubOptions.cs): public class MySubOptions public MySubOptions() // Set default values. SubOption1 = "value1_from_ctor"; SubOption2 = 5; public string SubOption1 get; set; public int SubOption2 get; set;

6 The page model's OnGet method returns a string with the options values (Pages/Index.cshtml.cs): private readonly MySubOptions _suboptions; public IndexModel( IOptions<MyOptions> optionsaccessor, IOptions<MyOptionsWithDelegateConfig> optionsaccessorwithdelegateconfig, IOptions<MySubOptions> suboptionsaccessor, IOptionsSnapshot<MyOptions> snapshotoptionsaccessor, IOptionsSnapshot<MyOptions> namedoptionsaccessor) _options = optionsaccessor.value; _optionswithdelegateconfig = optionsaccessorwithdelegateconfig.value; _suboptions = suboptionsaccessor.value; _snapshotoptions = snapshotoptionsaccessor.value; _named_options_1 = namedoptionsaccessor.get("named_options_1"); _named_options_2 = namedoptionsaccessor.get("named_options_2"); // Example #3: Sub-options var suboption1 = _suboptions.suboption1; var suboption2 = _suboptions.suboption2; SubOptions = $"suboption1 = suboption1, suboption2 = suboption2"; When the app is run, the OnGet method returns a string showing the sub-option class values: HTML suboption1 = subvalue1_from_json, suboption2 = 200 Options provided by a view model or with direct view injection Options provided by a view model or with direct view injection is demonstrated as Example #4 in the sample app. Options can be supplied in a view model or by injecting IOptions<TOptions> directly into a view (Pages/Index.cshtml.cs): private readonly MyOptions _options; public IndexModel( IOptions<MyOptions> optionsaccessor, IOptions<MyOptionsWithDelegateConfig> optionsaccessorwithdelegateconfig, IOptions<MySubOptions> suboptionsaccessor, IOptionsSnapshot<MyOptions> snapshotoptionsaccessor, IOptionsSnapshot<MyOptions> namedoptionsaccessor) _options = optionsaccessor.value; _optionswithdelegateconfig = optionsaccessorwithdelegateconfig.value;

7 _suboptions = suboptionsaccessor.value; _snapshotoptions = snapshotoptionsaccessor.value; _named_options_1 = namedoptionsaccessor.get("named_options_1"); _named_options_2 = namedoptionsaccessor.get("named_options_2"); // Example #4: Bind options directly to the page MyOptions = _options; For direct injection, inject IOptions<MyOptions> with IOptions<MyOptions> ViewData["Title"] = "Using Options Sample"; <h1>@viewdata["title"]</h1> When the app is run, the options values are shown in the rendered page:

8 Reload configuration data with IOptionsSnapshot Reloading configuration data with IOptionsSnapshot is demonstrated in Example #5 in the sample app. IOptionsSnapshot supports reloading options with minimal processing overhead. IOptionsSnapshot is a snapshot of IOptionsMonitor<TOptions> and updates automatically whenever the monitor triggers changes based on the data source changing. The following example demonstrates how a new IOptionsSnapshot is created after appsettings.json changes (Pages/Index.cshtml.cs). Multiple requests to the server return constant values provided by the appsettings.json file until the file is changed and configuration reloads. private readonly MyOptions _snapshotoptions; public IndexModel(

9 IOptions<MyOptions> optionsaccessor, IOptions<MyOptionsWithDelegateConfig> optionsaccessorwithdelegateconfig, IOptions<MySubOptions> suboptionsaccessor, IOptionsSnapshot<MyOptions> snapshotoptionsaccessor, IOptionsSnapshot<MyOptions> namedoptionsaccessor) _options = optionsaccessor.value; _optionswithdelegateconfig = optionsaccessorwithdelegateconfig.value; _suboptions = suboptionsaccessor.value; _snapshotoptions = snapshotoptionsaccessor.value; _named_options_1 = namedoptionsaccessor.get("named_options_1"); _named_options_2 = namedoptionsaccessor.get("named_options_2"); // Example #5: Snapshot options var snapshotoption1 = _snapshotoptions.option1; var snapshotoption2 = _snapshotoptions.option2; SnapshotOptions = $"snapshot option1 = snapshotoption1, " + $"snapshot option2 = snapshotoption2"; The following image shows the initial option1 and option2 values loaded from the appsettings.json file: HTML snapshot option1 = value1_from_json, snapshot option2 = -1 Change the values in the appsettings.json file to value1_from_json UPDATED and 200. Save the appsettings.json file. Refresh the browser to see that the options values are updated: HTML snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200 Options factory, monitoring, and cache IOptionsMonitor is used for notifications when TOptions instances change. IOptionsMonitor supports reloadable options, change notifications, and IPostConfigureOptions. Accessing options during startup IOptions can be used in Startup.Configure, since services are built before the Configure method executes. public void Configure(IApplicationBuilder app, IOptions<MyOptions> optionsaccessor) var option1 = optionsaccessor.value.option1;

10 IOptions shouldn't be used in Startup.ConfigureServices. An inconsistent options state may exist due to the ordering of service registrations. Additional resources Configuration in ASP.NET Core