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?
answer
- not where app settings live
- a handler for every path and verb
- AspNetCoreModuleV2 from the Hosting Bundle
- processPath, arguments, hostingModel
- stdoutLogEnabled="false" by default
basics
~20 sIt 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 sIIS 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<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
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.
Explain the aspNetCore handler and element: processPath and arguments, hostingModel, stdout logging, and how publish transforms an existing web.config.
Show how you diagnose a startup failure through stdout logs and the event log, and keep server-specific web.config additions under source control.
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.