Configuration
Configuration is the framework's default chain, its files read from the content root:
appsettings.json, then appsettings.{Environment}.json, then {ApplicationName}.settings.json and
{ApplicationName}.settings.{Environment}.json — named after the entry assembly; the web service
ships no such file — then environment variables, then command-line arguments. A project hosting the
web service can add sources of its own; see
Hosting from another project. The keys this host reads are:
| Key | What it controls |
|---|---|
Logging:LogLevel |
the console provider's levels |
Logging:File:LogLevel |
the log file's levels, over the defaults the host seeds in code |
Logging:File:Directory |
the log file's directory; logs under the working directory by default |
Logging:File:RetainDays |
how many days of this instance's log files are kept; 30 by default, 0 keeps all |
AllowedHosts |
host filtering; absent from the shipped file. While the login gate is off and the key names no host but the loopback ones — it is not set, or lists only localhost, 127.0.0.1, [::1] or ::1 — the host admits only the loopback names localhost, 127.0.0.1 and [::1], and answers a connection from another computer that writes one of them, or no Host, 403 (Answering This Computer Only); with the gate on, or once the key names another host or *, the framework's own rule applies — the configured names, or any name when none is configured |
Kestrel:Endpoints |
the addresses the server binds |
ProxyConfig:AdminDirectory |
the admin working root, under which Resource and Cache live |
Auth |
the optional login gate, and the name of its cookie, Auth:CookieName; off as shipped, on in the Development overlay |
HiNC:CacheDbId |
an explicit step-cache database id, overriding the environment name |
HiNC:LicenseCapsForTest |
<N>,<stepCap>: tightens the two licence caps once at boot — the resolution cap ratio and the step cap, a 0 leaving that cap as it is — so an acceptance instance runs under a cap. Tighten-only: it never loosens what the licence source set, and no endpoint sets a cap at runtime. The start-up log names the caps in force, at Warning when the switch took and at Error when it did not |
The Development overlay repeats the logging and admin-directory sections — its logging section adding
two Logging:File:LogLevel keys of its own — and turns the login gate on with one credential entry,
where the shipped file leaves it off. Because that entry is public, it also sets AllowedHosts to the
three loopback names, which the gate-on default would otherwise open to any name; an instance started
there with the gate turned off (Auth__Enabled=false) answers this computer only, as with no key at
all. It declares no
Kestrel section, so the listening address is the same under either environment.
Kestrel Endpoints Win
Kestrel:Endpoints is the authoritative source of the listening address. When it declares endpoints,
Kestrel binds those and ignores addresses supplied any other way — ASPNETCORE_URLS, --urls,
and the launch profile's applicationUrl alike — logging that it is overriding them. The shipped
configuration declares one HTTP endpoint on loopback port 5000. The http launch profile names the
same address, so the override is invisible there; the https profile also names an HTTPS address on
a second port, and that address is one of the ones Kestrel discards, so launching under it still
yields plain HTTP on 5000 and nothing else.
To move a local instance to another port, set the Kestrel__Endpoints__Http__Url environment
variable, which the environment-variable provider maps onto the same key. Setting ASPNETCORE_URLS
alone changes nothing.
The endpoint binds localhost, so the shipped configuration answers only on the machine it runs on.
Reaching it from elsewhere means either overriding that key or placing a reverse proxy in front,
which is the arrangement the forwarded-headers configuration handles. Either way the login gate, off
as shipped, has to be turned on. Until it is, a widened endpoint answers its callers from elsewhere
400 when they write another host name (the loopback-only host list) and 403 when they write a
loopback name or none (a connection that does not come from this machine) — a browser reaching an
instance in a container or a virtual machine through a forwarded port included — while a proxy on the same machine that forwards to localhost
connects from a loopback address and can pass every caller through with no session. Turning the
gate on lifts both, the host restriction unless the deployment sets AllowedHosts; with the gate
left off, an AllowedHosts naming another host, or *, lets every machine in with no session. A proxy has to mount the service at / — the SPA addresses the API,
the hubs and its own assets from the root — and pass WebSocket upgrades on. An HTTPS endpoint that
Kestrel serves itself needs its Certificate configured: without one, Kestrel falls back to the
ASP.NET Core development certificate, which only a development machine holds, and otherwise cannot
bind the endpoint, ending the process at start-up.
Environment and Working Directory
The environment name reaches further here than usual. Both launch profiles set it to Development,
which selects the Development overlay, names the instance's log file, and —
unless HiNC:CacheDbId overrides it — names the step-cache database file.
Two paths follow the process's current working directory rather than the content root: the file
logger's directory, while Logging:File:Directory is relative or left at its logs default, and the
per-user preference file. An instance launched from the project directory finds both where they are
expected; one launched from elsewhere puts them beside wherever it was started. The web service never
moves its working directory itself. A project hosting it that keeps them in a folder of its own moves
the working directory before calling BuildApp, and sets ContentRootPath so that the settings files
and wwwroot are still read from the program folder. The installed HiNC keeps both in a data folder
of its own; see Installing HiNC on Windows.
Source Code Path
See HiNC App Anatomy for git repository links.
Web Application
HiNC-2025-webservice (Quasar CLI SPA):
Program.cs— the host-filtering default that follows the login gate.Common/LocalConnectionGuard.cs— the condition the host-filtering default reads, and the gate-off check of the connection's own address that goes with it.appsettings.json— the shipped listening address, the admin directory and the login section (off, no account); noAllowedHostskey.appsettings.Development.json— the Development overlay, which declares noKestrelsection, the login section that turns the gate on with one account, andAllowedHostsat the three loopback names.Properties/launchSettings.json— the two launch profiles whoseapplicationUrltheKestrelsection overrides.
See Also
- Program and Hosting — the host that reads these keys: the pipeline, the login gate and the address they change
- Hosting from another project — adding configuration sources, and the content root and working directory a hosting project sets
- Logging — the file and console levels the
Loggingkeys in this table set - The step-cache file — the step-cache file
HiNC:CacheDbIdnames