CSAT HPV config doc

aspnetcore/fundamentals/configuration/index.md

@@ -5,7 +5,7 @@ description: Use the Configuration API to configure an ASP.NET Core app by multi
 manager: wpickett
 ms.author: riande
 ms.custom: mvc
-ms.date: 11/01/2017
+ms.date: 1/11/2018
 ms.topic: article
 ms.technology: aspnet
 ms.prod: asp.net-core
@@ -15,7 +15,7 @@ uid: fundamentals/configuration/index
 
 By [Rick Anderson](https://twitter.com/RickAndMSFT), [Mark Michaelis](http://intellitect.com/author/mark-michaelis/), [Steve Smith](https://ardalis.com/), [Daniel Roth](https://github.com/danroth27), and [Luke Latham](https://github.com/guardrex)
 
-The Configuration API provides a way to configure an ASP.NET Core web app based on a list of name-value pairs. Configuration is read at runtime from multiple sources. You can group these name-value pairs into a multi-level hierarchy. 
+The Configuration API provides a way to configure an ASP.NET Core web app based on a list of name-value pairs. Configuration is read at runtime from multiple sources. You can group these name-value pairs into a multi-level hierarchy.
 
 There are configuration providers for:
 
@@ -45,38 +45,37 @@ The app reads and displays the following configuration settings:
 
 Configuration consists of a hierarchical list of name-value pairs in which the nodes are separated by a colon. To retrieve a value, access the `Configuration` indexer with the corresponding item's key:
 
-```csharp
-Console.WriteLine($"option1 = {Configuration["subsection:suboption1"]}");
-```
+[!code-csharp[Main](index/sample/ConfigJson/Program.cs?range=24-24)]
 
 To work with arrays in JSON-formatted configuration sources, use an array index as part of the colon-separated string. The following example gets the name of the first item in the preceding `wizards` array:
 
 ```csharp
 Console.Write($"{Configuration["wizards:0:Name"]}, ");
 ```
 
-Name-value pairs written to the built-in `Configuration` providers are **not** persisted. However, you can create a custom provider that saves values. See [custom configuration provider](xref:fundamentals/configuration/index#custom-config-providers).
+Name-value pairs written to the built-in [Configuration](https://docs.microsoft.com/ dotnet/api/microsoft.extensions.configuration) providers are **not** persisted. However, you can create a custom provider that saves values. See [custom configuration provider](xref:fundamentals/configuration/index#custom-config-providers).
 
 The preceding sample uses the configuration indexer to read values. To access configuration outside of `Startup`, use the *options pattern*. For more information, see the [Options](xref:fundamentals/configuration/options) topic.
 
-It's typical to have different configuration settings for different environments, for example, development, testing, and production. The `CreateDefaultBuilder` extension method in an ASP.NET Core 2.x app (or using `AddJsonFile` and `AddEnvironmentVariables` directly in an ASP.NET Core 1.x app) adds configuration providers for reading JSON files and system configuration sources:
+It's typical to have different configuration settings for different environments, for example, development, testing, and production. The [CreateDefaultBuilder](https://docs.microsoft.com/ dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder #Microsoft_AspNetCore_WebHost_CreateDefaultBuilder_System_String___) method adds configuration providers for reading JSON files and system configuration sources:
 
 * *appsettings.json*
 * *appsettings.\<EnvironmentName>.json*
 * Environment variables
 
-See [AddJsonFile](/dotnet/api/microsoft.extensions.configuration.jsonconfigurationextensions) for an explanation of the parameters. `reloadOnChange` is only supported in ASP.NET Core 1.1 and later. 
+ASP.NET Core 1.x apps need to call `AddJsonFile` and [AddEnvironmentVariables](https://docs.microsoft.com/ dotnet/api/microsoft.extensions.configuration.environmentvariablesextensions.addenvironmentvariables #Microsoft_Extensions_Configuration_EnvironmentVariablesExtensions_AddEnvironmentVariables_Microsoft_Extensions_Configuration_IConfigurationBuilder_System_String_).
+
+See [AddJsonFile](/dotnet/api/microsoft.extensions.configuration.jsonconfigurationextensions) for an explanation of the parameters. `reloadOnChange` is only supported in ASP.NET Core 1.1 and later.
 
-Configuration sources are read in the order that they're specified. In the code above, the environment variables are read last. Any configuration values set through the environment replace those set in the two previous providers.
+Configuration sources are read in the order that they're specified. In the code above, the environment variables are read last. Any configuration values set through the environment replace configuration values set in the two previous providers. Reading environment variables last is considered a best practice. Production apps frequently set configuration values with environment variables.
 
-The environment is typically set to `Development`, `Staging`, or `Production`. See [Working with multiple environments](xref:fundamentals/environments) for more information.
+The environment is typically set to `Development`, `Staging`, or `Production`. For more information, see [Working with multiple environments](xref:fundamentals/environments).
 
 Configuration considerations:
 
-* `IOptionsSnapshot` can reload configuration data when it changes. See [IOptionsSnapshot](xref:fundamentals/configuration/options#reload-configuration-data-with-ioptionssnapshot) for more information.
-* Configuration keys are case insensitive.
-* Specify environment variables last so that the local environment can override settings in deployed configuration files.
-* **Never** store passwords or other sensitive data in configuration provider code or in plain text configuration files. Don't use production secrets in your development or test environments. Instead, specify secrets outside of the project so that they can't be accidentally committed to your repository. Learn more about [working with multiple environments](xref:fundamentals/environments) and managing [safe storage of app secrets during development](xref:security/app-secrets).
+* `IOptionsSnapshot` can reload configuration data when it changes. For more information, see [IOptionsSnapshot](xref:fundamentals/configuration/options#reload-configuration-data-with-ioptionssnapshot).,
+* Configuration keys are **not** case-sensitive.
+* **Never** store passwords or other sensitive data in configuration provider code or in plain text configuration files. Don't use production secrets in your development or test environments. Specify secrets outside of the project so that they can't be accidentally committed to your repository. Learn more about [working with multiple environments](xref:fundamentals/environments) and managing [safe storage of app secrets during development](xref:security/app-secrets).
 * If a colon (`:`) can't be used in environment variables on your system, replace the colon (`:`) with a double-underscore (`__`).
 
 ## In-memory provider and binding to a POCO class
@@ -91,7 +90,7 @@ Configuration values are returned as strings, but binding enables the constructi
 
 The following sample demonstrates the [GetValue&lt;T&gt;](https://docs.microsoft.com/aspnet/core/api/microsoft.extensions.configuration.configurationbinder#Microsoft_Extensions_Configuration_ConfigurationBinder_GetValue_Microsoft_Extensions_Configuration_IConfiguration_System_Type_System_String_System_Object_) extension method:
 
-[!code-csharp[Main](index/sample/InMemoryGetValue/Program.cs?highlight=27-29)]
+[!code-csharp[Main](index/sample/InMemoryGetValue/Program.cs?highlight=31)]
 
 The ConfigurationBinder's `GetValue<T>` method allows you to specify a default value (80 in the sample). `GetValue<T>` is for simple scenarios and does not bind to entire sections. `GetValue<T>` gets scalar values from `GetSection(key).Value` converted to a specific type.
 
@@ -105,7 +104,7 @@ The following sample binds to the `AppSettings` class:
 
 [!code-csharp[Main](index/sample/ObjectGraph/Program.cs?highlight=15-16)]
 
-**ASP.NET Core 1.1** and higher can use  `Get<T>`, which works with entire sections. `Get<T>` can be more convenient than using `Bind`. The following code shows how to use `Get<T>` with the sample above:
+**ASP.NET Core 1.1** and higher can use `Get<T>`, which works with entire sections. `Get<T>` can be more convenient than using `Bind`. The following code shows how to use `Get<T>` with the preceding sample:
 
 ```csharp
 var appConfig = config.GetSection("App").Get<AppSettings>();
@@ -148,7 +147,7 @@ public void CanBindObjectTree()
 
 ## Create an Entity Framework custom provider
 
-In this section, a basic configuration provider that reads name-value pairs from a database using EF is created. 
+In this section, a basic configuration provider that reads name-value pairs from a database using EF is created.
 
 Define a `ConfigurationValue` entity for storing configuration values in the database:
 
@@ -158,11 +157,11 @@ Add a `ConfigurationContext` to store and access the configured values:
 
 [!code-csharp[Main](index/sample/CustomConfigurationProvider/ConfigurationContext.cs?name=snippet1)]
 
-Create an class that implements [IConfigurationSource](https://docs.microsoft.com/aspnet/core/api/microsoft.extensions.configuration.iconfigurationsource):
+Create a class that implements [IConfigurationSource](https://docs.microsoft.com/aspnet/core/api/microsoft.extensions.configuration.iconfigurationsource):
 
 [!code-csharp[Main](index/sample/CustomConfigurationProvider/EntityFrameworkConfigurationSource.cs?highlight=7)]
 
-Create the custom configuration provider by inheriting from [ConfigurationProvider](https://docs.microsoft.com/aspnet/core/api/microsoft.extensions.configuration.configurationprovider).  The configuration provider initializes the database when it's empty:
+Create the custom configuration provider by inheriting from [ConfigurationProvider](https://docs.microsoft.com/aspnet/core/api/microsoft.extensions.configuration.configurationprovider). The configuration provider initializes the database when it's empty:
 
 [!code-csharp[Main](index/sample/CustomConfigurationProvider/EntityFrameworkConfigurationProvider.cs?highlight=9,18-31,38-39)]
 
@@ -182,7 +181,7 @@ Using the following *appsettings.json* file:
 
 [!code-json[Main](index/sample/CustomConfigurationProvider/appsettings.json)]
 
-The following is displayed:
+The following output is displayed:
 
 ```console
 key1=value_from_ef_1
@@ -236,10 +235,15 @@ Typical ASP.NET Core 2.x apps use the static convenience method `CreateDefaultBu
 
 `CreateDefaultBuilder` loads optional configuration from *appsettings.json*, *appsettings.{Environment}.json*, [user secrets](xref:security/app-secrets) (in the `Development` environment), environment variables, and command-line arguments. The CommandLine configuration provider is called last. Calling the provider last allows the command-line arguments passed at runtime to override configuration set by the other configuration providers called earlier.
 
-Note that for *appsettings* files that `reloadOnChange` is enabled. Command-line arguments are overridden if a matching configuration value in an *appsettings* file is changed after the app starts.
+For *appsettings* files where:
+
+* `reloadOnChange` is enabled.
+* Contain the same setting in the command-line arguments and an *appsettings* file.
+* The *appsettings* file containing the matching command-line argument is changed after the app starts.
+
+If all the preceding conditions are true, the command-line arguments are overridden.
 
-> [!NOTE]
-> As an alternative to using the `CreateDefaultBuilder` method, creating a host using [WebHostBuilder](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilder) and manually building configuration with [ConfigurationBuilder](/api/microsoft.extensions.configuration.configurationbuilder) is supported in ASP.NET Core 2.x. See the ASP.NET Core 1.x tab for more information.
+ASP.NET Core 2.x app can use WebHostBuilder](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilder) instead of ``CreateDefaultBuilder`. When using `WebHostBuilder`, manually set configuration with [ConfigurationBuilder](/api/microsoft.extensions.configuration.configurationbuilder). See the ASP.NET Core 1.x tab for more information.
 
 # [ASP.NET Core 1.x](#tab/aspnetcore1x)
 
@@ -251,7 +255,7 @@ Create a [ConfigurationBuilder](/api/microsoft.extensions.configuration.configur
 
 ### Arguments
 
-Arguments passed on the command line must conform to one of two formats shown in the following table.
+Arguments passed on the command line must conform to one of two formats shown in the following table:
 
 | Argument format                                                     | Example        |
 | ------------------------------------------------------------------- | :------------: |
@@ -348,7 +352,7 @@ MachineName: DahliaPC
 Left: 1984
 ```
 
-After the switch mappings dictionary is created, it contains the data shown in the following table.
+After the switch mappings dictionary is created, it contains the data shown in the following table:
 
 | Key            | Value                 |
 | -------------- | --------------------- |
@@ -377,8 +381,9 @@ A *web.config* file is required when hosting the app in IIS or IIS Express. Sett
 * Dependency Injection (DI) is not set up until after `ConfigureServices` is invoked.
 * The configuration system is not DI aware.
 * `IConfiguration` has two specializations:
-  * `IConfigurationRoot`  Used for the root node. Can trigger a reload.
-  * `IConfigurationSection`  Represents a section of configuration values. The `GetSection` and `GetChildren` methods return an `IConfigurationSection`.
+  * `IConfigurationRoot` Used for the root node. Can trigger a reload.
+  * `IConfigurationSection` Represents a section of configuration values. The `GetSection` and `GetChildren` methods return an `IConfigurationSection`.
+  * Use [IConfigurationRoot](https://docs.microsoft.com/ dotnet/api/microsoft.extensions.configuration.iconfigurationroot) when reloading configuration or need access to each provider. Neither of these situations are common.
 
 ## Additional resources
 

aspnetcore/fundamentals/configuration/index/sample/CommandLine/Program.cs

@@ -5,7 +5,7 @@
 
 public class Program
 {
-    public static IConfigurationRoot Configuration { get; set; }
+    public static IConfiguration Configuration { get; set; }
 
     public static Dictionary<string, string> GetSwitchMappings(
         IReadOnlyDictionary<string, string> configurationStrings)

aspnetcore/fundamentals/configuration/index/sample/ConfigJson/Program.cs

@@ -1,10 +1,12 @@
 using System;
 using System.IO;
+// Requires NuGet package
+// Microsoft.Extensions.Configuration.Json
 using Microsoft.Extensions.Configuration;
 
 public class Program
 {
-    public static IConfigurationRoot Configuration { get; set; }
+    public static IConfiguration Configuration { get; set; }
 
     public static void Main(string[] args = null)
     {
@@ -14,7 +16,7 @@ public static void Main(string[] args = null)
 
         Configuration = builder.Build();
 
-        Console.WriteLine($"option1 = {Configuration["option1"]}");
+        Console.WriteLine($"option1 = {Configuration["Option1"]}");
         Console.WriteLine($"option2 = {Configuration["option2"]}");
         Console.WriteLine(
             $"suboption1 = {Configuration["subsection:suboption1"]}");

aspnetcore/fundamentals/configuration/index/sample/InMemory/Program.cs

@@ -1,10 +1,12 @@
 using System;
 using System.Collections.Generic;
+// Requires NuGet package
+// Microsoft.Extensions.Configuration.Json
 using Microsoft.Extensions.Configuration;
 
 public class Program
 {   
-    public static IConfigurationRoot Configuration { get; set; }
+    public static IConfiguration Configuration { get; set; }
 
     public static void Main(string[] args = null)
     {
@@ -25,11 +27,21 @@ public static void Main(string[] args = null)
         Console.WriteLine($"Hello {Configuration["Profile:MachineName"]}");
 
         var window = new MyWindow();
+        // Bind requrires NuGet package
+        // Microsoft.Extensions.Configuration.Binder
         Configuration.GetSection("App:MainWindow").Bind(window);
         Console.WriteLine($"Left {window.Left}");
         Console.WriteLine();
 
         Console.WriteLine("Press any key...");
         Console.ReadKey();
     }
+}
+
+public class MyWindow
+{
+    public int Height { get; set; }
+    public int Width { get; set; }
+    public int Top { get; set; }
+    public int Left { get; set; }
 }

aspnetcore/fundamentals/configuration/index/sample/InMemoryGetValue/Program.cs

@@ -1,10 +1,12 @@
 using System;
 using System.Collections.Generic;
+// Requires NuGet package
+// Microsoft.Extensions.Configuration.Json
 using Microsoft.Extensions.Configuration;
 
 public class Program
 {   
-    public static IConfigurationRoot Configuration { get; set; }
+    public static IConfiguration Configuration { get; set; }
 
     public static void Main(string[] args = null)
     {
@@ -37,4 +39,12 @@ public static void Main(string[] args = null)
         Console.WriteLine("Press a key...");
         Console.ReadKey();
     }
+}
+
+public class MyWindow
+{
+    public int Height { get; set; }
+    public int Width { get; set; }
+    public int Top { get; set; }
+    public int Left { get; set; }
 }

aspnetcore/fundamentals/configuration/index/sample_snapshot/CommandLine/Program.cs

@@ -5,7 +5,7 @@
 
 public class Program
 {
-    public static IConfigurationRoot Configuration { get; set; }
+    public static IConfiguration Configuration { get; set; }
 
     public static void Main(string[] args = null)
     {