Environments

The defaults that make development pleasant are wrong in production, and the settings that make production safe make development miserable. Detailed error pages, a permissive local database, fake outbound integrations, verbose logging: all useful on your machine, all unacceptable on a live service.

The platform resolves that with one string. At start-up the host reads an environment name from an environment variable, exposes it through IHostEnvironment, and uses it to choose which appsettings file layers on top of the base one. Your own code reads the same value when behaviour needs to differ.

This is the intended mechanism, not a workaround. Branching on the environment name is how the platform expects one build to behave differently in different places, and inventing your own flag for the same job means two things to keep in step.

One detail is worth committing to memory: when the variable is not set at all, the environment is Production. The safe default applies when nobody has said anything, which is the right way round.

# One run, current shell (Linux, macOS)
DOTNET_ENVIRONMENT=Staging dotnet run

# Current session (Windows PowerShell)
$env:DOTNET_ENVIRONMENT = "Staging"
dotnet run

# A container, at the point it starts
docker run -e ASPNETCORE_ENVIRONMENT=Production anvi/employees-api:1.4.0

# Confirm what a running container was actually given
docker exec employees-api printenv ASPNETCORE_ENVIRONMENT

# Which environment did the application decide it was in?
dotnet run -- --Environment=Staging

• There is no single canonical place to set this. It is an environment variable, so it comes from wherever that machine gets environment variables: your shell, a container definition, an orchestrator manifest, a service configuration.
• On your machine it usually comes from launchSettings.json, which the dotnet run and editor launch profiles read. That file is a development convenience and is never used by a published application, so a value that works locally tells you nothing about a deployment.
• Checking the value on a running instance rather than assuming it is the single most useful habit in this lesson. Print it in a start-up log line so it is visible in the log rather than something you have to go and ask.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

if (builder.Environment.IsDevelopment())
{
    // No database and no real email on a laptop
    builder.Services.AddSingleton<IEmployeeStore, InMemoryEmployeeStore>();
    builder.Services.AddSingleton<INotificationSender, LoggingNotificationSender>();
}
else
{
    string connection = builder.Configuration.GetConnectionString("Employees")
        ?? throw new InvalidOperationException(
            "Connection string 'Employees' is required outside Development.");

    builder.Services.AddSingleton<IEmployeeStore>(_ => new PostgresEmployeeStore(connection));
    builder.Services.AddSingleton<INotificationSender, SmtpNotificationSender>();
}

using IHost host = builder.Build();
await host.RunAsync();

• The branch happens once, at start-up, while services are being registered. Everything downstream receives an IEmployeeStore and never asks which environment it is in — which keeps the environment check in one file instead of scattered through the application.
• The missing connection string throws rather than falling back to something local. Failing at start-up with a clear message beats starting successfully and writing production data somewhere unintended.
• IsDevelopment compares the name ignoring case, so DEVELOPMENT and development both match. It does not do anything clever with near misses — Dev matches nothing.
• There is a risk in this shape worth naming: the else branch is the one that runs in production and the if branch is the one you test all day. Keep the untested side small, and make sure staging exercises the same path production will.