skip to content

Servers & Hosting

How requests reach an ASP.NET Core app: Kestrel endpoints and limits, IIS through the ASP.NET Core Module, forwarded headers behind a proxy, and graceful shutdown. A staple of deployment questions.

part ofASP.NET Coreread it →
on this pageshow

explore

questions

19

When an ASP.NET Core 10 app is published for IIS, what does the generated web.config tell IIS, and which component acts on it?

level: juniorimportance: must knowfreq 50%

answer

  1. not where app settings live
  2. a handler for every path and verb
  3. AspNetCoreModuleV2 from the Hosting Bundle
  4. processPath, arguments, hostingModel
  5. stdoutLogEnabled="false" by default

basics

~20 s

It registers the ASP.NET Core Module (AspNetCoreModuleV2) as the handler for every request and, in its aspNetCore element, tells that module how to start the app: processPath and arguments, the hosting model (inprocess by default) and stdout logging.

solid answer

~30 s

IIS knows nothing about .NET on its own, so publish writes a `web.config` whose only real job is to hand requests to the **ASP.NET Core Module (ANCM)**, a native IIS module installed by the .NET Hosting Bundle. Under `system.webServer`, a `handlers` entry named `aspNetCore` maps `path="*"` and `verb="*"` to `modules="AspNetCoreModuleV2"`. The `aspNetCore` element then configures the module: `processPath` (the app's `.exe` host, or `dotnet` with the DLL in `arguments`), `stdoutLogEnabled="false"` with `stdoutLogFile=".\logs\stdout"`, and `hostingModel="inprocess"`. Optional children carry `environmentVariables` and `handlerSettings`. Application settings still belong in `appsettings.json`; ASP.NET Core never reads `web.config` as configuration.

code

xml · 13 lines
xml
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\PermitPortal.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

go deeper

for a junior

Recall that publish writes web.config so IIS hands every request to the ASP.NET Core Module, and that app settings live in appsettings.json, not there.

for a middle

Explain the aspNetCore handler and element: processPath and arguments, hostingModel, stdout logging, and how publish transforms an existing web.config.

for a senior

Show how you diagnose a startup failure through stdout logs and the event log, and keep server-specific web.config additions under source control.

for a principal

Weigh standardising IIS servers on the Hosting Bundle against moving the workload to a self-hosted or container model, and who owns server provisioning.

## Why an ASP.NET Core app needs a web.config at all ASP.NET Core apps are console processes that host their own server. IIS, by contrast, is a Windows web server built around native modules and handlers. The bridge between the two is the **ASP.NET Core Module (ANCM)**, a native IIS module that the **.NET Hosting Bundle** installs together with the .NET and ASP.NET Core runtimes. IIS only uses ANCM for a site if that site's configuration says so, and the place IIS reads site configuration from is `web.config` in the content root. That is why `dotnet publish` of a project using `Microsoft.NET.Sdk.Web` writes a `web.config` into the publish folder, even though the app itself never reads it. ## What publish writes For a framework-dependent app named `PermitPortal` the generated file looks like this: ```xml <configuration> <location path="." inheritInChildApplications="false"> <system.webServer> <handlers> <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> </handlers> <aspNetCore processPath=".\PermitPortal.exe" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" /> </system.webServer> </location> </configuration> ``` Piece by piece: - **The handler** named `aspNetCore` matches every path and verb and points at `AspNetCoreModuleV2`, so every request to the site goes to ANCM rather than to IIS's static file or ASP.NET handlers. - **`processPath` / `arguments`** say what to start. With an app host it is `.\PermitPortal.exe`; without one it is `dotnet` with `.\PermitPortal.dll` in `arguments`. - **`hostingModel`** is `inprocess` because the SDK's `AspNetCoreHostingModel` property defaults to it for .NET Core 3.0 and later. - **`stdoutLogEnabled`** is `false`, with `stdoutLogFile` prepared as `.\logs\stdout`. Turning it on temporarily is the classic way to see why an app fails at startup. If the project already contains a `web.config`, publish **transforms** it rather than replacing it: it fills in the handler and the `aspNetCore` attributes and keeps what you added, such as `requestFiltering` limits or extra `environmentVariables`. Setting the MSBuild property `IsTransformWebConfigDisabled` to `true` stops the transform entirely. ## Environment variables and handler settings Two optional children of the `aspNetCore` element are worth knowing: - **`environmentVariables`** lists `environmentVariable` entries that ANCM sets for the app before it starts. Publishing with `-p:EnvironmentName=Staging` makes the transform write an `ASPNETCORE_ENVIRONMENT` entry with that value, which is how one build is pointed at a different environment on a given server. - **`handlerSettings`** carries `handlerSetting` name/value pairs that tune ANCM itself, such as `shutdownDelay` or the shadow-copy settings, without touching the app. Both are read by ANCM, not by ASP.NET Core's configuration system; the app only sees the resulting environment variables. ## What ANCM does with it 1. IIS receives a request for the site and finds the `aspNetCore` handler. 2. ANCM reads the `aspNetCore` element. On the first request it starts the app: in-process it loads the .NET runtime into the IIS worker process; out-of-process it launches `processPath` as a separate process. 3. ANCM forwards the request to the running app and returns its response through IIS. 4. It also watches the app folder for `app_offline.htm` and restarts the app when `web.config` changes. Other attributes ANCM understands, with their schema defaults: | Attribute | Default | Purpose | |---|---|---| | `startupTimeLimit` | 120 s | how long the app may take to start | | `shutdownTimeLimit` | 10 s | how long ANCM waits for a graceful stop | | `rapidFailsPerMinute` | 10 | crash limit before ANCM stops restarting (out-of-process) | | `requestTimeout` | 2 minutes | forwarded-request timeout (out-of-process) | | `disableStartUpErrorPage` | false | hide ANCM's own startup error page | ## What web.config is not - It is **not** application configuration. `ConfigurationBuilder` never reads it; settings go in `appsettings.json`, environment variables or other providers. Environment variables placed under `<environmentVariables>` are the one bridge: ANCM sets them for the app process. - It is **not** needed when the app runs behind another server, in a container, or as a service. Kestrel ignores it. - It is **not** written by hand in the common case; the SDK regenerates the ANCM parts on every publish. ## Why the Hosting Bundle matters If ANCM is not installed, IIS cannot load `AspNetCoreModuleV2` and the site fails with a configuration error before any .NET code runs. Installing the Hosting Bundle (running its installer again if IIS was added afterwards, and restarting IIS) is the first check for a newly provisioned server.

  • How do you see why an ASP.NET Core app returns an ANCM startup error page under IIS?
    Set `stdoutLogEnabled="true"` in the published `web.config` (the `logs` folder must be writable by the app pool identity), reproduce the failure and read the stdout log; the Windows Application event log also carries ANCM's entries. Turn stdout logging off again afterwards, because the files are not rotated.
  • Does ASP.NET Core read connection strings or app settings from web.config?
    No. The configuration system reads `appsettings.json`, environment variables, command-line arguments and other registered providers. Only the `environmentVariables` under the `aspNetCore` element reach the app, because ANCM sets them on the process before it starts.
  • What happens to your own additions to web.config when you publish again?
    If the project contains a `web.config`, publish transforms that file: it sets the handler and the `aspNetCore` attributes it owns and keeps everything else. A `hostingModel` you set explicitly in the project's file is also preserved.

  • web.config is where ASP.NET Core reads its configuration settings.
  • IIS runs ASP.NET Core apps without any extra module installed.
  • Publish replaces any web.config in the project with a fresh one.
  • stdoutLogEnabled should stay true in production for diagnostics.
  • Kestrel needs web.config to start outside IIS.
open as a page

In ASP.NET Core 10, which address does Kestrel listen on when nothing configures a URL, and how do you make it accept connections from other machines?

level: juniorimportance: must knowfreq 62%

basics

~10 s

With no URL, port or endpoint configured, Kestrel binds http://localhost:5000: plain HTTP on the IPv4 and IPv6 loopback addresses only. To accept other machines, bind every interface, for example ASPNETCORE_URLS=http://+:5000, HTTP_PORTS=5000 or ListenAnyIP(5000).

open as a page

Behind a TLS-terminating load balancer, why does an ASP.NET Core app log the balancer's IP and build http:// links, and what does UseForwardedHeaders change?

level: juniorimportance: must knowfreq 55%

basics

~20 s

Kestrel only sees the balancer's plain-HTTP connection, so RemoteIpAddress is the balancer and Scheme is http. UseForwardedHeaders, told to process X-Forwarded-For and X-Forwarded-Proto from a trusted proxy, writes the client's IP and https scheme back onto HttpContext.

open as a page

When a container sends SIGTERM to an ASP.NET Core 10 API mid-traffic, what is the shutdown sequence, and what do in-flight requests experience?

level: middleimportance: must knowfreq 50%

basics

~10 s

SIGTERM triggers StopApplication: ApplicationStopping fires, Kestrel stops accepting connections and lets in-flight requests finish, for up to HostOptions.ShutdownTimeout (30 seconds). Requests still running then have their connections aborted; hosted services stop and ApplicationStopped fires.

open as a page

In ASP.NET Core, how do you run code when the app starts and when it shuts down, and how can code request a graceful stop?

level: juniorimportance: should knowfreq 40%

basics

~10 s

Use IHostApplicationLifetime (app.Lifetime in Program.cs): register callbacks on its ApplicationStarted, ApplicationStopping and ApplicationStopped cancellation tokens. Calling StopApplication() triggers ApplicationStopping and the same graceful shutdown that Ctrl+C or SIGTERM starts.

open as a page

In an IIS-hosted ASP.NET Core 10 project, what does AspNetCoreHostingModel=OutOfProcess change in web.config and in the server that handles requests?

level: middleimportance: should knowfreq 42%

basics

~10 s

Publish writes hostingModel="outofprocess" instead of the default inprocess. ANCM then starts the app as its own process and proxies to Kestrel on http://127.0.0.1:<port>, so IISOptions and Kestrel limits apply instead of IISHttpServer and IISServerOptions.

open as a page

A building-permit portal on ASP.NET Core 10, hosted in-process by IIS, raises IISServerOptions.MaxRequestBodySize, yet 40 MB plan uploads are still rejected; why?

level: middleimportance: should knowfreq 38%

basics

~20 s

IIS request filtering rejects the upload first: its maxAllowedContentLength defaults to 30,000,000 bytes, and IISServerOptions cannot raise it. Raise requestLimits maxAllowedContentLength in web.config as well; ASP.NET Core logs a warning when its limit exceeds IIS's.

open as a page

In ASP.NET Core 10, when ASPNETCORE_URLS, ASPNETCORE_HTTP_PORTS and a Kestrel:Endpoints section are all set, which addresses does Kestrel bind?

level: middleimportance: should knowfreq 45%

basics

~10 s

Only the Kestrel:Endpoints entries. Endpoints from configuration or ConfigureKestrel override the address list and Kestrel logs a warning; within that list, urls (ASPNETCORE_URLS, --urls) beats HTTP_PORTS/HTTPS_PORTS. PreferHostingUrls=true reverses the first rule.

open as a page

In ASP.NET Core 10's Kestrel:Endpoints configuration, how do you serve a different TLS certificate per host name on one HTTPS port, and what happens when nothing matches?

level: middleimportance: should knowfreq 30%

basics

~20 s

Add an Sni section under the endpoint, keyed by host name, each with its own Certificate (and optionally Protocols, SslProtocols, ClientCertificateMode). Kestrel tries an exact name, then the longest .suffix, then ""; with no match it refuses the TLS handshake.

open as a page

In ASP.NET Core, what exactly does setting ASPNETCORE_FORWARDEDHEADERS_ENABLED=true configure, and when is it unsafe to use?

level: middleimportance: should knowfreq 28%

basics

~20 s

It adds UseForwardedHeaders at the very start of the pipeline, processes X-Forwarded-For and X-Forwarded-Proto, and clears KnownProxies and KnownIPNetworks so every sender is trusted. That is unsafe whenever clients can reach Kestrel without passing the proxy.

open as a page

In ASP.NET Core 10, which senders does the forwarded headers middleware trust by default, and how do you trust a load balancer subnet without KnownNetworks?

level: middleimportance: should knowfreq 45%

basics

~20 s

Only loopback senders: KnownProxies holds ::1 and KnownIPNetworks holds 127.0.0.0/8, so headers from a balancer elsewhere are ignored. Add its address to KnownProxies or its subnet, as a System.Net.IPNetwork, to KnownIPNetworks; KnownNetworks is obsolete in 10 (ASPDEPR005).

open as a page

When a proxy publishes an ASP.NET Core app under /lifts, how do UsePathBase and X-Forwarded-Prefix keep routing and generated links correct?

level: middleimportance: should knowfreq 35%

basics

~20 s

If the proxy forwards /lifts/..., UsePathBase("/lifts") moves the prefix from Request.Path to Request.PathBase so routes match and links include it. If the proxy strips it, enable XForwardedPrefix so X-Forwarded-Prefix sets PathBase from a trusted proxy.

open as a page

Deploying a new build of an ASP.NET Core 10 app on IIS fails with locked files and brief 503s; how do app_offline.htm, shadow copying and ANCM's shutdownDelay each help?

level: seniorimportance: should knowfreq 32%

basics

~20 s

app_offline.htm makes ANCM stop the app and answer 503 with that page until it is deleted, freeing the files. Shadow copying runs the app from a copy. shutdownDelay, 1 s by default since .NET 9, narrows the recycle race behind 503s.

open as a page

An ASP.NET Core 10 telemetry ingest sets Kestrel's MaxRequestBodySize and MinRequestBodyDataRate to null so large, slow device uploads stop failing; what defaults did that remove, and what would you do instead?

level: seniorimportance: should knowfreq 40%

basics

~20 s

It removed the 30,000,000-byte body cap (413 when exceeded) and the 240 bytes/s minimum upload rate after a 5-second grace (408). Instead, raise the body cap for the upload endpoint only, relax the rate without removing it, and cap connections.

open as a page

During ASP.NET Core shutdown, why doesn't HttpContext.RequestAborted fire for in-flight requests, and when should an endpoint watch ApplicationStopping instead?

level: seniorimportance: should knowfreq 30%

basics

~20 s

RequestAborted means this request's connection is gone, which during shutdown only happens when Kestrel aborts at the ShutdownTimeout. Open-ended endpoints such as streams or long polls should also watch ApplicationStopping and end cleanly; short transactional requests should simply finish.

open as a page

An ASP.NET Core 10 service always takes 30 seconds to stop and sometimes loses work on redeploy; how do HostOptions.ShutdownTimeout and the stop order explain it, and what do you change?

level: seniorimportance: should knowfreq 32%

basics

~20 s

A stop lasting exactly 30 seconds means something consumed HostOptions.ShutdownTimeout: an open request, a blocking stopping callback or a hosted service. Lost work means that budget, or the platform's kill deadline, ran out. Fix the holder, then size the timeout.

open as a page

Behind a CDN and a load balancer, how do ASP.NET Core's ForwardLimit and trust lists pick the X-Forwarded-For entry that becomes RemoteIpAddress, and how can it be spoofed?

level: seniorimportance: should knowfreq 35%

basics

~20 s

The middleware reads X-Forwarded-For right to left, one entry per hop, while the current sender is trusted and ForwardLimit (default 1) allows. Two proxies need ForwardLimit 2 and both trusted; empty trust lists with no limit let a forged leftmost entry win.

open as a page

When would you run an ASP.NET Core 10 app on HTTP.sys with UseHttpSys instead of Kestrel, and what must be configured outside the app for it?

level: middleimportance: nice to knowfreq 18%

basics

~20 s

Choose HTTP.sys on Windows when you need what the kernel driver offers without IIS: kernel-mode Windows authentication (Kerberos), port sharing between processes, kernel response caching, request queue delegation. URL reservations and TLS certificates are registered with netsh, not in the app.

open as a page

An ASP.NET Core 10 Kestrel endpoint sets Protocols to Http1AndHttp2AndHttp3, yet clients only ever use HTTP/1.1; what must be true for Kestrel to serve HTTP/2 and HTTP/3?

level: seniorimportance: nice to knowfreq 22%

basics

~20 s

The endpoint must use TLS: without it, Kestrel serves HTTP/1.1 and logs that HTTP/2 and HTTP/3 are disabled. HTTP/3 additionally needs a QUIC-capable platform (MsQuic), the same port open for UDP, and clients learning of it through the alt-svc header.

open as a page