Provides the functionality to bind an object to data in configuration providers for Microsoft.Extensions.Configuration.

Documentation can be found at https://learn.microsoft.com/dotnet/core/extensions/configuration.

• We consider new features, new APIs, bug fixes, and performance changes

The APIs and functionality are mature, but do get extended occasionally.

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.

The following example shows how to bind a JSON configuration section to .NET objects.

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:

{
  "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:

<ItemGroup>
  <Content Include="appsettings.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
</ItemGroup>

Along with the binder assembly that uses reflection, we ship a source generator assembly that provides a reflection and AOT compatible implementation. It works by intercepting regular binding calls and redirecting them to new routines that execute strongly typed binding logic.

• Build the .NET libraries and runtime assemblies
• Make the generator changes in the gen\ directory
• Validate the changes by running the source generator tests in tests\SourceGeneratorTests

Here's a general command for running the the generator tests. They assume that you're making the changes in a Windows OS and running the from the tests\SourceGeneratorTests\ directory.

dotnet build /t:test

If applicable, add new tests to validate your contribution. See this documentation for details.

Sometimes the SDK uses stale bits of the generator. This can lead to unexpected test behavior or failures. Killing dotnet.exe processes usually solves the issue, e.g. with taskkill /F /IM dotnet.exe /T.

Some contributions might change the logic emitted by the generator. We maintain baseline source files to track the code emitted to handle some core binding scenarios.

If the emitted code changes, these tests will fail locally and in continuous integration checks (for PRs) changes. You would need to update the baseline source files, manually or by using the following commands (PowerShell):

> $env:RepoRootDir = "D:\repos\dotnet_runtime"
> dotnet build t:test -f /p:UpdateBaselines=true

We have a test helper to update the baselines. It requires setting an environment variable called RepoRootDir to the root repo path. In additon, the UpdateBaselines MSBuild property needs to be set to true.

After updating the baselines, inspect the changes to verify that they are valid. Note that the baseline tests will fail if the new code causes errors when building the resulting compilation.