Introduction

In .NET Core applications, appsettings.json is the baseline configuration file, while appsettings.Development.json, appsettings.Staging.json, and appsettings.Production.json are environment-specific override files. The important rule is precedence: later configuration sources override earlier ones when they provide the same key.

What belongs in the base file

appsettings.json should contain values that are shared across environments or safe defaults that make sense everywhere.

1{
2  "Logging": {
3    "LogLevel": {
4      "Default": "Information"
5    }
6  },
7  "Features": {
8    "UseCaching": true
9  }
10}

Think of this file as the common baseline for the application. It gives every environment a starting point.

What belongs in the environment-specific file

An environment-specific file overrides only the values that differ in that environment.

1{
2  "Logging": {
3    "LogLevel": {
4      "Default": "Debug"
5    }
6  },
7  "Features": {
8    "UseCaching": false
9  }
10}

If this content lives in appsettings.Development.json, the development environment will use the overridden logging level and caching flag, while other values still fall back to the base file.

How the merge works

The files are not merged as separate isolated configuration objects. They are loaded as configuration providers. When two providers define the same key, the later one wins.

That means:

• values present only in appsettings.json remain available
• values repeated in the environment file get overridden there
• nested sections are resolved key by key

This behavior is why environment-specific files are usually small. They should describe differences, not duplicate the entire base configuration.

How the environment is selected

The environment name typically comes from the host environment variables and determines which optional environment-specific file is loaded. If the environment is Development, the application will look for appsettings.Development.json. If that file is missing and the provider was configured as optional, the app still runs using the remaining configuration sources.

In modern applications, these files are only part of the full precedence chain. Environment variables, user secrets in development, and command-line arguments often override JSON files entirely.

Do not store secrets casually in JSON files

Configuration files are convenient, but they are not the right home for sensitive production secrets. Store secrets in environment variables, secret stores, or vault systems instead.

That keeps the role of JSON files clear: baseline configuration and environment-specific non-secret overrides.

Keep overrides minimal

A good environment file should be small enough that you can quickly see what is different about that environment. If the environment-specific file becomes a near copy of the base file, configuration drift becomes harder to spot and maintenance gets worse over time.

That small-difference approach also makes deployments safer. Reviewers can quickly verify that only environment-specific behavior changed instead of re-reading a duplicated configuration file line by line.

In practice, that usually means the base file defines the default behavior and each environment file edits only the exceptions.

Common Pitfalls

• Duplicating the full base configuration into every environment-specific file.
• Forgetting that later providers override earlier ones key by key.
• Assuming the environment-specific file is independent rather than an override layer.
• Storing production secrets in checked-in JSON files.
• Debugging the wrong configuration source because an environment variable or command-line setting overrides both JSON files.

Summary

• 'appsettings.json is the shared baseline configuration.'
• 'appsettings.{Environment}.json files override only the values that differ for that environment.'
• Configuration precedence matters more than the file names themselves.
• Keep environment-specific files small and focused on differences.
• Use dedicated secret-management mechanisms for sensitive settings instead of checked-in JSON files.