Add package readme for Microsoft.Extensions.Configuration.Binder

src/libraries/Microsoft.Extensions.Configuration.Binder/src/Microsoft.Extensions.Configuration.Binder.csproj

@@ -5,13 +5,15 @@
     <EnableDefaultItems>true</EnableDefaultItems>
     <IsPackable>true</IsPackable>
     <EnableAOTAnalyzer>true</EnableAOTAnalyzer>
-    <PackageDescription>Functionality to bind an object to data in configuration providers for Microsoft.Extensions.Configuration.</PackageDescription>
+    <PackageDescription>Provides the functionality to bind an object to data in configuration providers for Microsoft.Extensions.Configuration. This package enables you to represent the configuration data as strongly-typed classes defined in the application code. To bind a configuration, use the Microsoft.Extensions.Configuration.ConfigurationBinder.Get extension method on the IConfiguration object. To use this package, you also need to install a package for the configuration provider, for example, Microsoft.Extensions.Configuration.Json for the JSON provider.</PackageDescription>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
     <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Configuration.Abstractions\src\Microsoft.Extensions.Configuration.Abstractions.csproj" />
     <Compile Include="$(CommonPath)Extensions\ParameterDefaultValue\ParameterDefaultValue.cs" Link="Common\src\Extensions\ParameterDefaultValue\ParameterDefaultValue.cs" />
     <Compile Include="$(CommonPath)System\ThrowHelper.cs" Link="Common\System\ThrowHelper.cs" />
+    <None Include="README.md" Pack="true" PackagePath="\"/>
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">

src/libraries/Microsoft.Extensions.Configuration.Binder/src/README.md

@@ -0,0 +1,91 @@
+# Microsoft.Extensions.Configuration.Binder
+
+Provides the functionality to bind an object to data in configuration providers for [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration/). This package enables you to represent the configuration data as strongly-typed classes defined in the application code. To bind a configuration, use the [Microsoft.Extensions.Configuration.ConfigurationBinder.Get](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.configurationbinder.get) extension method on the `IConfiguration` object. To use this package, you also need to install a package for the [configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration#configuration-providers), for example, [Microsoft.Extensions.Configuration.Json](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Json/) for the JSON provider.
+
+Documentation can be found at https://learn.microsoft.com/dotnet/core/extensions/configuration
+
+## Contribution Bar
+- [x] [We consider new features, new APIs, bug fixes, and performance changes](../../../libraries/README.md#primary-bar)
+
+The APIs and functionality are mature, but do get extended occasionally.
+
+## Deployment
+[Microsoft.Extensions.Configuration.Binder](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Binder/) is not included in the shared framework. The package is deployed as out-of-band (OOB) and needs to be installed into projects directly.
+
+## Example
+The following example shows how to bind a JSON configuration section to .NET objects.
+
+```cs
+using System;
+using Microsoft.Extensions.Configuration;
+
+class Settings
+{
+    public string Server { get; set; }
+    public string Database { get; set; }
+    public Endpoint[] Endpoints { get; set; }
+}
+
+class Endpoint
+{
+    public string IPAddress { get; set; }
+    public int Port { get; set; }
+}
+
+class Program
+{
+    static void Main()
+    {
+        // Build a configuration object from JSON file
+        IConfiguration config = new ConfigurationBuilder()
+            .AddJsonFile("appsettings.json")
+            .Build();
+
+        // Bind a configuration section to an instance of Settings class
+        Settings settings = config.GetSection("Settings").Get<Settings>();
+
+        // Read simple values
+        Console.WriteLine($"Server: {settings.Server}");
+        Console.WriteLine($"Database: {settings.Database}");
+
+        // Read nested objects
+        Console.WriteLine("Endpoints: ");
+
+        foreach (Endpoint endpoint in settings.Endpoints)
+        {
+            Console.WriteLine($"{endpoint.IPAddress}:{endpoint.Port}");
+        }
+    }
+}
+```
+
+To run this example, include an `appsettings.json` file with the following content in your project:
+
+```json
+{
+  "Settings": {
+    "Server": "example.com",
+    "Database": "Northwind",
+    "Endpoints": [
+      {
+        "IPAddress": "192.168.0.1",
+        "Port": "80"
+      },
+      {
+        "IPAddress": "192.168.10.1",
+        "Port": "8080"
+      }
+    ]
+  }
+}
+```
+
+You can include a configuration file using a code like this in your `.csproj` file:
+
+```xml
+<ItemGroup>
+  <Content Include="appsettings.json">
+    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+  </Content>
+</ItemGroup>
+```