Configuring environment-specific app settings in .NET Core

A .NET Core application rarely runs with the same settings everywhere. Local development may use a developer workstation and a local database, while testing runs against shared services and production uses managed Azure resources. Environment-specific configuration lets the application keep one codebase while selecting suitable values for each stage.

The standard approach combines appsettings.json, environment-specific JSON files, environment variables, command-line arguments and secret stores. Understanding how these providers are layered is essential for applications deployed across Australian data centres, Azure App Service, containers or an internal platform team.

How the configuration hierarchy works

A typical ASP.NET Core application starts with a base file named appsettings.json. It can then load a more specific file such as appsettings.Development.json, appsettings.Testing.json or appsettings.Production.json. Values in the later file override matching values from the base file.

The default host created by modern .NET templates already includes these providers. In a web application using WebApplication.CreateBuilder(args), the framework generally loads JSON configuration, user secrets in development, environment variables and command-line arguments in an established order. A value supplied later in that sequence has higher priority.

var builder = WebApplication.CreateBuilder(args);

// Configuration is already loaded by the default builder.
var connectionString =
    builder.Configuration.GetConnectionString("Orders");

var app = builder.Build();
app.Run();

Avoid adding the same providers again unless there is a specific reason. Duplicate registrations can make precedence difficult to understand and may cause a file to be read twice. If a custom host is required, document the provider order clearly in the startup code.

Selecting the active environment

The host determines the current environment through an environment variable. ASPNETCORE_ENVIRONMENT is widely used by ASP.NET Core applications, while DOTNET_ENVIRONMENT is used by the generic host and newer hosting models. With WebApplicationBuilder, DOTNET_ENVIRONMENT takes precedence when both variables are present; traditional web host configuration can apply different precedence rules.

Set the value before the process starts. On Windows PowerShell, a local developer might use:

$env:ASPNETCORE_ENVIRONMENT = "Development"
dotnet run

On macOS, Linux or a container platform, the equivalent is:

ASPNETCORE_ENVIRONMENT=Testing dotnet run

The name is case-insensitive on Windows but can be case-sensitive in surrounding tooling on Linux. Use a small, agreed set of names, such as Development, Testing, Staging and Production. An Australian delivery team working across Sydney, Brisbane and Perth should keep these names consistent in source control, build pipelines and runbooks rather than inventing regional variants for ordinary deployment stages.

The environment name is available through IHostEnvironment or IWebHostEnvironment:

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

Use environment checks for behaviour that genuinely differs, such as developer diagnostics. Do not scatter environment-specific business rules throughout controllers and services. Put changeable values in configuration and bind them to options instead.

Organising JSON settings files

A base file should contain safe defaults that apply everywhere. The environment-specific file should contain only the differences. This keeps configuration readable and reduces the possibility that production values are accidentally copied into a local repository.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Orders": {
    "ApiBaseUrl": "https://orders.example.internal",
    "TimeoutSeconds": 30
  }
}

A development override might look like this:

{
  "Orders": {
    "ApiBaseUrl": "https://localhost:7240",
    "TimeoutSeconds": 60
  }
}

The second document could be saved as appsettings.Development.json. JSON configuration is hierarchical, so nested objects map naturally to sections. Keep production credentials, API keys and passwords out of both files. Even a private repository can be copied, indexed or exposed through a build artefact.

For an Australian organisation, the deployment region may need to be explicit where data residency matters. An Azure resource in australiaeast near Sydney and one in australiasoutheast near Melbourne can have different network paths, service availability and disaster-recovery implications. A setting such as Storage:AccountName can vary by environment, but the secret used to access that storage should come from a protected provider.

Overriding values with environment variables

Environment variables are convenient for CI/CD systems, Docker, Kubernetes and Azure App Service. They should use double underscores to represent nested configuration keys because the colon separator is not portable across operating systems and shells.

For the JSON section Orders:TimeoutSeconds, set:

Orders__TimeoutSeconds=45

For a connection string named Orders, use:

ConnectionStrings__Orders=Server=db;Database=orders;User Id=app;

The environment variable normally overrides the same key from JSON. This allows one image or deployment package to move from testing to production without modifying files inside the package. In an Azure App Service deployment, application settings are exposed to the process as environment variables, making them suitable for non-secret operational values and references to secret services.

Be careful with shell quoting, multiline values and special characters. A password containing $, ; or spaces can be altered by the shell before .NET reads it. Container manifests and pipeline variable groups should make these values explicit. The : form may work in some environments, but __ is the reliable cross-platform convention.

Environment variables can also configure logging:

Logging__LogLevel__Default=Warning

They are useful for urgent operational changes, although every override should be recorded in the deployment system. An unexplained variable left on a production host can be harder to detect than a visible JSON change.

Binding settings to typed options

Reading values directly throughout the application is fragile:

var timeout = configuration["Orders:TimeoutSeconds"];

The result is a string, validation is postponed and key names are repeated. The options pattern provides a typed boundary between configuration and application code.

public sealed class OrdersOptions
{
    public const string SectionName = "Orders";

    public string ApiBaseUrl { get; set; } = string.Empty;
    public int TimeoutSeconds { get; set; }
}

Register and validate the section during startup:

builder.Services
    .AddOptions<OrdersOptions>()
    .Bind(builder.Configuration.GetSection(OrdersOptions.SectionName))
    .Validate(options => Uri.TryCreate(
        options.ApiBaseUrl, UriKind.Absolute, out _),
        "ApiBaseUrl must be an absolute URI")
    .Validate(options => options.TimeoutSeconds > 0,
        "TimeoutSeconds must be greater than zero")
    .ValidateOnStart();

A service can then receive IOptions<OrdersOptions>. Use IOptionsSnapshot<T> when values may differ by request scope, and IOptionsMonitor<T> when a long-running process needs to observe reloadable configuration. ValidateOnStart() is especially valuable because a deployment fails immediately when a required setting is missing, instead of failing during the first customer request.

For secrets, use user secrets during local development, Azure Key Vault or another managed secret store in hosted environments, and a CI/CD secret facility for pipeline credentials. Australian businesses handling personal information should align secret management with the Privacy Act obligations and internal controls such as the Essential Eight. Logging an options object can unintentionally expose credentials, so redact sensitive fields.

Handling deployment and configuration reloads

Local JSON files commonly use reloadOnChange: true, allowing a running developer process to notice edits. This can be useful for logging levels or feature flags, but it should not be treated as a universal production strategy. In containers and some mounted volumes, file change notifications may be delayed or unavailable.

A safer operational model is to build an immutable application package and inject environment-specific values during deployment. The same container image can be promoted from a testing cluster to production while the platform supplies different endpoints, credentials and feature settings. This reduces configuration drift between stages.

Be aware that changing a setting does not automatically recreate clients that copied the old value during startup. An HttpClient, database pool or SDK client may retain its endpoint until the process restarts. For critical changes, a controlled restart is easier to reason about than relying on live reload.

Time zones deserve particular attention in Australian systems. Store timestamps in UTC, then apply an explicit business time zone such as Australia/Sydney or Australia/Perth when displaying or scheduling work. Sydney observes daylight saving while Perth does not, and a setting based on a fixed +10:00 offset will eventually produce incorrect results. Keep time-zone identifiers in configuration where the business rule requires them.

Testing configuration before release

Configuration tests should verify that the intended environment file is loaded and that higher-priority providers win. ConfigurationBuilder can create an in-memory configuration for unit tests, while integration tests can use temporary JSON files and environment variables.

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["Orders:ApiBaseUrl"] = "https://test.example",
        ["Orders:TimeoutSeconds"] = "15"
    })
    .Build();

var options = configuration
    .GetSection("Orders")
    .Get<OrdersOptions>();

Assert.Equal(15, options!.TimeoutSeconds);

A deployment pipeline should check that production has every required setting without printing its value. Health checks can verify connectivity to a database or external API, but they should avoid exposing connection strings in response bodies or logs. Treat missing configuration as a release failure rather than silently accepting an empty string.

The following patterns suit different operational needs:

Choosing a maintainable configuration strategy

A practical setup starts with conservative defaults in appsettings.json, adds small environment-specific overrides, and uses environment variables for deployment-time differences. Sensitive values should come from a secret manager, with managed identity preferred where the hosting platform supports it.

The startup path should be predictable: determine the environment, load the standard providers, bind important sections to typed options, validate them at startup and expose only safe operational information through diagnostics. This approach works for a laptop in Adelaide, an Azure App Service in Australia East or a container workload deployed to a Melbourne-based region.

Clear naming is as important as the code. Use Orders__ApiBaseUrl, ConnectionStrings__Orders and Logging__LogLevel__Default consistently across local scripts, GitHub Actions, Azure DevOps and production manifests. Keep a non-secret configuration reference alongside the application so developers and operations staff can see which settings exist, which are mandatory and which deployment system supplies them.