Add ConfigurationBuilder example (dotnet#7646)

Author: gewarren

snippets/csharp/Microsoft.Extensions.Configuration/ConfigurationBuilder/Overview/AppWithOptions.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="6.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="appsettings.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

snippets/csharp/Microsoft.Extensions.Configuration/ConfigurationBuilder/Overview/Program.cs

@@ -0,0 +1,11 @@
+using Microsoft.Extensions.Configuration;
+
+IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json", false, true);
+IConfigurationRoot root = builder.Build();
+
+Console.WriteLine($"Hello, { root["weather"] } world!");
+
+/* This program outputs the following text:
+ * 
+ * Hello, stormy world!
+ */

snippets/csharp/Microsoft.Extensions.Configuration/ConfigurationBuilder/Overview/appsettings.json

@@ -0,0 +1,3 @@
+{
+  "weather": "stormy"
+}

xml/Microsoft.Extensions.Configuration/ConfigurationBuilder.xml

@@ -26,8 +26,29 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>Used to build key/value based configuration settings for use in an application.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Used to build key/value-based configuration settings for use in an application.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+By using this class, you can store configuration values in a JSON file, for example, and then retrieve them at run time. For more information, see [Configuration - basic example](/dotnet/core/extensions/configuration#basic-example).
+
+If you're migrating an app to .NET Core 3.1 or a later version, you can use this class to replace the *app.config* file functionality that you may have previously used to configure your app.
+
+## Example
+
+The following code snippet shows a simplified app that creates a `ConfigurationBuilder` object to retrieve a string value from a JSON file at run time.
+    
+:::code language="csharp" source="~/snippets/csharp/Microsoft.Extensions.Configuration/ConfigurationBuilder/Overview/Program.cs":::
+
+The contents of the JSON file are shown here.
+    
+:::code language="json" source="~/snippets/csharp/Microsoft.Extensions.Configuration/ConfigurationBuilder/Overview/appsettings.json":::
+  
+   ]]></format>
+    </remarks>    
+    <related type="Article" href="/dotnet/core/extensions/configuration">Configuration in .NET</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -51,7 +72,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:Microsoft.Extensions.Configuration.ConfigurationBuilder" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -159,8 +180,9 @@
       </ReturnValue>
       <Docs>
         <summary>Gets a key/value collection that can be used to share data between the <see cref="T:Microsoft.Extensions.Configuration.IConfigurationBuilder" />
-            and the registered <see cref="T:Microsoft.Extensions.Configuration.IConfigurationProvider" />s.</summary>
-        <value>To be added.</value>
+            and the registered configuration providers.</summary>
+        <value>A key/value collection that can be used to share data between the <see cref="T:Microsoft.Extensions.Configuration.IConfigurationBuilder" />
+            and the registered configuration providers.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -197,8 +219,8 @@
         <ReturnType FrameworkAlternate="dotnet-plat-ext-2.0;dotnet-plat-ext-2.1;dotnet-plat-ext-2.2;dotnet-plat-ext-3.0;dotnet-plat-ext-3.1;dotnet-plat-ext-5.0;dotnet-plat-ext-6.0">System.Collections.Generic.IList&lt;Microsoft.Extensions.Configuration.IConfigurationSource&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Returns the sources used to obtain configuration values.</summary>
-        <value>To be added.</value>
+        <summary>Gets the sources used to obtain configuration values.</summary>
+        <value>The sources used to obtain configuration values.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>