Your app's settings shouldn't be hardcoded — they should come from outside, layered and overridable.

Your app needs a connection string. Where does it come from? If you write const string ConnectionString = "Server=prod-db;..."; directly in your code, you've made a decision you'll regret the first time you need to run against a different database — for testing, for staging, or for a teammate's local machine. Now you're editing source code and recompiling just to point at a different server.

.NET's configuration system solves this by treating settings as data that flows in from outside your code — files, environment variables, command-line arguments — and lets you read it all through one unified interface, with a predictable, well-defined order for which source wins when two disagree.

In this lesson, you'll learn how IConfiguration works, how appsettings.json fits in, what configuration providers are and their override order, and how to bind a configuration section into a strongly-typed class.

What Is It?

The Simple Explanation

Configuration is all the settings your app needs to run that shouldn't be baked into the compiled code — connection strings, API keys, feature flags, retry counts. IConfiguration is the single .NET interface your code uses to read those settings, no matter where they actually came from.

The Technical Definition

IConfiguration represents a set of key/value application configuration properties, built from one or more configuration providers — sources like JSON files, environment variables, or command-line arguments — merged together into a single, hierarchical view. Keys can be nested using a colon (Logging:LogLevel:Default) or, when represented in JSON, ordinary nested objects.

Why Does It Exist?

The Problem — Hardcoded Settings Don't Survive Contact With Reality

• A connection string baked into code means recompiling to point at a different database.
• A secret (API key, password) checked into source control is a security incident waiting to happen.
• Every environment (your laptop, a CI pipeline, staging, production) needs slightly different values, and juggling that with #if compiler directives is unmanageable.

The Solution — Layered, External Configuration

.NET's configuration system lets you define sensible defaults in a checked-in JSON file, then override specific values per environment using environment variables or command-line arguments — without touching a single line of code or recompiling. The same compiled binary runs correctly in every environment, because the values it reads change, not the code itself.

Big Picture

appsettings.json               ← base defaults
        ↓ overridden by
appsettings.{Environment}.json ← environment-specific overrides
        ↓ overridden by
Environment Variables          ← deploy-time / secret overrides
        ↓ overridden by
Command-Line Arguments         ← highest priority, wins over everything

Each provider is layered on top of the ones before it. If two providers define the same key, the one added later wins. This is the entire mental model you need for 90% of configuration questions: "which source was added last?"

How It Works

var builder = Host.CreateApplicationBuilder(args);

string? connString = builder.Configuration["ConnectionStrings:Default"];
string? retries = builder.Configuration.GetSection("Api")["RetryCount"];

var apiSettings = new ApiSettings();
builder.Configuration.GetSection("Api").Bind(apiSettings);

Simple Example

appsettings.json:

{
  "Api": {
    "BaseUrl": "https://api.example.com",
    "RetryCount": 3,
    "TimeoutSeconds": 30
  }
}

A matching, strongly-typed class:

public class ApiSettings
{
    public string BaseUrl { get; set; } = string.Empty;
    public int RetryCount { get; set; }
    public int TimeoutSeconds { get; set; }
}

var builder = Host.CreateApplicationBuilder(args);

var apiSettings = new ApiSettings();
builder.Configuration.GetSection("Api").Bind(apiSettings);

Console.WriteLine(apiSettings.BaseUrl);     // https://api.example.com
Console.WriteLine(apiSettings.RetryCount);  // 3

Now run the app with an environment variable override — no code change, no rebuild:

# Environment variables use double-underscore for nesting instead of colon
export Api__RetryCount=5

dotnet run
# apiSettings.RetryCount is now 5 — env var overrode the JSON default

Note the double underscore (__) — most shells and operating systems don't allow colons in environment variable names, so the configuration system accepts __ as an equivalent separator specifically for environment variables.

Real-World Example

A notification service reads its SMTP settings from configuration, registers the bound settings as a Singleton, and injects them into the service that needs them:

// appsettings.json
// { "Smtp": { "Host": "localhost", "Port": 25, "FromAddress": "no-reply@shop.com" } }

public class SmtpSettings
{
    public string Host { get; set; } = string.Empty;
    public int Port { get; set; }
    public string FromAddress { get; set; } = string.Empty;
}

var builder = Host.CreateApplicationBuilder(args);

var smtpSettings = new SmtpSettings();
builder.Configuration.GetSection("Smtp").Bind(smtpSettings);
builder.Services.AddSingleton(smtpSettings);
builder.Services.AddSingleton<IEmailSender, SmtpEmailSender>();

public class SmtpEmailSender(SmtpSettings settings) : IEmailSender
{
    public void Send(string to, string message) =>
        Console.WriteLine($"[{settings.Host}:{settings.Port}] From {settings.FromAddress} → {to}: {message}");
}

In production, an ops engineer sets Smtp__Host and Smtp__Port as environment variables on the deployment platform — the checked-in appsettings.json keeps sensible local-development defaults, and nobody touches source code to change where email gets sent.

Analogy

Under the Hood

Common Confusion

"Override" means replace, not merge

If appsettings.json defines an entire "Api" object with three properties, and an environment variable only overrides Api__RetryCount, the other two properties (BaseUrl, TimeoutSeconds) are untouched — only the specific key that the environment variable targets is replaced. Overriding happens per-key, not per-object.

Configuration values are always strings under the hood

Even "RetryCount": 3 in JSON is stored internally as the string "3". When you Bind() to a typed class, the binder converts strings to the target property's type (int, bool, enum, etc.) for you — but if you read a raw value with the indexer (configuration["Api:RetryCount"]), you always get back a string?, not an int.

Common Mistakes

Mistake 1 — Committing real secrets into appsettings.json

Writing a production API key or database password directly into appsettings.json, which gets committed to source control.

Keep only non-sensitive defaults in appsettings.json. Supply real secrets via environment variables, a secret manager, or (locally) the .NET User Secrets tool — never commit them.

Mistake 2 — Using a colon in an environment variable name

Trying to set Api:RetryCount as an actual OS environment variable name — many shells reject colons in variable names, or silently mangle them.

Use double underscore for environment variables: Api__RetryCount. The configuration system automatically translates it to the colon-separated key internally.

Mistake 3 — Assuming the indexer returns a typed value

int retries = builder.Configuration["Api:RetryCount"]; — this doesn't compile; the indexer returns string?.

Either parse it explicitly (int.Parse(...)), use GetValue<int>("Api:RetryCount"), or (preferably, for anything beyond a single value) bind the whole section to a typed class.

When Should I Use It?

• Always for anything that could plausibly differ between environments: connection strings, external API URLs, feature flags, timeouts, retry counts.
• Almost always for anything sensitive (keys, passwords) — supplied via environment variables or a proper secret store, never hardcoded.
• Truly constant values that will never change and aren't sensitive (like an internal enum's display name) can reasonably stay as C# constants — configuration is for values that vary by deployment or need to change without a rebuild.

Mental Model

Key Takeaway

Check Your Understanding

You've seen how configuration is layered from multiple providers. Let's check your grasp of the override order.

You now understand how .NET layers configuration from multiple sources and how to bind it into strongly-typed settings classes.

dotnetmadeeasy.com — Learn C# and .NET, the right way.