skip to content

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%

answer

  1. Windows-only kernel-mode driver
  2. Kerberos and port sharing without IIS
  3. UrlPrefixes and AuthenticationManager
  4. netsh http add urlacl / sslcert
  5. not usable behind ANCM

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.

solid answer

~40 s

`builder.WebHost.UseHttpSys(...)` replaces Kestrel with a server built on **HTTP.sys**, the Windows kernel-mode HTTP driver that IIS itself sits on. It is Windows-only and cannot be used with IIS or the ASP.NET Core Module. Pick it when the app is exposed without IIS but needs HTTP.sys features: kernel-mode **Windows authentication** with Kerberos (`options.Authentication.Schemes`), **port sharing** with other HTTP.sys listeners, kernel **response caching** (`EnableResponseCaching`, on by default), or request **queue** naming and delegation. Addresses go in `options.UrlPrefixes` or the usual `urls`; HTTPS certificates are bound to the IP and port with `netsh http add sslcert`, and non-administrator accounts need `netsh http add urlacl` reservations. Defaults worth knowing: `MaxRequestBodySize` 30,000,000 bytes, `RequestQueueLimit` 1000, `MaxConnections` `null` (the machine-wide setting), `AllowSynchronousIO` false.

code

csharp · 18 lines
csharp
using Microsoft.AspNetCore.Server.HttpSys;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseHttpSys(options =>
{
    options.UrlPrefixes.Add("https://+:443/review/");
    options.Authentication.Schemes =
        AuthenticationSchemes.Negotiate | AuthenticationSchemes.NTLM;
    options.Authentication.AllowAnonymous = false;
    options.RequestQueueLimit = 2000;           // default 1000
});

builder.Services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);

var app = builder.Build();
app.MapGet("/review/whoami", (HttpContext ctx) => ctx.User.Identity?.Name);
app.Run();

go deeper

for a junior

Recall that HTTP.sys is a Windows-only alternative to Kestrel, selected with UseHttpSys, and that Kestrel stays the default.

for a middle

Explain the features that justify HTTP.sys (Kerberos, port sharing, kernel caching, request queues), the main HttpSysOptions defaults, and the netsh urlacl and sslcert steps.

for a senior

Judge whether a Windows service should use HTTP.sys or Kestrel behind a proxy, and plan certificate binding and URL reservations in deployment automation.

for a principal

Weigh tying a workload to Windows-only HTTP.sys features against keeping it portable to Linux hosting, and who owns machine-level configuration.

## What HTTP.sys is **HTTP.sys** is a kernel-mode driver in Windows that accepts HTTP connections, parses requests and queues them for user-mode processes. IIS is built on it. ASP.NET Core ships a server, `Microsoft.AspNetCore.Server.HttpSys`, that listens through the same driver, so an app can use HTTP.sys directly without IIS: ```csharp using Microsoft.AspNetCore.Server.HttpSys; var builder = WebApplication.CreateBuilder(args); builder.WebHost.UseHttpSys(options => { options.UrlPrefixes.Add("https://review.example.com:443/"); options.Authentication.Schemes = AuthenticationSchemes.Negotiate | AuthenticationSchemes.NTLM; options.Authentication.AllowAnonymous = false; options.MaxConnections = 500; }); builder.Services.AddAuthentication(HttpSysDefaults.AuthenticationScheme); ``` `UseHttpSys` replaces Kestrel as the `IServer`. It runs only on Windows; on another OS the listener throws `PlatformNotSupportedException`. It is **not compatible with the ASP.NET Core Module**, so it cannot sit behind IIS or IIS Express. ## When it is the better choice Kestrel is the default and the right answer for most apps, including those behind IIS or a reverse proxy. HTTP.sys earns its place when the app is exposed directly on Windows and needs something Kestrel does not provide: - **Windows authentication with Kerberos in kernel mode.** HTTP.sys negotiates Negotiate/Kerberos and NTLM before the request reaches the app. For Kerberos, the SPN is registered for the host, because the machine account decrypts the ticket. - **Port sharing.** Several processes can listen on the same port under different URL prefixes, such as a back-office review tool on `/review` beside another service. - **Kernel-mode response caching** (`EnableResponseCaching`, default `true`) for responses with suitable `Cache-Control` headers. - **Request queues.** `RequestQueueName` and `RequestQueueMode` (`Create`, `Attach`, `CreateOrAttach`) let processes create or attach to named queues, and `IServerDelegationFeature` delegates requests to another queue. - **Direct file transmission** and a mature attack-surface hardening in the driver. For the building-permit organisation, the public portal stays on IIS; an internal plan-review service that must authenticate staff with Kerberos on a server without IIS is a reasonable HTTP.sys candidate. ## What lives outside the app Because HTTP.sys is an operating-system component, some configuration is done with `netsh` (administrator rights required): 1. **URL reservations.** An account that is not an administrator must have the URL prefix reserved for it: `netsh http add urlacl url=https://+:443/review/ user=DOMAIN\svc-review`. 2. **TLS certificates.** HTTP.sys does not load certificates from app configuration. You bind a certificate from the machine store to the IP and port: `netsh http add sslcert ipport=0.0.0.0:443 certhash=<thumbprint> appid={<guid>}`. For host-name bindings `hostnameport=` is used instead of `ipport=`. 3. **Firewall** rules for the port. This is the biggest operational difference from Kestrel, where certificates and endpoints are part of the app's configuration. ## `HttpSysOptions` defaults | Option | Default | Meaning | |---|---|---| | `UrlPrefixes` | empty | prefixes to register; overrides `urls` unless `PreferHostingUrls` is set | | `Authentication.Schemes` | `None` | Windows schemes HTTP.sys negotiates | | `Authentication.AllowAnonymous` | `true` | whether unauthenticated requests are allowed | | `MaxConnections` | `null` | `null` uses the machine-wide registry value; `-1` is unlimited | | `RequestQueueLimit` | 1000 | requests HTTP.sys queues before rejecting more; with the default `Http503Verbosity` of `Basic` the connection is reset rather than sent a 503 | | `MaxRequestBodySize` | 30,000,000 bytes | per-request override through `IHttpMaxRequestBodySizeFeature` | | `AllowSynchronousIO` | `false` | synchronous I/O throws unless enabled | | `EnableResponseCaching` | `true` | kernel-mode response cache | With no prefix and no `urls`, HTTP.sys falls back to `http://localhost:5000`, like Kestrel. ## Timeouts and addresses HTTP.sys enforces its own timeouts in the kernel, exposed through `options.Timeouts` (a `TimeoutManager`): `EntityBody`, `DrainEntityBody`, `RequestQueue`, `IdleConnection`, `HeaderWait` and `MinSendBytesPerSecond`. They play the role Kestrel's `KestrelServerLimits` timeouts play, but the values are applied to the driver's URL group rather than checked in managed code. Address precedence mirrors Kestrel: prefixes added to `UrlPrefixes` override the `urls` setting (with an "Overriding address(es)" log entry) unless `PreferHostingUrls` is true, and with neither, the server binds `http://localhost:5000`. ## Trade-offs - Windows-only, so the app cannot move to Linux containers without switching servers. - Certificates and reservations live in machine state, which deployment automation has to manage. - HTTP/2 support depends on the Windows version (Windows Server 2016 / Windows 10 or later for HTTP/2 over TLS), not on the app. - Kestrel's richer in-app configuration (endpoints, SNI, limits) does not apply.

  • Can you use UseHttpSys for an app hosted in IIS to get kernel-mode Windows authentication?
    No. HTTP.sys is not compatible with the ASP.NET Core Module, so it cannot run behind IIS or IIS Express. Under IIS the app uses IIS's own Windows authentication through `IISServerOptions` (in-process) or `IISOptions` (out-of-process); IIS already sits on HTTP.sys underneath.
  • Why does an HTTP.sys app fail to start with an access-denied error when run as a service account?
    Registering a URL prefix with HTTP.sys requires a reservation for non-administrator accounts. Add one with `netsh http add urlacl url=<prefix> user=<account>`; the prefix must match what the app registers, including scheme, host wildcard, port and path.
  • Where does the TLS certificate for an HTTP.sys endpoint come from?
    From the machine certificate store, bound to the IP and port (or host name and port) with `netsh http add sslcert`. Unlike Kestrel, HTTP.sys has no option to load a certificate from app configuration or a file.

  • HTTP.sys runs on Linux as well as Windows.
  • UseHttpSys works behind IIS through the ASP.NET Core Module.
  • HTTP.sys reads its certificate from Kestrel:Certificates in appsettings.json.
  • HttpSysOptions.MaxConnections = null means no connections are allowed.
  • HTTP.sys is the default server in new templates.