daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/fundamentals/servers/kestrel/http3.md

6.6 KiB
Raw Blame History

title author description monikerRange ms.author ms.custom ms.date no-loc uid
Use HTTP/3 with the ASP.NET Core Kestrel web server wtgodbe Learn about using HTTP/3 with Kestrel, the cross-platform web server for ASP.NET Core. >= aspnetcore-6.0 wigodbe mvc 08/06/2021
Home
Privacy
Kestrel
appsettings.json
ASP.NET Core Identity
cookie
Cookie
Blazor
Blazor Server
Blazor WebAssembly
Identity
Let's Encrypt
Razor
SignalR
fundamentals/servers/kestrel/http3

Use HTTP/3 with the ASP.NET Core Kestrel web server

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 recommended 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.

The preceding Windows 11 Build versions may require the use of a Windows Insider build.

Linux

  • libmsquic package installed.

libmsquic is published via Microsoft's official Linux package repository at packages.microsoft.com. To install this package:

  1. Add the packages.microsoft.com repository. See Linux Software Repository for Microsoft Products for instructions.
  2. Install the libmsquic package using the distro's package manager. For example, apt install libmsquic on Ubuntu.

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.

[!code-csharp]

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 xref:fundamentals/servers/kestrel/endpoints.

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 do not enable HTTP/3 on localhost or loopback connections. To test with a browser, run the client and server on separate machines. For example, use a Virtual Machine, Windows Subsystem for Linux, or Windows Sandbox.

  • HttpClient can be used for localhost/loopback testing in .NET 6 or later. Extra configuration is required when using HttpClient to make an HTTP/3 request:

    • Set HttpRequestMessage.Version to 3.0, or
    • Set HttpRequestMessage.VersionPolicy to HttpVersionPolicy.RequestVersionOrHigher.

Limitations

Some HTTPS scenarios are not yet supported for HTTP/3 in Kestrel. When calling Microsoft.AspNetCore.Hosting.ListenOptionsHttpsExtensions.UseHttps with xref:Microsoft.AspNetCore.Server.Kestrel.Https.HttpsConnectionAdapterOptions while using HTTP/3, setting the following options on the xref:Microsoft.AspNetCore.Server.Kestrel.Https.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.