The .NET Environment Variables I Actually Use (Windows, Linux, Docker, Azure)

Over the years shipping ASP.NET Core services, I've learned that a surprising amount of behavior hangs off a small set of environment variables. This page is my field guide: what I set, why I set it, and exactly how I wire it up on Windows, Linux, Docker/Kubernetes, and Azure App Service. Everything below is battle-tested in real deployments.

1. Choosing the environment

In modern minimal hosting, both ASPNETCORE_ENVIRONMENT and DOTNET_ENVIRONMENT work. In practice, I keep a simple rule: web apps use ASPNETCORE_ENVIRONMENT; non-web/background apps use DOTNET_ENVIRONMENT. I never set them to different values in the same process.

$env:ASPNETCORE_ENVIRONMENT = "Development"
dotnet run

export ASPNETCORE_ENVIRONMENT=Production
dotnet MyApp.dll

2. Binding URLs & ports

Two patterns I use:

Full URLs

ASPNETCORE_URLS="http://0.0.0.0:8080;https://0.0.0.0:8443"

Ports-only (my default in containers)

HTTP_PORTS=8080
HTTPS_PORTS=8443

These are shorthand for the equivalent ASPNETCORE_URLS values. In .NET 8 container images, the default HTTP port changed from 80 to 8080, which plays nicely with most PaaS platforms.

3. Configuration via env vars (nested keys)

Environment variables map to configuration keys. For nested keys, use __ (double underscore) in the variable name to represent a colon:

Logging__LogLevel__Default=Information
Kestrel__Endpoints__Http__Url=http://0.0.0.0:8080
Kestrel__Certificates__Default__Path=/certs/site.pfx
Kestrel__Certificates__Default__Password=changeit

4. Diagnostics on/off switches

For production hardening or incident response, I rely on these:

• DOTNET_EnableDiagnostics – master switch for debugger/profiler/EventPipe.
• DOTNET_DiagnosticPorts – sets the diagnostic port behavior (listen/connect, suspend).

# Disable attach and diagnostic IPC entirely
DOTNET_EnableDiagnostics=0

# Or fine-tune via Diagnostic Port (example)
DOTNET_DiagnosticPorts=/tmp/dotnet-diagnostic-01,suspend

Note: for .NET 8+, disabling diagnostics may also disable profilers; use with intent.

5. Globalization & ICU

When running in containers or minimal environments, culture data can add 20+ MB to your app size. For APIs that don't need localization:

DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1

This disables culture-specific formatting, but also breaks things like DateTime.Parse with culture-specific formats. Test thoroughly.

6. GC & performance knobs

For high-throughput services, I sometimes tune:

# Server GC (default in server scenarios)
DOTNET_gcServer=1

# Concurrent GC
DOTNET_gcConcurrent=1

# Retain VM for faster allocations
DOTNET_GCRetainVM=1

7. Container awareness

In Kubernetes with resource limits, help .NET detect container boundaries:

DOTNET_RUNNING_IN_CONTAINER=1

This makes .NET respect container memory limits when deciding GC behavior and ThreadPool sizing.

8. Hosting startup assemblies

For cross-cutting concerns (telemetry, monitoring), I sometimes use:

ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=MyApp.Observability

This loads the assembly at startup, allowing you to register services without modifying Program.cs.

9. Proxies & forwarded headers

Behind load balancers or reverse proxies:

ASPNETCORE_FORWARDEDHEADERS_ENABLED=true

This enables forwarded header middleware automatically, helping with HTTPS redirection and host detection.

10. How I set these (copy/paste)

Windows (PowerShell)

$env:ASPNETCORE_ENVIRONMENT = "Production"
$env:HTTP_PORTS = "8080"
$env:DOTNET_EnableDiagnostics = "0"
dotnet MyApp.dll

Linux (bash)

export ASPNETCORE_ENVIRONMENT=Production
export HTTP_PORTS=8080
export DOTNET_EnableDiagnostics=0
dotnet MyApp.dll

systemd service

[Unit]
Description=My ASP.NET Core App
After=network.target

[Service]
Type=notify
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=HTTP_PORTS=8080
Environment=DOTNET_EnableDiagnostics=0
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/dotnet MyApp.dll
Restart=always
RestartSec=10
User=www-data

[Install]
WantedBy=multi-user.target

Docker

docker run --rm -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e HTTP_PORTS=8080 \
  myregistry/myapp:latest

docker-compose

services:
  web:
    image: myregistry/myapp:latest
    environment:
      ASPNETCORE_ENVIRONMENT: "Production"
      HTTP_PORTS: "8080"
    ports:
      - "8080:8080"

Azure App Service (CLI)

az webapp config appsettings set -g MyRg -n myapp-prod \
  --settings ASPNETCORE_ENVIRONMENT=Production WEBSITES_PORT=8080

11. Pitfalls I keep seeing

• Precedence confusion: mixing DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT with different values.
• Assuming launchSettings.json works in prod: it's local-only. Use env vars or app settings.
• Forgetting __ for nested keys: e.g., Logging__LogLevel__Default.
• Azure custom containers not listening on the expected port: set WEBSITES_PORT or use the port variables.
• Invariant globalization surprises: only enable if you're sure you don't need culture data.

12. References

• Use multiple environments in ASP.NET Core
• Configuration in ASP.NET Core (env provider, __ mapping)
• Kestrel endpoints (URLS, HTTP_PORTS, HTTPS_PORTS)
• Default ASP.NET Core port changed to 8080 in container images
• Azure App Service: configure a custom container (WEBSITES_PORT)
• Configure an App Service app (App Settings become env vars)
• Forwarded headers & proxies in ASP.NET Core
• Debugging/profiling runtime config (diagnostics)
• Diagnostic Port details
• GC runtime config & env vars
• Globalization options & invariant mode
• .NET environment variables (runtime + CLI)

If you spot anything I should add (or a platform quirk I missed), feel free to reach out and I'll update this guide.