Configuration is simple atomic structure of key-value pairs, and the keys and values are strings, but in the real project development, we generally do not simply in the form of key-value pairs to be used in the configuration. The recommended approach is to use " new configuration of the system [1] .NET Core uses: read configuration data " final demonstration of the way the relevant configuration is defined as a type of Options and use the structure and want to match the type definition to define the original configuration , so you can use the mapping relationship between them will read configuration data binding for the Options object, we will this programming mode is called " Options mode ." [This article has been synchronized to the " ASP.NET Framework Core Secret " among]
Contents
I. Bind the
two, extension methods AddOptions
Third, extension methods Configure
Fourth, create objects Options
First, configure the bindings
Options for a target, if we are to its data members (attributes this mainly refers to members) considered as its child nodes, then Options object also has a hierarchical tree structure, which is configured by trees and Configuration object represented in the structure not essentially different. Options If the type of data member definition tree structure having a configuration matching structure, the latter will bind to a corresponding type of Options object is a very easy thing, that bind to a target corresponding Configuration Options object the behavior referred to as " configure the binding ."
Binding configuration allows us to generate the corresponding Configuration Options object according to the object obtained at the relevant API definitions "Microsoft.Extensions.Configuration.Binder" NuGet this package, which is defined as the interface IConfiguration GetValue method to give a binding Options generated objects. In this call to let go, we will create an empty Options and objects as a parameter, the binding configuration data which will be carried to the Configuration Options object.
1: public static class ConfigurationBinder
2: {
3: public static void Bind(this IConfiguration configuration, object instance);
4: }
Configure the binding target may be a simple type of primitive types , or may be a custom data type , it may also be an array , set together or dictionary type. The Bind method described above during the configuration process bound for different target types, it will adopt a different strategy. As for the specific method of implementation principle, we will be separately described in the subsequent section, while the current focus is the introduction of API Options Options mode used to obtain the desired object in the back of how to call this method.
We look at " new .NET Core system configuration used in [1]: read configuration data " demo mode using Options to read the configuration examples. Options model is the application of dependency injection, we know the dependency injection for programming only involves two aspects, namely register the corresponding service to the ServiceCollection object, the object we need to provide services using the latter creates a corresponding ServiceProvider. As shown in the following code fragment, the ultimate goal is to use ServiceProvider Options obtain a pattern of type IOptions <TOptions> service object, which is generated by the binding configuration Value Options object. In order to obtain the required service object, which means two extension methods AddOptions and Configure <TOptions> registered the necessary services.
1: IConfiguration config = ...;
2: FormatOptions options = new ServiceCollection()
3: .AddOptions()
4: .Configure<FormatOptions>(config.GetSection("Format"))
5: .BuildServiceProvider()
6: .GetService<IOptions<FormatOptions>>()
7: .Value;
Second, the extension method AddOptions
Options object is still the ultimate way to create a use dependency injection of a type IOptions <TOptions> clientele get, we look first to understand this interface. This is a generic type of formal Options object interfaces, generic parameter type code corresponding TOptions. IOptions <TOptions> interfaces defined below, it has only a single read-only property Value Returns the object we need Options.
1: public interface IOptions<out TOptions> where TOptions: class, new()
2: {
3: TOptions Value { get; }
4: }
When we call ServiceCollection of AddOptions, the method is as follows only way to register for this type of a service only, this type of real services to OptionsManager <TOptions>, registered service lifecycle models used to Singleton. In other words, the configuration of the binding is generated Options object is actually returned by the final OptionsManager <TOptions> created.
1: public static IServiceCollection AddOptions(this IServiceCollection services)
2: {
3: services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptions<>), typeof(OptionsManager<>)));
4: return services;
5: }
Is OptionsManager <TOptions> types defined as shown below, we can see it accepts a constructor element type IConfigureOptions <TOptions> set as parameters, we will achieve the corresponding object type and the interface is referred to as ConfigureOptions < TOptions>. IConfigureOptions <TOptions> interface defines Configure a unique method of an Options object as an input parameter. As can be seen from the definition of the role of a delegate object ConfigureOptions <TOptions> object with a type Action <TOptions>, so for its implementation type ConfigureOptions <TOptions>, the corresponding object through a direct Action <TOptions> Object to create.
1: public class OptionsManager<TOptions> : IOptions<TOptions> where TOptions: class, new()
2: {
3: public OptionsManager(IEnumerable<IConfigureOptions<TOptions>> setups);
4: public virtual TOptions Value { get; }
5: }
6:
7: public interface IConfigureOptions<in TOptions> where TOptions: class
8: {
9: void Configure(TOptions options);
10: }
11:
12: public class ConfigureOptions<TOptions>: IConfigureOptions<TOptions> where TOptions : class, new()
13: {
14: public Action<TOptions> Action { get; private set; }
15: public ConfigureOptions(Action<TOptions> action)
16: {
17: this.Action = action;
18: }
19: public void Configure(TOptions options)
20: {
21: this.Action(options);
22: }
23: }
Options to create objects reflected in the OptionsManager <TOptions> type Value property. Realization of the property is very simple, it first calls the default no-argument constructor (Options type must have a default no-argument constructor) creates an empty Options object, before returning, it will submit its specified time to initialize ConfigureOptions < TOptions> processed one object. There is no doubt, for calling the Bind method is certainly a ConfigureOptions participation by <TOptions> objects into the entire process, the specific nature and achieve another extension method Configure about.
Third, the extension method Configure
Options for ServiceCollection mode involves only the two extension methods (AddOptions and Configure <TOptions>), the former will serve IOptions <TOptions> / OptionsManager <TOptions> registered onto ServiceCollection, which in turn made it kind of service registration?
1: public static IServiceCollection Configure<TOptions>(this IServiceCollection services, IConfiguration config) where TOptions: class
2: {
3: return services.AddSingleton<IConfigureOptions<TOptions>>( new ConfigureFromConfigurationOptions<TOptions>(config));
4: }
5:
6: public class ConfigureFromConfigurationOptions<TOptions> :ConfigureOptions<TOptions> where TOptions : class
7: {
8: public ConfigureFromConfigurationOptions(IConfiguration config)
9: : base(options => config.Bind(options))
10: { }
11: }
As can be seen from the above code fragment, when we call the extension method ServiceCollection Configure <TOptions>, which will use the specified object creates a ConfigureFromConfigurationOptions Configuration objects, and service type IConfigureOptions <TOptions> registered to ServiceCollection, used life cycle model for Singleton. As for the type of ConfigureFromConfigurationOptions, it is ConfigureOptions <TOptions> type of successor described above, create the object specified Action <TOptions> delegate object by calling extension methods Bind Configuration object and ultimately the configuration bindings.
Fourth, create objects Options
Behind Options programming mode to register to ServiceCollection two services at the core, these two services corresponding service interfaces are IOptions <TOptions> and IConfigureOptions <TOptions>, the former directly bound Options ultimate object configuration data, after Options object are then returned to its prior embodiment corresponding initialization. The two services are registered by extension methods AddOptions and Configure methods into designated ServiceCollection, real type of service are OptionsManager <TOptions> and ConfigureFromConfigurationOptions <TOptions>, which is derived from ConfigureOptions <TOptions>. Shown in the figure reflects the relationship of these interfaces UML / Options types involved in the model and therebetween.
Configuration is simple atomic structure of key-value pairs, and the keys and values are strings, but in the real project development, we generally do not simply in the form of key-value pairs to be used in the configuration. The recommended approach is to use " new configuration of the system [1] .NET Core uses: read configuration data " final demonstration of the way the relevant configuration is defined as a type of Options and use the structure and want to match the type definition to define the original configuration , so you can use the mapping relationship between them will read configuration data binding for the Options object, we will this programming mode is called " Options mode ." [This article has been synchronized to the " ASP.NET Framework Core Secret " among]
Contents
I. Bind the
two, extension methods AddOptions
Third, extension methods Configure
Fourth, create objects Options
First, configure the bindings
Options for a target, if we are to its data members (attributes this mainly refers to members) considered as its child nodes, then Options object also has a hierarchical tree structure, which is configured by trees and Configuration object represented in the structure not essentially different. Options If the type of data member definition tree structure having a configuration matching structure, the latter will bind to a corresponding type of Options object is a very easy thing, that bind to a target corresponding Configuration Options object the behavior referred to as " configure the binding ."
Binding configuration allows us to generate the corresponding Configuration Options object according to the object obtained at the relevant API definitions "Microsoft.Extensions.Configuration.Binder" NuGet this package, which is defined as the interface IConfiguration GetValue method to give a binding Options generated objects. In this call to let go, we will create an empty Options and objects as a parameter, the binding configuration data which will be carried to the Configuration Options object.
1: public static class ConfigurationBinder
2: {
3: public static void Bind(this IConfiguration configuration, object instance);
4: }
Configure the binding target may be a simple type of primitive types , or may be a custom data type , it may also be an array , set together or dictionary type. The Bind method described above during the configuration process bound for different target types, it will adopt a different strategy. As for the specific method of implementation principle, we will be separately described in the subsequent section, while the current focus is the introduction of API Options Options mode used to obtain the desired object in the back of how to call this method.
We look at " new .NET Core system configuration used in [1]: read configuration data " demo mode using Options to read the configuration examples. Options model is the application of dependency injection, we know the dependency injection for programming only involves two aspects, namely register the corresponding service to the ServiceCollection object, the object we need to provide services using the latter creates a corresponding ServiceProvider. As shown in the following code fragment, the ultimate goal is to use ServiceProvider Options obtain a pattern of type IOptions <TOptions> service object, which is generated by the binding configuration Value Options object. In order to obtain the required service object, which means two extension methods AddOptions and Configure <TOptions> registered the necessary services.
1: IConfiguration config = ...;
2: FormatOptions options = new ServiceCollection()
3: .AddOptions()
4: .Configure<FormatOptions>(config.GetSection("Format"))
5: .BuildServiceProvider()
6: .GetService<IOptions<FormatOptions>>()
7: .Value;
Second, the extension method AddOptions
Options object is still the ultimate way to create a use dependency injection of a type IOptions <TOptions> clientele get, we look first to understand this interface. This is a generic type of formal Options object interfaces, generic parameter type code corresponding TOptions. IOptions <TOptions> interfaces defined below, it has only a single read-only property Value Returns the object we need Options.
1: public interface IOptions<out TOptions> where TOptions: class, new()
2: {
3: TOptions Value { get; }
4: }
When we call ServiceCollection of AddOptions, the method is as follows only way to register for this type of a service only, this type of real services to OptionsManager <TOptions>, registered service lifecycle models used to Singleton. In other words, the configuration of the binding is generated Options object is actually returned by the final OptionsManager <TOptions> created.
1: public static IServiceCollection AddOptions(this IServiceCollection services)
2: {
3: services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptions<>), typeof(OptionsManager<>)));
4: return services;
5: }
Is OptionsManager <TOptions> types defined as shown below, we can see it accepts a constructor element type IConfigureOptions <TOptions> set as parameters, we will achieve the corresponding object type and the interface is referred to as ConfigureOptions < TOptions>. IConfigureOptions <TOptions> interface defines Configure a unique method of an Options object as an input parameter. As can be seen from the definition of the role of a delegate object ConfigureOptions <TOptions> object with a type Action <TOptions>, so for its implementation type ConfigureOptions <TOptions>, the corresponding object through a direct Action <TOptions> Object to create.
1: public class OptionsManager<TOptions> : IOptions<TOptions> where TOptions: class, new()
2: {
3: public OptionsManager(IEnumerable<IConfigureOptions<TOptions>> setups);
4: public virtual TOptions Value { get; }
5: }
6:
7: public interface IConfigureOptions<in TOptions> where TOptions: class
8: {
9: void Configure(TOptions options);
10: }
11:
12: public class ConfigureOptions<TOptions>: IConfigureOptions<TOptions> where TOptions : class, new()
13: {
14: public Action<TOptions> Action { get; private set; }
15: public ConfigureOptions(Action<TOptions> action)
16: {
17: this.Action = action;
18: }
19: public void Configure(TOptions options)
20: {
21: this.Action(options);
22: }
23: }
Options to create objects reflected in the OptionsManager <TOptions> type Value property. Realization of the property is very simple, it first calls the default no-argument constructor (Options type must have a default no-argument constructor) creates an empty Options object, before returning, it will submit its specified time to initialize ConfigureOptions < TOptions> processed one object. There is no doubt, for calling the Bind method is certainly a ConfigureOptions participation by <TOptions> objects into the entire process, the specific nature and achieve another extension method Configure about.
Third, the extension method Configure
Options for ServiceCollection mode involves only the two extension methods (AddOptions and Configure <TOptions>), the former will serve IOptions <TOptions> / OptionsManager <TOptions> registered onto ServiceCollection, which in turn made it kind of service registration?
1: public static IServiceCollection Configure<TOptions>(this IServiceCollection services, IConfiguration config) where TOptions: class
2: {
3: return services.AddSingleton<IConfigureOptions<TOptions>>( new ConfigureFromConfigurationOptions<TOptions>(config));
4: }
5:
6: public class ConfigureFromConfigurationOptions<TOptions> :ConfigureOptions<TOptions> where TOptions : class
7: {
8: public ConfigureFromConfigurationOptions(IConfiguration config)
9: : base(options => config.Bind(options))
10: { }
11: }
As can be seen from the above code fragment, when we call the extension method ServiceCollection Configure <TOptions>, which will use the specified object creates a ConfigureFromConfigurationOptions Configuration objects, and service type IConfigureOptions <TOptions> registered to ServiceCollection, used life cycle model for Singleton. As for the type of ConfigureFromConfigurationOptions, it is ConfigureOptions <TOptions> type of successor described above, create the object specified Action <TOptions> delegate object by calling extension methods Bind Configuration object and ultimately the configuration bindings.
Fourth, create objects Options
Behind Options programming mode to register to ServiceCollection two services at the core, these two services corresponding service interfaces are IOptions <TOptions> and IConfigureOptions <TOptions>, the former directly bound Options ultimate object configuration data, after Options object are then returned to its prior embodiment corresponding initialization. The two services are registered by extension methods AddOptions and Configure methods into designated ServiceCollection, real type of service are OptionsManager <TOptions> and ConfigureFromConfigurationOptions <TOptions>, which is derived from ConfigureOptions <TOptions>. Shown in the figure reflects the relationship of these interfaces UML / Options types involved in the model and therebetween.