Skip to content

Commit

Permalink
Add package readme for Microsoft.Extensions.Configuration.Binder (#77649
Browse files Browse the repository at this point in the history
)
  • Loading branch information
MSDN-WhiteKnight authored Oct 30, 2022
1 parent e6700ea commit 5c61ad4
Show file tree
Hide file tree
Showing 2 changed files with 94 additions and 1 deletion.
91 changes: 91 additions & 0 deletions src/libraries/Microsoft.Extensions.Configuration.Binder/README.md
Original file line number Diff line number Diff line change
@@ -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 included in the ASP.NET Core shared framework. The package is deployed as out-of-band (OOB) too and can be referenced 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>
```
Original file line number Diff line number Diff line change
Expand Up @@ -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'">
Expand Down

0 comments on commit 5c61ad4

Please sign in to comment.