Configuring Environments in ASP.NET Core

An environment in ASP.NET Core is the context in which an application runs and allows changing its configuration and behavior depending on whether we are in development, testing, or production.

This allows us to adapt the application’s behavior: debug locally, test changes in staging, and apply stricter configuration in production. Because running an API on your local machine is one thing, but deploying it on a server with real users watching is quite another.

Common Environments

ASP.NET Core allows using any environment name, but three names appear constantly:

If no environment is configured, ASP.NET Core assumes Production by default. This makes sense, as it’s preferable to start in safe mode rather than showing an error page with all internal details.

Environment Variables

The environment is typically set via an environment variable. The most common one in ASP.NET Core applications is ASPNETCORE_ENVIRONMENT.

$env:ASPNETCORE_ENVIRONMENT="Development"

On Linux or macOS:

export ASPNETCORE_ENVIRONMENT=Development

There is also DOTNET_ENVIRONMENT, which applies to the .NET generic host. In modern projects using WebApplication.CreateBuilder, it’s best to not define both with different values, otherwise you’re asking for an entertaining afternoon of diagnosis.

launchSettings.json

When working locally, Visual Studio, Rider, or dotnet run can use the Properties/launchSettings.json file. This file is intended for local development and is not published with the application.

{
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

We can run a specific profile from the CLI:

dotnet run --launch-profile Staging

To ignore local profiles and use what’s set in the console:

dotnet run --no-launch-profile

Environment-specific appsettings

ASP.NET loads configuration files specific to the environment. The pattern is:

appsettings.{Environment}.json

For example:

appsettings.json
appsettings.Development.json
appsettings.Staging.json
appsettings.Production.json

The idea is simple: appsettings.json contains the base configuration, and the environment-specific file overrides the keys that need changing.

appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=prod-sql;Database=MiApp;..."
  }
}

appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.EntityFrameworkCore": "Information"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MiAppDev;..."
  }
}

Priority Order

Configuration in ASP.NET Core comes from multiple sources. In the default setup, the usual order is:

The key rule is: if the same key appears in multiple places, the source with higher priority wins.

That’s why an environment variable can override a value from appsettings.json, and a command-line argument can override almost everything before it.

Changing Behavior by Environment

Sometimes changing configuration values is not enough. We might also want to enable or disable parts of the pipeline based on the environment.

A typical example is in Program.cs:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.Run();

In development, we show a detailed error page. In production, we use a safe handler and enable HSTS.

We can also check for custom environments:

if (app.Environment.IsEnvironment("Testing"))
{
    // Specific configuration for automated tests
}

Custom environments are valid. Just be consistent with the names and create the corresponding configuration files, like appsettings.Testing.json.

Setting the Environment in Production

In production, the environment is usually configured from the deployment platform.

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 8080

ENV ASPNETCORE_ENVIRONMENT=Production

docker run -e ASPNETCORE_ENVIRONMENT=Production my-app

services:
  web:
    image: my-app
    environment:
      - ASPNETCORE_ENVIRONMENT=Production