Configuration

A setting is any value that has to differ between one place your application runs and another: a connection string, a page size, a timeout, the address of another service. Compiling those into your assembly means one build per environment, which defeats the point of building once and deploying the result.

Configuration in .NET is one merged key-value view, assembled from several sources at start-up. Keys are paths, written with colons: Employees:PageSize refers to PageSize inside the Employees section. Key comparison is case-insensitive, so Employees:PageSize and employees:pagesize reach the same value.

The important property is the merge order. Sources are added in sequence, and a later source overrides an earlier one for the same key. Nothing is combined cleverly — the last value in wins.

// appsettings.json — defaults, committed
{
  "Employees": {
    "PageSize": 25,
    "AllowSelfServiceUpdates": true,
    "SyncIntervalMinutes": 60
  },
  "ConnectionStrings": {
    "Employees": "Host=localhost;Database=employees;Username=dev;Password=REPLACE_ME"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

// appsettings.Production.json — only what differs
{
  "Employees": {
    "PageSize": 100,
    "AllowSelfServiceUpdates": false
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  }
}

• In production, PageSize is 100 and AllowSelfServiceUpdates is false. SyncIntervalMinutes is not mentioned in the second file, so it keeps the value 60 from the first. The merge happens key by key, not file by file.
• The connection string in the base file is a placeholder that cannot connect anywhere. Real values arrive from user secrets locally and from an environment variable or secret store in production.
• Arrays are the exception to the intuitive merge. A later source overrides array entries by index rather than replacing the array, so a two-item list layered over a four-item list leaves the last two items in place. If you need to replace a list, model it as an object keyed by name instead.
• JSON does not allow comments in the strictest reading of the format, but the configuration reader accepts them. The two comment lines above are there to separate the files for you.

using System.ComponentModel.DataAnnotations;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;

public sealed class EmployeeOptions
{
    public const string SectionName = "Employees";

    [Range(1, 500)]
    public int PageSize { get; set; } = 25;

    public bool AllowSelfServiceUpdates { get; set; }

    [Range(1, 1440)]
    public int SyncIntervalMinutes { get; set; } = 60;
}

// Program.cs
var builder = Host.CreateApplicationBuilder(args);

builder.Services
    .AddOptions<EmployeeOptions>()
    .Bind(builder.Configuration.GetSection(EmployeeOptions.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

// A class that needs the settings asks for them by type
public sealed class EmployeeDirectory(IOptions<EmployeeOptions> options)
{
    private readonly EmployeeOptions _options = options.Value;

    public int PageSize => _options.PageSize;
}

• Binding matches configuration keys to public settable properties by name. A key with no matching property is ignored silently, and a property with no matching key keeps its default — which is why a typo in a key name produces a working application with the wrong value rather than an error.
• The defaults on the properties are what you get when the section is missing entirely. Choosing safe defaults here is cheaper than handling absent configuration everywhere else.
• ValidateDataAnnotations checks the attributes. ValidateOnStart runs that check when the host starts instead of when the options are first requested, so a bad value stops the application immediately rather than failing the first request that happens to need it. Without ValidateOnStart, a misconfigured deployment can look healthy for minutes.
• The class asks for IOptions<EmployeeOptions>, not IConfiguration. That means it states exactly which settings it needs, it can be constructed in a test with a plain object, and it cannot reach any other part of the configuration.
• ValidateDataAnnotations lives in the Microsoft.Extensions.Options.DataAnnotations package. Web projects already have it through the shared framework; a console project may need the reference.