Table of Contents

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); no AllowedHosts key.
  • appsettings.Development.json — the Development overlay, which declares no Kestrel section, the login section that turns the gate on with one account, and AllowedHosts at the three loopback names.
  • Properties/launchSettings.json — the two launch profiles whose applicationUrl the Kestrel section 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 Logging keys in this table set
  • The step-cache file — the step-cache file HiNC:CacheDbId names