Use HTTP/3 with HttpClient
HTTP/3 is the third and recently standardized major version of HTTP. 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 negotiate 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 browser must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes.
HttpClientand Kestrel do not support network transitions in .NET 7. It may be available in a future release.
Important
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 .NET.
HttpClient settings
The HTTP version can be configured by setting HttpRequestMessage.Version to 3.0. However, because not all routers, firewalls, and proxies properly support HTTP/3, we recommend configuring HTTP/3 together with HTTP/1.1 and HTTP/2. In HttpClient, this can be done by specifying:
HttpRequestMessage.Versionto 1.1.HttpRequestMessage.VersionPolicytoHttpVersionPolicy.RequestVersionOrHigher.
Platform dependencies
HTTP/3 uses QUIC as its transport protocol. The .NET implementation of HTTP/3 uses MsQuic to provide QUIC functionality. MsQuic is included in specific builds of Windows and as a library for Linux. If the platform that HttpClient is running on doesn't have all the requirements for HTTP/3 then it's disabled.
Windows
- Windows 11 Build 22000 (version 21H2) or later.
- TLS 1.3 or later connection.
Linux
- OpenSSL 1.1
On Linux, libmsquic is published via Microsoft's official Linux package repository packages.microsoft.com. To consume it, it must be added manually. For more information, see Linux Software Repository for Microsoft Products. After configuring the package feed, it is installed via the package manager of your distro, for example, for Ubuntu:
sudo apt install libmsquic
Note
.NET 7 is only compatible with 2.1+ versions of libmsquic.
macOS
HTTP/3 is not currently supported on macOS but may be available in a future release.
Using HttpClient
The following code example uses top-level statements and demonstrates how to specify HTTP3 in the request:
// See https://aka.ms/new-console-template for more information
using System.Net;
var client = new HttpClient()
{
DefaultRequestVersion = HttpVersion.Version30,
DefaultVersionPolicy = HttpVersionPolicy.RequestVersionExact
};
Console.WriteLine("--- Localhost:5001 ---");
HttpResponseMessage resp = await client.GetAsync("https://localhost:5001/");
string body = await resp.Content.ReadAsStringAsync();
Console.WriteLine(
$"status: {resp.StatusCode}, version: {resp.Version}, " +
$"body: {body.Substring(0, Math.Min(100, body.Length))}");
HTTP/3 Support in .NET 6
In .NET 6, HTTP/3 is available as a preview feature because the HTTP/3 specification was not yet finalized. Behavioral or performance problems may exist in HTTP/3 with .NET 6. For more information on preview features, see the preview features specification.
To enable HTTP/3 support in .NET 6, include the following in the project file to enable HTTP/3 with HttpClient:
<ItemGroup>
<RuntimeHostConfigurationOption Include="System.Net.SocketsHttpHandler.Http3Support" Value="true" />
</ItemGroup>
Alternatively, you can call System.AppContext.SetSwitch from your app code, or set the DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT environment variable to true.
The reason for requiring a configuration flag for HTTP/3 is to protect apps from future breakage when using version policy RequestVersionOrHigher. When calling a server that currently uses HTTP/1.1 and HTTP/2, if the server later upgrades to HTTP/3, the client would try to use HTTP/3 and potentially be incompatible as the standard is not final and therefore may change after .NET 6 is released.
.NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible with .NET 6 due to breaking changes in the library. Libmsquic will receive updates to 1.9.x when needed to incorporate security fixes.
HTTP/3 Server
HTTP/3 is supported by ASP.NET with the Kestrel server in .NET 6 (preview) and .NET 7 (fully supported). For more information, see use HTTP/3 with the ASP.NET Core Kestrel web server.
Public test servers
Cloudflare hosts a site for HTTP/3 which can be used to test the client against at https://cloudflare-quic.com/
See also
Feedback
Submit and view feedback for