FAQ

Should I use this or ASP.NET Core?

For a web app or API that runs on a server, ASP.NET Core is still the better default. This library is for the places ASP.NET Core cannot go, or where it is more than the job needs.

Where does the server run?
│
├─ Inside something else: a phone app, a tablet, an Apple TV, a desktop app, a CLI
│        └─►  This server. ASP.NET Core does not run on .NET MAUI, iOS, Android or tvOS.
│
└─ On a server, as the product itself
   │
   ├─ Public, high traffic, or security-critical?
   │        └─►  ASP.NET Core
   │
   ├─ Needs Razor, MVC views, SignalR, Blazor Server or ASP.NET Core Identity?
   │        └─►  ASP.NET Core
   │
   └─ A small internal service or tool where a small Native AOT binary matters
            └─►  Either works. This server gives you a smaller binary with fewer dependencies.

Reasons to pick ASP.NET Core

• Maturity and security. Kestrel has handled a decade of production traffic. It has been fuzzed and has had its vulnerabilities fixed by Microsoft’s security team, including attacks such as HTTP/2 Rapid Reset. This server implements HTTP/1.1, HTTP/2 (with its own HPACK) and HTTP/3 (with its own QPACK) itself. That code is younger and has not faced hostile internet traffic at the same scale.
• Performance at scale. Kestrel is tuned by a dedicated team and benchmarked constantly. If throughput or tail latency under heavy load is the requirement, it is the proven choice.
• Ecosystem. Razor Pages and MVC views, Blazor Server, SignalR, ASP.NET Core Identity, OpenIddict or Duende as an identity provider, Windows authentication, Data Protection key rings, and distributed caching backed by Redis have no equivalent here. Nor does the long tail of third-party middleware written for ASP.NET Core.
• Hosting integration. IIS, HTTP.sys, Azure App Service, .NET Aspire and Kubernetes all have first-class support, templates and diagnostics tooling.
• People and support. Documentation, answers, hiring, and Microsoft’s support lifecycle.

Reasons to pick this server

• It runs where ASP.NET Core does not. It runs inside a .NET MAUI app on iOS and Android, and natively on tvOS. It follows the app between foreground and background and rebinds when the network changes. That is the reason this library exists.
• Small and AOT-clean. Native AOT and trimming work end to end, and the build enforces them. It needs no ASP.NET Core shared framework, so a CLI tool, a desktop app or a small container stays small.
• Few dependencies. It depends only on the Microsoft.Extensions.* abstractions. JSON, crypto, JWT, OpenAPI, HPACK and QPACK are all built on what is in the box.
• Built for a server on a device.
  • Tunnels make a phone reachable from the internet.
  • mDNS discovery lets another device find it without typing an IP address.
  • OAuth loopback sign-in signs a desktop app or CLI in through the system browser.
  • WebDAV and CalDAV & CardDAV let the phone’s own Files, Calendar and Contacts apps talk to yours.
• Familiar shape. Middleware, Results.* and IActionResult, AddAuthentication(), AddAuthorization(), CORS, rate limiting and problem details are all shaped like their ASP.NET Core counterparts, so most of what you know carries over.

Rule of thumb

If the server is the product and it runs on a server, use ASP.NET Core. If the server lives inside something else, such as an app, a device or a tool, use this.

Can I put it on the public internet?

Yes. It supports TLS, automatic certificates, host filtering, rate limiting, IP filtering and request limits. Keep the maturity difference above in mind for a service that is a target in its own right. For a server on a phone, a tunnel is usually the better way in. Carrier NAT blocks inbound connections, and the tunnel’s edge absorbs traffic the device should never see.

Does it support HTTP/2 and HTTP/3?

HTTP/1.1 and HTTP/2 work everywhere the server runs. HTTP/3 runs on QUIC, which .NET only supports where System.Net.Quic does: Windows, and Linux with libmsquic installed. It does not run on macOS or on mobile. See protocols.

How do I test my endpoints?

Use Shiny.Net.HttpServer.Testing. It gives you an HttpClient wired to the server in memory, with no port or socket, that still goes through the real parser, router and middleware.

I’m coming from ASP.NET Core. Where do I start?

Start with Getting Started, then Typed Endpoints, which is the closest thing to controllers and minimal APIs. The middleware page lists the ordering. It is the same idea as ASP.NET Core’s, with the same pitfalls.