Environment Configuration in Flow
How the Flow ASP.NET Core API is configured across environments, described at the level of the standard ASP.NET Core pattern it follows.
This page describes the general ASP.NET Core configuration pattern that Flow follows as a
standard ASP.NET Core Web API project. Where specific file names or settings weren't independently
verified against Flow's own repository, they're presented as "the standard ASP.NET Core convention,"
not as a confirmed inventory of Flow's exact files — avoid treating this page as a full audit of
Flow's appsettings*.json contents.
The Layered Configuration Pattern
ASP.NET Core Web API projects build their configuration from an ordered set of sources, each layer able to override values from the layer before it:
appsettings.json— base settings shared by every environment.appsettings.{ASPNETCORE_ENVIRONMENT}.json— an overlay file loaded only for the current environment (e.g.appsettings.Development.json,appsettings.Production.json), merged on top of the base file.- Actual OS/container environment variables — typically override anything from the JSON files.
- Command-line arguments passed at process startup — highest precedence.
Conceptual layering — Program.csvar builder = WebApplication.CreateBuilder(args);
// builder.Configuration is now the merge of:
// appsettings.json
// appsettings.{ASPNETCORE_ENVIRONMENT}.json
// environment variables
// command-line args
var app = builder.Build();
Deciding Which Overlay File Loads: ASPNETCORE_ENVIRONMENT
The environment variable ASPNETCORE_ENVIRONMENT is read once, at process startup, and
determines which appsettings.{Environment}.json overlay gets merged in. It's typically
set through the hosting environment — a launch profile locally, a container's environment variables in
a deployed setting, an App Service configuration setting on a PaaS host, and so on. Common values are
Development, Staging, and Production, though any string can be
used as long as a matching overlay file (or none, which simply means "use the base file only") exists.
Each layer can override the ones before it. Environment variables and command-line args typically take precedence over JSON files.
Runtime Reload Capability
Unlike a React bundle, a running .NET process can pick up certain configuration changes without a
restart. ASP.NET Core's JSON configuration provider supports a reloadOnChange option that
watches the underlying file and re-merges values into IConfiguration when it changes —
useful for adjusting things like log levels or feature flags on a live process. Not every setting is
safe to hot-swap this way (e.g. a database connection pool typically isn't rebuilt just because the
connection string setting changed), but the mechanism for detecting the change without
restarting exists at the configuration layer, which has no equivalent at all on the React/Vite side —
see Chapter 1.3 for that
contrast.
Summary
| Concept | How Flow (as a standard ASP.NET Core API) handles it |
|---|---|
| Environment signal | ASPNETCORE_ENVIRONMENT, read once at startup |
| Base config | appsettings.json |
| Per-environment overlay | appsettings.{Environment}.json |
| Highest-precedence source | Command-line arguments, then OS/container env vars |
| Change without rebuild? | Yes — restart the process (or hot-reload for supported providers) |