Web server implementations in ASP.NET Core

By Tom Dykstra, Steve Smith, Stephen Halter, and Chris Ross

An ASP.NET Core app runs with an in-process HTTP server implementation. The server implementation listens for HTTP requests and surfaces them to the app as sets of request features composed into an HttpContext.

ASP.NET Core ships with the following:

ASP.NET Core ships with the following:

Kestrel

Kestrel is the default web server included in ASP.NET Core project templates.

Kestrel can be used:

  • By itself as an edge server processing requests directly from a network, including the Internet.
  • With a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. A reverse proxy server receives HTTP requests from the Internet and forwards them to Kestrel.

Kestrel communicates directly with the Internet without a reverse proxy server

Kestrel communicates indirectly with the Internet through a reverse proxy server, such as IIS, Nginx, or Apache

Either configuration—with or without a reverse proxy server—is a valid and supported hosting configuration for ASP.NET Core 2.0 or later apps. For more information, see When to use Kestrel with a reverse proxy.

If the app only accepts requests from an internal network, Kestrel can be used by itself.

Kestrel communicates directly with the internal network

If the app is exposed to the Internet, Kestrel must use a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. A reverse proxy server receives HTTP requests from the Internet and forwards them to Kestrel.

Kestrel communicates indirectly with the Internet through a reverse proxy server, such as IIS, Nginx, or Apache

The most important reason for using a reverse proxy for public-facing edge server deployments that are exposed directly the Internet is security. The 1.x versions of Kestrel don't include important security features to defend against attacks from the Internet. This includes, but isn't limited to, appropriate timeouts, request size limits, and concurrent connection limits.

For more information, see When to use Kestrel with a reverse proxy.

IIS with Kestrel

When using IIS or IIS Express, the ASP.NET Core app either runs in the same process as the IIS worker process (the in-process hosting model) or in a process separate from the IIS worker process (the out-of-process hosting model).

The ASP.NET Core Module is a native IIS module that handles native IIS requests between either the in-process IIS HTTP Server or the out-of-process Kestrel server. For more information, see ASP.NET Core Module.

When using IIS or IIS Express as a reverse proxy for ASP.NET Core, the ASP.NET Core app runs in a process separate from the IIS worker process. In the IIS process, the ASP.NET Core Module coordinates the reverse proxy relationship. The primary functions of the ASP.NET Core Module are to start the app, restart the app when it crashes, and forward HTTP traffic to the app. For more information, see ASP.NET Core Module.

Nginx with Kestrel

For information on how to use Nginx on Linux as a reverse proxy server for Kestrel, see Host ASP.NET Core on Linux with Nginx.

Apache with Kestrel

For information on how to use Apache on Linux as a reverse proxy server for Kestrel, see Host ASP.NET Core on Linux with Apache.

HTTP.sys

If ASP.NET Core apps are run on Windows, HTTP.sys is an alternative to Kestrel. Kestrel is generally recommended for best performance. HTTP.sys can be used in scenarios where the app is exposed to the Internet and required capabilities are supported by HTTP.sys but not Kestrel. For more information, see HTTP.sys web server implementation in ASP.NET Core.

HTTP.sys communicates directly with the Internet

HTTP.sys can also be used for apps that are only exposed to an internal network.

HTTP.sys communicates directly with the internal network

HTTP.sys is named WebListener in ASP.NET Core 1.x. If ASP.NET Core apps are run on Windows, WebListener is an alternative for scenarios where IIS isn't available to host apps.

Weblistener communicates directly with the Internet

WebListener can also be used in place of Kestrel for apps that are only exposed to an internal network, if required capabilities are supported by WebListener but not Kestrel. For information on WebListener, see WebListener.

Weblistener communicates directly with the internal network

ASP.NET Core server infrastructure

The IApplicationBuilder available in the Startup.Configure method exposes the ServerFeatures property of type IFeatureCollection. Kestrel and HTTP.sys (WebListener in ASP.NET Core 1.x) only expose a single feature each, IServerAddressesFeature, but different server implementations may expose additional functionality.

IServerAddressesFeature can be used to find out which port the server implementation has bound at runtime.

Custom servers

If the built-in servers don't meet the app's requirements, a custom server implementation can be created. The Open Web Interface for .NET (OWIN) guide demonstrates how to write a Nowin-based IServer implementation. Only the feature interfaces that the app uses require implementation, though at a minimum IHttpRequestFeature and IHttpResponseFeature must be supported.

Server startup

When using Visual Studio, Visual Studio for Mac, or Visual Studio Code, the server is launched when the app is started by the Integrated Development Environment (IDE). In Visual Studio on Windows, launch profiles can be used to start the app and server with either IIS Express/ASP.NET Core Module or the console. In Visual Studio Code, the app and server are started by Omnisharp, which activates the CoreCLR debugger. Using Visual Studio for Mac, the app and server are started by the Mono Soft-Mode Debugger.

When launching an app from a command prompt in the project's folder, dotnet run launches the app and server (Kestrel and HTTP.sys only). The configuration is specified by the -c|--configuration option, which is set to either Debug (default) or Release. If launch profiles are present in a launchSettings.json file, use the --launch-profile <NAME> option to set the launch profile (for example, Development or Production). For more information, see the dotnet run and .NET Core distribution packaging topics.

HTTP/2 support

HTTP/2 is supported with ASP.NET Core in the following deployment scenarios:

  • Kestrel
    • Operating system
      • Windows Server 2016/Windows 10 or later†
      • Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
      • HTTP/2 will be supported on macOS in a future release.
    • Target framework: .NET Core 2.2 or later
  • HTTP.sys
    • Windows Server 2016/Windows 10 or later
    • Target framework: Not applicable to HTTP.sys deployments.
  • IIS (in-process)
    • Windows Server 2016/Windows 10 or later; IIS 10 or later
    • Target framework: .NET Core 2.2 or later
  • IIS (out-of-process)
    • Windows Server 2016/Windows 10 or later; IIS 10 or later
    • Public-facing edge server connections use HTTP/2, but the reverse proxy connection to Kestrel uses HTTP/1.1.
    • Target framework: Not applicable to IIS out-of-process deployments.

†Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

  • HTTP.sys
    • Windows Server 2016/Windows 10 or later
    • Target framework: Not applicable to HTTP.sys deployments.
  • IIS (out-of-process)
    • Windows Server 2016/Windows 10 or later; IIS 10 or later
    • Public-facing edge server connections use HTTP/2, but the reverse proxy connection to Kestrel uses HTTP/1.1.
    • Target framework: Not applicable to IIS out-of-process deployments.

An HTTP/2 connection must use Application-Layer Protocol Negotiation (ALPN) and TLS 1.2 or later. For more information, see the topics that pertain to your server deployment scenarios.

Additional resources