Portal Community
Environments

Environment Configuration

ASPNETCORE_ENVIRONMENT is the single variable that controls which environment the app runs in — and which config files it loads.

Standard Environments

NameUseWho sets it
DevelopmentDeveloper machineslaunchSettings.json
StagingPre-production / QA serversDeployment pipeline
ProductionLive customer serversDeployment pipeline / system env var

How to Set It

launchSettings.json — local development (preferred)

Already set for you in the repository. Only used by dotnet run and Visual Studio. Never deployed. Safe to commit. 

{
  "profiles": {
    "BizFirst.Ai.Consolidated.WebApi": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "TENANT_CODE": "bizfirst"
      },
      "applicationUrl": "https://localhost:10001;http://localhost:5001"
    }
  }
}

PowerShell — temporary terminal override

$env:ASPNETCORE_ENVIRONMENT = "Staging"
$env:TENANT_CODE = "apexretail"
dotnet run

Lasts for the current terminal session only.

Windows System Environment Variable — persistent machine override

Search "Environment Variables" → System Properties → Environment Variables → System variables → New:

VariableValue
ASPNETCORE_ENVIRONMENTDevelopment
TENANT_CODEapexretail

Docker / Container

# Dockerfile
ENV ASPNETCORE_ENVIRONMENT=Production
ENV TENANT_CODE=apexretail

# docker-compose.yml
environment:
  - ASPNETCORE_ENVIRONMENT=Production
  - TENANT_CODE=apexretail

Files Loaded Per Environment

EnvironmentFiles loaded (in order)
Development appsettings.json
appsettings.Development.json
appsettings.Development.Local.json (optional)
appsettings.Tenant.{code}.json (if TENANT_CODE set)
appsettings.Tenant.{code}.development.json (if TENANT_CODE set)
Staging appsettings.json
appsettings.Staging.json
appsettings.Staging.Local.json (optional)
appsettings.Tenant.{code}.json (if TENANT_CODE set)
appsettings.Tenant.{code}.staging.json (if TENANT_CODE set)
Production appsettings.json
appsettings.Production.json
(no Local file — servers don't have one)
appsettings.Tenant.{code}.json (if TENANT_CODE set)
appsettings.Tenant.{code}.production.json (if TENANT_CODE set)

PlatformSettings.Environment.Name

At startup, WebApplicationHelper stores the environment name as a lowercase string into PlatformSettings.Environment.Name. This is what drives the file name token: 

PlatformSettings.Environment.Name = (builder.Environment.EnvironmentName ?? "production").ToLower();
// "Development" → "development"
// "Staging"     → "staging"
// "Production"  → "production"
Case sensitivity The {env} token in file names is lowercased. On Linux containers, file names are case-sensitive. Name your tenant env files with lowercase: appsettings.Tenant.apexretail.production.json, not Production.json.

Recommended File Matrix

FileDevStagingProdCommit?
appsettings.json✓✓✓Yes
appsettings.Development.json✓Yes
appsettings.Staging.json✓Yes
appsettings.Production.json✓Yes
appsettings.Development.Local.json✓Never
appsettings.Staging.Local.json✓Never
← Local Setup Next: Tenant Configuration →