You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: aspnet/fundamentals/configuration.rst
+18-23
Original file line number
Diff line number
Diff line change
@@ -23,16 +23,11 @@ At its simplest, ``Configuration`` is just a collection of sources, which provid
23
23
24
24
You must configure at least one source in order for ``Configuration`` to function correctly. The following sample shows how to test working with ``Configuration`` as a key/value store:
25
25
26
-
.. code-block:: c#
27
-
28
-
varbuilder=newConfigurationBuilder();
29
-
builder.AddInMemoryCollection();
30
-
varconfig=builder.Build();
31
-
config["somekey"] ="somevalue";
32
-
33
-
// do some other work
34
-
35
-
varsetting=config["somekey"]; // also returns "somevalue"
The application uses configuration to configure the right connection string. Access to the ``DefaultConnection`` setting is achieved through this key: ``ConnectionStrings:DefaultConnection``, or by using the ``GetConnectionString("DefaultConnection")`` extension method.
41
+
The application uses configuration to configure the right connection string. Access to the ``DefaultConnection`` setting is achieved through this key: ``ConnectionStrings:DefaultConnection``, or by using the :dn:method:`~Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString` extension method and passing in ``"DefaultConnection"``.
47
42
48
43
The settings required by your application and the mechanism used to specify those settings (configuration being one example) can be decoupled using the :ref:`options pattern <options-config-objects>`. To use the options pattern you create your own options class (probably several different classes, corresponding to different cohesive groups of settings) that you can inject into your application using an options service. You can then specify your settings using configuration or whatever mechanism you choose.
49
44
@@ -54,7 +49,7 @@ Using the built-in sources
54
49
55
50
The configuration framework has built-in support for JSON, XML, and INI configuration files, as well as support for in-memory configuration (directly setting values in code) and the ability to pull configuration from environment variables and command line parameters. Developers are not limited to using a single configuration source. In fact several may be set up together such that a default configuration is overridden by settings from another source if they are present.
56
51
57
-
Adding support for additional configuration sources is accomplished through extension methods. These methods can be called on a ``ConfigurationBuilder`` instance in a standalone fashion, or chained together as a fluent API. Both of these approaches are demonstrated in the sample below.
52
+
Adding support for additional configuration sources is accomplished through extension methods. These methods can be called on a :dn:class:`~Microsoft.Extensions.Configuration.ConfigurationBuilder` instance in a standalone fashion, or chained together as a fluent API. Both of these approaches are demonstrated in the sample below.
58
53
59
54
.. _custom-config:
60
55
@@ -75,9 +70,9 @@ It can be useful to have environment-specific configuration files. This can be a
75
70
:lines: 20-35
76
71
:emphasize-lines: 6
77
72
78
-
The ``IHostingEnvironment`` service is used to get the current environment. In the ``Development`` environment, the highlighted line of code above would look for a file named ``appsettings.Development.json`` and use its values, overriding any other values, if it's present. Learn more about :doc:`environments`.
73
+
The :dn:iface:`~Microsoft.AspNetCore.Hosting.IHostingEnvironment` service is used to get the current environment. In the ``Development`` environment, the highlighted line of code above would look for a file named ``appsettings.Development.json`` and use its values, overriding any other values, if it's present. Learn more about :doc:`environments`.
79
74
80
-
When specifying files as configuration sources, you can optionally specify whether changes to the file should result in the settings being reloaded. This is configured by passing in a ``true`` value for the ``reloadOnChange`` parameter when calling ``AddJsonFile`` or similar file-based extension methods.
75
+
When specifying files as configuration sources, you can optionally specify whether changes to the file should result in the settings being reloaded. This is configured by passing in a ``true`` value for the ``reloadOnChange`` parameter when calling :dn:method:`~Microsoft.Extensions.Configuration.JsonConfigurationExtensions.AddJsonFile` or similar file-based extension methods.
81
76
82
77
.. warning:: You should never store passwords or other sensitive data in configuration provider code or in plain text configuration files. You also shouldn't use production secrets in your development or test environments. Instead, such secrets should be specified outside the project tree, so they cannot be accidentally committed into the configuration provider repository. Learn more about :doc:`environments` and managing :doc:`/security/app-secrets`.
83
78
@@ -108,7 +103,7 @@ A simple ``MyOptions`` class is shown here:
108
103
:lines: 3-7
109
104
:dedent: 4
110
105
111
-
Options can be injected into your application using the ``IOptions<TOptions>`` accessor service. For example, the following :doc:`controller </mvc/controllers/index>` uses ``IOptions<MyOptions>`` to access the settings it needs to render the ``Index`` view:
106
+
Options can be injected into your application using the :dn:iface:`~Microsoft.Extensions.Options.IOptions\<TOptions>` accessor service. For example, the following :doc:`controller </mvc/controllers/index>` uses ``IOptions<MyOptions>`` to access the settings it needs to render the ``Index`` view:
@@ -118,7 +113,7 @@ Options can be injected into your application using the ``IOptions<TOptions>`` a
118
113
119
114
.. tip:: Learn more about :doc:`dependency-injection`.
120
115
121
-
To setup the ``IOptions<TOption>`` service you call the ``AddOptions()`` extension method during startup in your ``ConfigureServices`` method:
116
+
To setup the :dn:iface:`~Microsoft.Extensions.Options.IOptions\<TOptions>` service you call the :dn:method:`~Microsoft.Extensions.DependencyInjection.OptionsServiceCollectionExtensions.AddOptions` extension method during startup in your ``ConfigureServices`` method:
@@ -132,7 +127,7 @@ The ``Index`` view displays the configured options:
132
127
133
128
.. image:: configuration/_static/index-view.png
134
129
135
-
You configure options using the ``Configure<TOption>`` extension method. You can configure options using a delegate or by binding your options to configuration:
130
+
You configure options using the :dn:method:`~Microsoft.Extensions.DependencyInjection.OptionsServiceCollectionExtensions.Configure\<TOptions>` extension method. You can configure options using a delegate or by binding your options to configuration:
@@ -142,16 +137,16 @@ You configure options using the ``Configure<TOption>`` extension method. You can
142
137
143
138
When you bind options to configuration, each property in your options type is bound to a configuration key of the form ``property:subproperty:...``. For example, the ``MyOptions.Option1`` property is bound to the key ``Option1``, which is read from the ``option1`` property in *appsettings.json*. Note that configuration keys are case insensitive.
144
139
145
-
Each call to ``Configure<TOption>`` adds an ``IConfigureOptions<TOption>`` service to the service container that is used by the ``IOptions<TOption>`` service to provide the configured options to the application or framework. If you want to configure your options some other way (for example, reading settings from a database) you can use the ``AddSingleton<TOptions>`` extension method to you specify a custom ``IConfigureOptions<TOption>`` service directly.
140
+
Each call to :dn:method:`~Microsoft.Extensions.DependencyInjection.OptionsServiceCollectionExtensions.Configure\<TOptions>` adds an :dn:iface:`~Microsoft.Extensions.Options.IConfigureOptions\<TOptions>` service to the service container that is used by the :dn:iface:`~Microsoft.Extensions.Options.IOptions\<TOptions>` service to provide the configured options to the application or framework. If you want to configure your options some other way (for example, reading settings from a database) you can use the ``AddSingleton<TOptions>`` extension method to you specify a custom :dn:iface:`~Microsoft.Extensions.Options.IConfigureOptions\<TOptions>` service directly.
146
141
147
-
You can have multiple ``IConfigureOptions<TOption>`` services for the same option type and they are all applied in order. In the :ref:`example <options-example>` above, the values of ``Option1`` and ``Option2`` are both specified in `appsettings.json`, but the value of ``Option1`` is overridden by the configured delegate with the value "value1_from_action".
142
+
You can have multiple :dn:iface:`~Microsoft.Extensions.Options.IConfigureOptions\<TOptions>` services for the same option type and they are all applied in order. In the :ref:`example <options-example>` above, the values of ``Option1`` and ``Option2`` are both specified in `appsettings.json`, but the value of ``Option1`` is overridden by the configured delegate with the value "value1_from_action".
148
143
149
144
.. _custom-config-providers:
150
145
151
146
Writing custom providers
152
147
------------------------
153
148
154
-
In addition to using the built-in configuration providers, you can also write your own. To do so, you simply implement the ``IConfigurationSource`` interface, which exposes a ``Build`` method. The build method configures and returns an ``IConfigurationProvider``.
149
+
In addition to using the built-in configuration providers, you can also write your own. To do so, you simply implement the :dn:iface:`~Microsoft.Extensions.Configuration.IConfigurationSource` interface, which exposes a :dn:method:`~Microsoft.Extensions.Configuration.IConfigurationSource.Build` method. The build method configures and returns an :dn:iface:`~Microsoft.Extensions.Configuration.IConfigurationProvider`.
155
150
156
151
Example: Entity Framework Settings
157
152
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -173,13 +168,13 @@ You need a ``ConfigurationContext`` to store and access the configured values us
173
168
:dedent: 4
174
169
:emphasize-lines: 7
175
170
176
-
Create an ``EntityFrameworkConfigurationSource`` that inherits from ``IConfigurationSource``:
171
+
Create an ``EntityFrameworkConfigurationSource`` that inherits from :dn:iface:`~Microsoft.Extensions.Configuration.IConfigurationSource`:
Next, create the custom configuration provider by inheriting from ``ConfigurationProvider``. The configuration data is loaded by overriding the ``Load`` method, which reads in all of the configuration data from the configured database. For demonstration purposes, the configuration provider also takes care of initializing the database if it hasn't already been created and populated:
177
+
Next, create the custom configuration provider by inheriting from :dn:class:`~Microsoft.Extensions.Configuration.ConfigurationProvider`. The configuration data is loaded by overriding the ``Load`` method, which reads in all of the configuration data from the configured database. For demonstration purposes, the configuration provider also takes care of initializing the database if it hasn't already been created and populated:
@@ -193,7 +188,7 @@ By convention you can also add an ``AddEntityFrameworkConfiguration`` extension
193
188
:language: c#
194
189
:emphasize-lines: 9
195
190
196
-
You can see an example of how to use this custom configuration provider in your application in the following example. Create a new ``ConfigurationBuilder`` to set up your configuration sources. To add the ``EntityFrameworkConfigurationProvider``, you first need to specify the EF data provider and connection string. How should you configure the connection string? Using configuration of course! Add an *appsettings.json* file as a configuration source to bootstrap setting up the ``EntityFrameworkConfigurationProvider``. By adding the database settings to an existing configuration with other sources specified, any settings specified in the database will override settings specified in *appsettings.json*:
191
+
You can see an example of how to use this custom configuration provider in your application in the following example. Create a new :dn:class:`~Microsoft.Extensions.Configuration.ConfigurationBuilder` to set up your configuration sources. To add the ``EntityFrameworkConfigurationProvider``, you first need to specify the EF data provider and connection string. How should you configure the connection string? Using configuration of course! Add an *appsettings.json* file as a configuration source to bootstrap setting up the ``EntityFrameworkConfigurationProvider``. By adding the database settings to an existing configuration with other sources specified, any settings specified in the database will override settings specified in *appsettings.json*:
0 commit comments