.NET Runtime on Windows App Service (.NET 8)¶

Runtime alignment is critical for startup reliability. This reference summarizes .NET 8 runtime settings, environment variables, web.config behavior, and startup conventions for this guide.

graph TD
    A[App Service Front End] --> B[IIS + ASP.NET Core Module]
    B -->|in-process| C1[w3wp.exe + IISHttpServer]
    B -->|out-of-process| C2[dotnet.exe + Kestrel]
    C1 --> D[GuideApi net8.0]
    C2 --> D
    E[HTTP_PLATFORM_PORT or PORT] --> C2
    F[App Settings and web.config] --> D

Runtime baseline in this repository¶

• Project SDK: Microsoft.NET.Sdk.Web
• Target framework: net8.0
• Core package: Microsoft.ApplicationInsights.AspNetCore
• Hosting path: Windows App Service with IIS + ASP.NET Core Module (in-process via IISHttpServer inside w3wp.exe, or out-of-process via Kestrel in a separate dotnet.exe; see Hosting Model)

GuideApi.csproj excerpt:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

Port and startup binding contract¶

Windows App Service commonly provides HTTP_PLATFORM_PORT to child process hosts.

Program.cs excerpt:

var port = Environment.GetEnvironmentVariable("HTTP_PLATFORM_PORT")
    ?? Environment.GetEnvironmentVariable("PORT")
    ?? "5000";

builder.WebHost.UseUrls($"http://+:{port}");

This pattern is safe for both App Service Windows and local fallback.

ASPNETCORE_ENVIRONMENT guidance¶

• Production slot: ASPNETCORE_ENVIRONMENT=Production
• Staging slot: ASPNETCORE_ENVIRONMENT=Staging (slot-sticky)
• Avoid Development in any internet-facing environment.

Set via CLI:

az webapp config appsettings set --resource-group $RESOURCE_GROUP_NAME --name $WEB_APP_NAME --settings ASPNETCORE_ENVIRONMENT=Production --output json

web.config on Windows App Service¶

For code deployment, dotnet publish may provide a web.config (generated or explicit) controlling process startup.

Typical concerns:

• processPath should be dotnet.
• arguments should reference the correct application DLL.
• Handler/module configuration must match expected runtime model.

Startup failures often come from mismatched arguments or missing published DLL.

Hosting Model: In-Process vs Out-of-Process¶

On Windows App Service, the ASP.NET Core Module (ANCM) can host your app in one of two models. The choice affects request latency, process topology, and which HTTP server is in front of your code.

In-process (default since .NET Core 3.0)

The ASP.NET Core Module loads the .NET runtime and your app directly inside the IIS worker process (w3wp.exe). HTTP requests are handed off to your app via IISHttpServer — Kestrel is not used in this mode. There is one process and one HTTP listener (HTTP.sys via IIS).

• Lower request latency — no inter-process hop between IIS and a separate .NET process.
• Higher per-worker throughput.
• dotnet.exe is not spawned; the app runs inside w3wp.exe.

Out-of-process

The ASP.NET Core Module spawns a separate dotnet.exe process that runs Kestrel, then reverse-proxies requests from IIS to Kestrel over localhost.

• Useful when you specifically need Kestrel features that cannot run inside w3wp.exe.
• Required for some scenarios that depend on a separate Kestrel process being addressable.
• Adds one IIS-to-Kestrel reverse-proxy hop per request.

Set the model via web.config

The hosting model is selected by the hostingModel attribute on the <aspNetCore> element. Setting it explicitly avoids relying on SDK defaults:

<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet"
                arguments=".\GuideApi.dll"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout"
                hostingModel="inprocess" />
  </system.webServer>
</configuration>

Valid hostingModel values: inprocess or outofprocess.

You can also pin the hosting model in the project file so dotnet publish emits the right web.config:

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

Kestrel runtime settings¶

Kestrel is your HTTP server runtime in out-of-process hosting (where IIS reverse-proxies to a separate dotnet.exe running Kestrel). In in-process hosting, the HTTP server is IISHttpServer instead of Kestrel — ConfigureKestrel(...) calls have no effect in that mode. Use ConfigureIISServerOptions(...) to tune the in-process server instead.

Common Kestrel tune points (out-of-process only):

• Request limits (MaxRequestBodySize) when needed.
• Keep-alive and header timeouts for abuse resilience.
• HTTPS redirection policies (while TLS terminates upstream).

builder.WebHost.ConfigureKestrel(options =>
{
    options.AddServerHeader = false;
});

Startup command notes¶

For standard .NET code deployments, App Service starts from site configuration and artifact metadata; custom startup commands are less common than container scenarios.

If custom startup is used, validate it does not conflict with handler/module startup path.

Runtime verification commands¶

az webapp config show --resource-group $RESOURCE_GROUP_NAME --name $WEB_APP_NAME --output json
az webapp list-runtimes --os windows --output table
az webapp show --resource-group $RESOURCE_GROUP_NAME --name $WEB_APP_NAME --output json

Production runtime checklist¶

• Target framework and platform runtime align.
• HTTP_PLATFORM_PORT binding logic present.
• ASPNETCORE_ENVIRONMENT explicitly set per slot.
• Health endpoint configured and responsive.
• Startup logs clean after restart and slot swap.

Common runtime failure signatures¶

.NET on Linux App Service: Key Differences¶

This document focuses on Windows App Service, where IIS hosts ASP.NET Core apps via the ASP.NET Core Module — the HTTP server depends on the chosen hosting model (IISHttpServer in-process inside w3wp.exe, or Kestrel in a separate dotnet.exe for out-of-process). .NET also runs on Linux App Service, but the hosting model is different: there is no IIS, no ASP.NET Core Module, and web.config is not consulted. Use this section to understand the differences if you deploy to Linux.

Linux runtime stack identifier:

az webapp config set \
  --resource-group $RESOURCE_GROUP_NAME \
  --name $WEB_APP_NAME \
  --linux-fx-version "DOTNETCORE|8.0" \
  --output json

Linux port binding pattern (no HTTP_PLATFORM_PORT involvement):

var port = Environment.GetEnvironmentVariable("PORT") ?? "8080";
builder.WebHost.UseUrls($"http://+:{port}");

The HTTP_PLATFORM_PORT fallback shown in Port and startup binding contract is harmless on Linux — HTTP_PLATFORM_PORT is simply not set, so the lookup falls through to PORT. The same Program.cs snippet works on both Windows and Linux.

Run It in the Portal¶

Portal view: Environment variables blade (where ASPNETCORE_ENVIRONMENT is managed)¶

The Environment variables blade with the App settings tab selected is the Portal surface where App Service app settings are managed. In this screenshot, the visible table columns are Name, Value, Deployment slot setting, Source, and Delete, and the toolbar exposes Add, Refresh, Show values, Advanced edit, and Pull reference values. Use the highlighted Environment variables entry in the left navigation to reach this blade when reviewing runtime configuration for the ASP.NET Core app.

See Also¶

• 01. Local Run
• 02. First Deploy
• Troubleshooting
• CLI Cheatsheet
• Concepts: How App Service Works

Sources¶

• Microsoft Learn source 1