Use HTTP/3 with the ASP.NET Core Kestrel web server
Note
This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 8 version of this article.
HTTP/3 is an approved standard and the third major version of HTTP. This article discusses the requirements for HTTP/3. HTTP/3 is fully supported in ASP.NET Core 7.0 and later.
Important
Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2.
HTTP/3 requirements
HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols.
Windows
- Windows 11 Build 22000 or later OR Windows Server 2022.
- TLS 1.3 or later connection.
Linux
libmsquic
package installed.
libmsquic
is published via Microsoft's official Linux package repository at packages.microsoft.com
. To install this package:
- Add the
packages.microsoft.com
repository. See Linux Software Repository for Microsoft Products for instructions. - Install the
libmsquic
package using the distro's package manager. For example,apt install libmsquic=1.9*
on Ubuntu.
Note: .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes.
macOS
HTTP/3 isn't currently supported on macOS and may be available in a future release.
Getting started
HTTP/3 is not enabled by default. Add configuration to Program.cs
to enable HTTP/3.
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel((context, options) =>
{
options.ListenAnyIP(5001, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
listenOptions.UseHttps();
});
});
The preceding code configures port 5001 to:
- Use HTTP/3 alongside HTTP/1.1 and HTTP/2 by specifying
HttpProtocols.Http1AndHttp2AndHttp3
. - Enable HTTPS with
UseHttps
. HTTP/3 requires HTTPS.
Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3 should be configured together with HTTP/1.1 and HTTP/2. This can be done by specifying HttpProtocols.Http1AndHttp2AndHttp3
as an endpoint's supported protocols.
For more information, see Configure endpoints for the ASP.NET Core Kestrel web server.
Alt-svc
HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the alt-svc
header. That means the first request will normally use HTTP/1.1 or HTTP/2 before switching to HTTP/3. Kestrel automatically adds the alt-svc
header if HTTP/3 is enabled.
Localhost testing
Browsers don't allow self-signed certificates on HTTP/3, such as the Kestrel development certificate.
HttpClient
can be used for localhost/loopback testing in .NET 6 or later. Extra configuration is required when usingHttpClient
to make an HTTP/3 request:- Set
HttpRequestMessage.Version
to 3.0, or - Set
HttpRequestMessage.VersionPolicy
toHttpVersionPolicy.RequestVersionOrHigher
.
- Set
HTTP/3 benefits
HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called QUIC.
HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2:
- Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster.
- Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost.
- Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 8. It may be available in a future release.
HTTP/3 is a proposed standard and the third major version of HTTP. This article discusses requirements for HTTP/3. HTTP/3 is fully supported in ASP.NET Core 7.0 and later.
Important
Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2.
HTTP/3 requirements
HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3 then it's disabled, and Kestrel will fallback to other HTTP protocols.
Windows
- Windows 11 Build 22000 or later OR Windows Server 2022.
- TLS 1.3 or later connection.
Linux
libmsquic
package installed.
libmsquic
is published via Microsoft's official Linux package repository at packages.microsoft.com
. To install this package:
- Add the
packages.microsoft.com
repository. See Linux Software Repository for Microsoft Products for instructions. - Install the
libmsquic
package using the distro's package manager. For example,apt install libmsquic=1.9*
on Ubuntu.
Note: .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes.
macOS
HTTP/3 isn't currently supported on macOS and may be available in a future release.
Getting started
HTTP/3 is not enabled by default. Add configuration to Program.cs
to enable HTTP/3.
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel((context, options) =>
{
options.ListenAnyIP(5001, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
listenOptions.UseHttps();
});
});
The preceding code configures port 5001 to:
- Use HTTP/3 alongside HTTP/1.1 and HTTP/2 by specifying
HttpProtocols.Http1AndHttp2AndHttp3
. - Enable HTTPS with
UseHttps
. HTTP/3 requires HTTPS.
Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3 should be configured together with HTTP/1.1 and HTTP/2. This can be done by specifying HttpProtocols.Http1AndHttp2AndHttp3
as an endpoint's supported protocols.
For more information, see Configure endpoints for the ASP.NET Core Kestrel web server.
Alt-svc
HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the alt-svc
header. That means the first request will normally use HTTP/1.1 or HTTP/2 before switching to HTTP/3. Kestrel automatically adds the alt-svc
header if HTTP/3 is enabled.
Localhost testing
Browsers don't allow self-signed certificates on HTTP/3 such as the Kestrel development certificate.
HttpClient
can be used for localhost/loopback testing in .NET 6 or later. Extra configuration is required when usingHttpClient
to make an HTTP/3 request:- Set
HttpRequestMessage.Version
to 3.0, or - Set
HttpRequestMessage.VersionPolicy
toHttpVersionPolicy.RequestVersionOrHigher
.
- Set
HTTP/3 benefits
HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called QUIC.
HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2:
- Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster.
- Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost.
- Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 6. It may be available in a future release.
HTTP/3 is the third and upcoming major version of HTTP. This article discusses requirements for HTTP/3 and how to configure Kestrel to use it.
Important
HTTP/3 is available in .NET 6 as a preview feature. The HTTP/3 specification isn't finalized and behavioral or performance issues may exist in HTTP/3 with .NET 6.
For more information on preview feature support, see the preview features supported section.
Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2. If issues are identified in HTTP/3, we recommend disabling HTTP/3 until the issues are resolved in a future release of ASP.NET Core. Significant issues are reported at the Announcements GitHub repository.
HTTP/3 requirements
HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3 then it's disabled, and Kestrel will fallback to other HTTP protocols.
Windows
- Windows 11 Build 22000 or later OR Windows Server 2022.
- TLS 1.3 or later connection.
Linux
libmsquic
package installed.
libmsquic
is published via Microsoft's official Linux package repository at packages.microsoft.com
. To install this package:
- Add the
packages.microsoft.com
repository. See Linux Software Repository for Microsoft Products for instructions. - Install the
libmsquic
package using the distro's package manager. For example,apt install libmsquic=1.9*
on Ubuntu.
Note: .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes.
macOS
HTTP/3 isn't currently supported on macOS and may be available in a future release.
Getting started
HTTP/3 is not enabled by default. Add configuration to Program.cs
to enable HTTP/3.
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel((context, options) =>
{
options.ListenAnyIP(5001, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
listenOptions.UseHttps();
});
});
The preceding code configures port 5001 to:
- Use HTTP/3 alongside HTTP/1.1 and HTTP/2 by specifying
HttpProtocols.Http1AndHttp2AndHttp3
. - Enable HTTPS with
UseHttps
. HTTP/3 requires HTTPS.
Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3 should be configured together with HTTP/1.1 and HTTP/2. This can be done by specifying HttpProtocols.Http1AndHttp2AndHttp3
as an endpoint's supported protocols.
For more information, see Configure endpoints for the ASP.NET Core Kestrel web server.
Alt-svc
HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the alt-svc
header. That means the first request will normally use HTTP/1.1 or HTTP/2 before switching to HTTP/3. Kestrel automatically adds the alt-svc
header if HTTP/3 is enabled.
Localhost testing
Browsers don't allow self-signed certificates on HTTP/3 such as the Kestrel development certificate.
HttpClient
can be used for localhost/loopback testing in .NET 6 or later. Extra configuration is required when usingHttpClient
to make an HTTP/3 request:- Set
HttpRequestMessage.Version
to 3.0, or - Set
HttpRequestMessage.VersionPolicy
toHttpVersionPolicy.RequestVersionOrHigher
.
- Set
Limitations
Some HTTPS scenarios are not yet supported for HTTP/3 in Kestrel. When calling Microsoft.AspNetCore.Hosting.ListenOptionsHttpsExtensions.UseHttps
with HttpsConnectionAdapterOptions while using HTTP/3, setting the following options on the HttpsConnectionAdapterOptions is a no-op (it does nothing):
Calling the following implementations of Microsoft.AspNetCore.Hosting.ListenOptionsHttpsExtensions.UseHttps
throw an error when using HTTP/3:
- UseHttps(this ListenOptions listenOptions, ServerOptionsSelectionCallback serverOptionsSelectionCallback, object state, TimeSpan handshakeTimeout)
- UseHttps(this ListenOptions listenOptions, TlsHandshakeCallbackOptions callbackOptions)
HTTP/3 benefits
HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called QUIC.
HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2:
- Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster.
- Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost.
- Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 6. It may be available in a future release.