February 6th, 2025

.NET 9 Networking Improvements

Continuing our tradition, we are excited to share a blog post highlighting the latest and most interesting changes in the networking space with the new .NET release. This year, we are introducing updates in the HTTP space, new HttpClientFactory APIs, .NET Framework compatibility improvements, and more.

HTTP

In the following section, we’re introducing the most impactful changes in the HTTP space. Among which belong perf improvements in connection pooling, support for multiple HTTP/3 connections, auto-updating Windows proxy, and, last but not least, community contributions.

Connection Pooling

In this release, we made two impactful performance improvements in HTTP connection pooling.

We added opt-in support for multiple HTTP/3 connections. Using more than one HTTP/3 connection to the peer is discouraged by the RFC 9114 since the connection can multiplex parallel requests. However, in certain scenarios, like server-to-server, one connection might become a bottleneck even with request multiplexing. We saw such limitations with HTTP/2 (dotnet/runtime#35088), which has the same concept of multiplexing over one connection. For the same reasons (dotnet/runtime#51775), we decided to implement multiple connection support for HTTP/3 (dotnet/runtime#101535).

The implementation itself tries to closely match the behavior of HTTP/2 multiple connections. Which, at the moment, always prefer to saturate existing connections with as many requests as allowed by the peer before opening a new one. Note that this is an implementation detail and the behavior might change in the future.

As a result, our benchmarks showed a nontrivial increase in requests per seconds (RPS), comparison for 10,000 parallel requests:

client single HTTP/3 connection multiple HTTP/3 connections
Max CPU Usage (%) 35 92
Max Cores Usage (%) 971 2,572
Max Working Set (MB) 3,810 6,491
Max Private Memory (MB) 4,415 7,228
Processor Count 28 28
First request duration (ms) 519 594
Requests 345,446 4,325,325
Mean RPS 23,069 288,664

Note that the increase in Max CPU Usage implies better CPU utilization, which means that the CPU is busy processing requests instead of being idle.

This feature can be turned on via the EnableMultipleHttp3Connections property on SocketsHttpHandler:

var client = new HttpClient(new SocketsHttpHandler
{
    EnableMultipleHttp3Connections = true
});

We also addressed lock contention in HTTP 1.1 connection pooling (dotnet/runtime#70098). The HTTP 1.1 connection pool previously used a single lock to manage the list of connections and the queue of pending requests. This lock was observed to be a bottleneck in high throughput scenarios on machines with a high number of CPU cores. We resolved this problem (dotnet/runtime#99364) by replacing an ordinary list with a lock with a concurrent collection. We chose ConcurrentStack as it preserves the observable behavior when requests are handled by the newest available connection, which allows collecting older connections when their configured lifetime expires. The throughput of HTTP 1.1 requests in our benchmarks increased by more than 30%:

Client .NET 8.0 .NET 9.0 Increase
Requests 80,028,791 107,128,778 +33.86%
Mean RPS 666,886 892,749 +33.87%

Proxy Auto Update on Windows

One of the main pain points when debugging HTTP traffic of applications using earlier versions of .NET is that the application doesn’t react to changes in Windows proxy settings (dotnet/runtime#70098). The proxy settings were previously initialized once per process with no reasonable ability to refresh the settings. For example (with .NET 8), HttpClient.DefaultProxy returns the same instance upon repeated access and never refetch the settings. As a result, tools like Fiddler, that set themself as system proxy to listen for the traffic, weren’t able to capture traffic from already running processes. This issue was mitigated in dotnet/runtime#103364, where the HttpClient.DefaultProxy is set to an instance of Windows proxy that listens for registry changes and reloads the proxy settings when notified.

The following code:

while (true)
{
    using var resp = await client.GetAsync("https://httpbin.org/");
    Console.WriteLine(HttpClient.DefaultProxy.GetProxy(new Uri("https://httpbin.org/"))?.ToString() ?? "null");
    await Task.Delay(1_000);
}

produces output like this:

null
// After Fiddler's "System Proxy" is turned on.
http://127.0.0.1:8866/

Note that this change applies only for Windows as it has a unique concept of machine wide proxy settings. Linux and other UNIX-based systems only allow setting up proxy via environment variables, which can’t be changed during process lifetime.

Community contributions

We’d like to call out community contributions.

CancellationToken overloads were missing from HttpContent.LoadIntoBufferAsync. This gap was resolved by an API proposal (dotnet/runtime#102659) from @andrewhickman-aveva and an implementation (dotnet/runtime#103991) was from @manandre.

Another change improves a units discrepancy for the MaxResponseHeadersLength property on SocketsHttpHandler and HttpClientHandler (dotnet/runtime#75137). All the other size and length properties are interpreted as being in bytes, however this one is interpreted as being in kilobytes. And since the actual behavior can’t be changed due to backward compatibility, the problem was solved by implementing an analyzer (dotnet/roslyn-analyzers#6796). The analyzer tries to make sure the user is aware that the value provided is interpreted as kilobytes, and warns if the usage suggests otherwise.

If the value is higher than a certain threshold, it looks like this: Analyzer Warning for MaxResponseHeadersLength

The analyzer was implemented by @amiru3f.

QUIC

The prominent changes in QUIC space in .NET 9 include making the library public, more configuration options for connections and several performance improvements.

Public APIs

From this release on, System.Net.Quic isn’t hidden behind PreviewFeature anymore and all the APIs are generally available without any opt-in switches (dotnet/runtime#104227).

QUIC Connection Options

We expanded the configuration options for QuicConnection (dotnet/runtime#72984). The implementation (dotnet/runtime#94211) added three new properties to QuicConnectionOptions:

  • HandshakeTimeout – we were already imposing a limit on how long a connection establishment can take, this property just enables the user to adjust it.
  • KeepAliveInterval – if this property is set up to a positive value, PING frames are sent out regularly in this interval (in case no other activity is happening on the connection) which prevents the connection from being closed on idle timeout.
  • InitialReceiveWindowSizes – a set of parameters to adjust the initial receive limits for data flow control sent in transport parameters. These data limits apply only until the dynamic flow control algorithm starts adjusting the limits based on the data reading speed. And due to MsQuic limitations, these parameters can only be set to values that are power of 2.

All of these parameters are optional. Their default values are derived from MsQuic defaults. The following code reports the defaults programmatically:

var options = new QuicClientConnectionOptions();
Console.WriteLine($"KeepAliveInterval = {PrettyPrintTimeStamp(options.KeepAliveInterval)}");
Console.WriteLine($"HandshakeTimeout = {PrettyPrintTimeStamp(options.HandshakeTimeout)}");
Console.WriteLine(@$"InitialReceiveWindowSizes =
{{
    Connection = {PrettyPrintInt(options.InitialReceiveWindowSizes.Connection)},
    LocallyInitiatedBidirectionalStream = {PrettyPrintInt(options.InitialReceiveWindowSizes.LocallyInitiatedBidirectionalStream)},
    RemotelyInitiatedBidirectionalStream = {PrettyPrintInt(options.InitialReceiveWindowSizes.RemotelyInitiatedBidirectionalStream)},
    UnidirectionalStream = {PrettyPrintInt(options.InitialReceiveWindowSizes.UnidirectionalStream)}
}}");

static string PrettyPrintTimeStamp(TimeSpan timeSpan)
    => timeSpan == Timeout.InfiniteTimeSpan ? "infinite" : timeSpan.ToString();

static string PrettyPrintInt(int sizeB)
    => sizeB % 1024 == 0 ? $"{sizeB / 1024} * 1024" : sizeB.ToString();

// Prints:
KeepAliveInterval = infinite
HandshakeTimeout = 00:00:10
InitialReceiveWindowSizes =
{
    Connection = 16384 * 1024,
    LocallyInitiatedBidirectionalStream = 64 * 1024,
    RemotelyInitiatedBidirectionalStream = 64 * 1024,
    UnidirectionalStream = 64 * 1024
}

Stream Capacity API

.NET 9 also introduced new APIs to support multiple HTTP/3 connections in SocketsHttpHandler (dotnet/runtime#101534). The APIs were designed with this specific usage in mind, and we don’t expect them to be used apart from very niche scenarios.

QUIC has built-in logic for managing stream limits within the protocol. As a result, calling OpenOutboundStreamAsync on a connection gets suspended if there isn’t any available stream capacity. Moreover, there isn’t an efficient way to learn whether the stream limit was reached or not. All these limitations together didn’t allow the HTTP/3 layer to know when to open a new connection. So we introduced a new StreamCapacityCallback that gets called whenever stream capacity is increased. The callback itself is registered via QuicConnectionOptions. More details about the callback can be found in the documentation.

Performance Improvements

Both performance improvements in System.Net.Quic are TLS related and both only affect connection establishing times.

The first performance related change was to run the peer certificate validation asynchronously in .NET thread pool (dotnet/runtime#98361). The certificate validation can be time consuming on its own and it might even include an execution of a user callback. Moving this logic to .NET thread pool stops us blocking the MsQuic thread, of which MsQuic has a limited number, and thus enables MsQuic to process higher number of new connections at the same time.

On top of that, we have introduced caching of MsQuic configuration (dotnet/runtime#99371). MsQuic configuration is a set of native structures containing connection settings from QuicConnectionOptions, potentially including certificate and its intermediaries. Constructing and initializing the native structure might be very expensive since it might require serializing and deserializing all the certificate data to and from PKS #12 format. Moreover, the cache allows reusing the same MsQuic configuration for different connections if their settings are identical. Specifically server scenarios with static configuration can notably profit from the caching, like the following code:

var alpn = "test";
var serverCertificate = X509CertificateLoader.LoadCertificateFromFile("../path/to/cert");

// Prepare the connection option upfront and reuse them.
var serverConnectionOptions = new QuicServerConnectionOptions()
{
    DefaultStreamErrorCode = 123,
    DefaultCloseErrorCode = 456,
    ServerAuthenticationOptions = new SslServerAuthenticationOptions
    {
        ApplicationProtocols = new List<SslApplicationProtocol>() { alpn },
        // Re-using the same certificate.
        ServerCertificate = serverCertificate
    }
};

// Configure the listener to return the pre-prepared options.
await using var listener = await QuicListener.ListenAsync(new QuicListenerOptions()
{
    ListenEndPoint = new IPEndPoint(IPAddress.Loopback, 0),
    ApplicationProtocols = [ alpn ],
    // Callback returns the same object.
    // Internal cache will re-use the same native structure for every incoming connection.
    ConnectionOptionsCallback = (_, _, _) => ValueTask.FromResult(serverConnectionOptions)
});

We also built it an escape hatch for this feature, it can be turned off with either environment variable:

export DOTNET_SYSTEM_NET_QUIC_DISABLE_CONFIGURATION_CACHE=1
# run the app

or with an AppContext switch:

AppContext.SetSwitch("System.Net.Quic.DisableConfigurationCache", true);

WebSockets

.NET 9 introduces the long-desired PING/PONG Keep-Alive strategy to WebSockets (dotnet/runtime#48729).

Prior to .NET 9, the only available Keep-Alive strategy was Unsolicited PONG. It was enough to keep the underlying TCP connection from idling out, but in a case when a remote host becomes unresponsive (for example, a remote server crashes), the only way to detect such situations was to depend on the TCP timeout.

In this release, we complement the existing KeepAliveInterval setting with the new KeepAliveTimeout setting, so that the Keep-Alive strategy is selected as follows:

  1. Keep-Alive is OFF, if
    • KeepAliveInterval is TimeSpan.Zero or Timeout.InfiniteTimeSpan
  2. Unsolicited PONG, if
    • KeepAliveInterval is a positive finite TimeSpan, -AND-
    • KeepAliveTimeout is TimeSpan.Zero or Timeout.InfiniteTimeSpan
  3. PING/PONG, if
    • KeepAliveInterval is a positive finite TimeSpan, -AND-
    • KeepAliveTimeout is a positive finite TimeSpan

By default, the preexisting Keep-Alive behavior is maintained: KeepAliveTimeout default value is Timeout.InfiniteTimeSpan, so Unsolicited PONG remains as the default strategy.

The following example illustrates how to enable the PING/PONG strategy for a ClientWebSocket:

var cws = new ClientWebSocket();
cws.Options.KeepAliveInterval = TimeSpan.FromSeconds(10);
cws.Options.KeepAliveTimeout = TimeSpan.FromSeconds(10);
await cws.ConnectAsync(uri, cts.Token);

// NOTE: There should be an outstanding read at all times to
// ensure incoming PONGs are promptly processed
var result = await cws.ReceiveAsync(buffer, cts.Token);

If no PONG response received after KeepAliveTimeout elapsed, the remote endpoint is deemed unresponsive, and the WebSocket connection is automatically aborted. It also unblocks the outstanding ReceiveAsync with an OperationCanceledException.

To learn more about the feature, you can check out the dedicated conceptual docs.

.NET Framework Compatibility

One of the biggest hurdles in the networking space when migrating projects from .NET Framework to .NET Core is the difference between the HTTP stacks. In .NET Framework, the main class to handle HTTP requests is HttpWebRequest which uses global ServicePointManager and individual ServicePoints to handle connection pooling. Whereas in .NET Core, HttpClient is the recommended way to access HTTP resources. On top of that, all the classes from .NET Framework are present in .NET, but they’re either obsolete, or missing implementation, or are just not maintained at all. As a result, we often see mistakes like using ServicePointManager to configure the connections while using HttpClient to access the resources.

The recommendation always was to fully migrate to HttpClient, but sometimes it’s not possible. Migrating projects from .NET Framework to .NET Core can be difficult on its own, let alone rewriting all the networking code. Expecting customers to do all this work in one step proved to be unrealistic and is one of the reasons why customers might be reluctant to migrate. To mitigate these pain points, we filled in some missing implementations of the legacy classes and created a comprehensive guide to help with the migration.

The first part is expansion of supported ServicePointManager and ServicePoint properties that were missing implementation in .NET Core up until this release (dotnet/runtime#94664 and dotnet/runtime#97537). With these changes, they’re now taken into account when using HttpWebRequest.

For HttpWebRequest, we implemented full support of AllowWriteStreamBuffering in dotnet/runtime#95001. And also added missing support for ImpersonationLevel in dotnet/runtime#102038.

On top of these changes, we also obsoleted a few legacy classes to prevent further confusion:

Lastly, we put up together a guide for migration from HttpWebRequest to HttpClient in HttpWebRequest to HttpClient migration guide. It includes comprehensive lists of mappings between individual properties and methods, e.g., Migrate ServicePoint(Manager) usage and many examples for trivial and not so trivial scenarios, e.g., Example: Enable DNS round robin.

Diagnostics

In this release, diagnostics improvements focus on enhancing privacy protection and advancing distributed tracing capabilities.

Uri Query Redaction in HttpClientFactory Logs

Starting with version 9.0.0 of Microsoft.Extensions.Http, the default logging logic of HttpClientFactory prioritizes protecting privacy. In older versions, it emits the full request URI in the RequestStart and RequestPipelineStart events. In cases where some components of the URI contain sensitive information, this can lead to privacy incidents by leaking such data into logs.

Version 8.0.0 introduced the ability to secure HttpClientFactory usage by customizing logging. However, this doesn’t change the fact that the default behavior might be risky for unaware users.

In the majority of the problematic cases, sensitive information resides in the query component. Therefore, a breaking change was introduced in 9.0.0, removing the entire query string from HttpClientFactory logs by default. A global opt-out switch is available for services/apps where it’s safe to log the full URI.

For consistency and maximum safety, a similar change was implemented for EventSource events in System.Net.Http.

We recognize that this solution might not suit everyone. Ideally, there should be a fine-grained URI filtering mechanism, allowing users to retain non-sensitive query entries or filter other URI components (e.g., parts of the path). We plan to explore such a feature for future versions (dotnet/runtime#110018).

Distributed Tracing Improvements

Distributed tracing is a diagnostic technique for tracking the path of a specific transaction across multiple processes and machines, helping identify bottlenecks and failures. This technique models the transaction as a hierarchical tree of Activities, also referred to as spans in OpenTelemetry terminology.

HttpClientHandler and SocketsHttpHandler are instrumented to start an Activity for each request and propagate the trace context via standard W3C headers when tracing is enabled.

Before .NET 9, users needed the OpenTelemetry .NET SDK to produce useful OpenTelemetry-compliant traces. This SDK was required not just for collection and export but also to extend the instrumentation, as the built-in logic didn’t populate the Activity with request data.

Starting with .NET 9, the instrumentation dependency (OpenTelemetry.Instrumentation.Http) can be omitted unless advanced features like enrichment are required. In dotnet/runtime#104251, we extended the built-in tracing to ensure that the shape of the Activity is OTel-compliant, with the name, status, and most required tags populated according to the standard.

Experimental Connection Tracing

When investigating bottlenecks, you might want to zoom into specific HTTP requests to identify where most of the time is spent. Is it during a connection establishment or the content download? If there are connection issues, it’s helpful to determine whether the problem lies with DNS lookups, TCP connection establishment, or the TLS handshake.

.NET 9 has introduced several new spans to represent activities around connection establishment in SocketsHttpHandler. The most significant one HTTP connection setup span which breaks down to three child spans for DNS, TCP, and TLS activities.

Because connection setup isn’t tied to a particular request in SocketsHttpHandler connection pool, the connection setup span can’t be modeled as a child span of the HTTP client request span. Instead, the relationship between requests and connections is being represented using Span Links, also known as Activity Links.

Note

The new spans are produced by various ActivitySources matching the wildcard Experimental.System.Net.*. These spans are experimental because monitoring tools like Azure Monitor Application Insights have difficulty visualizing the resulting traces effectively due to the numerous connection_setup → request backlinks. To improve the user experience in monitoring tools, further work is needed. It involves collaboration between the .NET team, OTel, and tool authors, and may result in breaking changes in the design of the new spans.

The simplest way to set up and try connection trace collection is by using .NET Aspire. Using Aspire Dashboards it’s possible to expand the connection_setup activity and see a breakdown of the connection initialization.

A breakdown of the connection_setup activity on .NET Aspire Dashboards

If you think the .NET 9 tracing additions might bring you valuable diagnostic insights, and you want to get some hands-on experience, don’t hesitate to read our full article about Distributed tracing in System.Net libraries.

HttpClientFactory

For HttpClientFactory, we’re introducing the Keyed DI support, offering a new convenient consumption pattern, and changing a default Primary Handler to mitigate a common erroneous usecase.

Keyed DI Support

In the previous release, Keyed Services were introduced to Microsoft.Extensions.DependencyInjection packages. Keyed DI allows you to specify the keys while registering multiple implementations of a single service type—and to later retrieve a specific implementation using the respective key.

HttpClientFactory and named HttpClient instances, unsurprisingly, align well with the Keyed Services idea. Among other things, HttpClientFactory was a way to overcome this long-missing DI feature. But it required you to obtain, store and query the IHttpClientFactory instance—instead of simply injecting a configured HttpClient—which might be inconvenient. While Typed clients attempted to simplify that part, it came with a catch: Typed clients are easy to misconfigure and misuse (and the supporting infra can also be a tangible overhead in certain scenarios). As a result, the user experience in both cases was far from ideal.

This changes as Microsoft.Extensions.DependencyInjection 9.0.0 and Microsoft.Extensions.Http 9.0.0 packages bring the Keyed DI support into HttpClientFactory (dotnet/runtime#89755). Now you can have the best of both worlds: you can pair the convenient, highly configurable HttpClient registrations with the straightforward injection of the specific configured HttpClient instances.

As of 9.0.0, you need to opt in to the feature by calling the AddAsKeyed() extension method. It registers a Named HttpClient as a Keyed service for the key equal to the client’s name—and enables you to use the Keyed Services APIs (e.g., [FromKeyedServices(...)]) to obtain the required HttpClients.

The following code demonstrates the integration between HttpClientFactory, Keyed DI and ASP.NET Core 9.0 Minimal APIs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("github", c =>
    {
        c.BaseAddress = new Uri("https://api.github.com/");
        c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
        c.DefaultRequestHeaders.Add("User-Agent", "dotnet");
    })
    .AddAsKeyed(); // Add HttpClient as a Keyed Scoped service for key="github"

var app = builder.Build();

// Directly inject the Keyed HttpClient by its name
app.MapGet("/", ([FromKeyedServices("github")] HttpClient httpClient) =>
    httpClient.GetFromJsonAsync<Repo>("/repos/dotnet/runtime"));

app.Run();

record Repo(string Name, string Url);

Endpoint response:

> ~  curl http://localhost:5000/
{"name":"runtime","url":"https://api.github.com/repos/dotnet/runtime"}

By default, AddAsKeyed() registers HttpClient as a Keyed Scoped service. The Scoped lifetime can help catching cases of captive dependencies:

services.AddHttpClient("scoped").AddAsKeyed();
services.AddSingleton<CapturingSingleton>();

// Throws: Cannot resolve scoped service 'System.Net.Http.HttpClient' from root provider.
rootProvider.GetRequiredKeyedService<HttpClient>("scoped");

using var scope = provider.CreateScope();
scope.ServiceProvider.GetRequiredKeyedService<HttpClient>("scoped"); // OK

// Throws: Cannot consume scoped service 'System.Net.Http.HttpClient' from singleton 'CapturingSingleton'.
public class CapturingSingleton([FromKeyedServices("scoped")] HttpClient httpClient)
//{ ...

You can also explicitly specify the lifetime by passing the ServiceLifetime parameter to the AddAsKeyed() method:

services.AddHttpClient("explicit-scoped")
    .AddAsKeyed(ServiceLifetime.Scoped);

services.AddHttpClient("singleton")
    .AddAsKeyed(ServiceLifetime.Singleton);

You don’t have to call AddAsKeyed for every single client—you can easily opt in “globally” (for any client name) via ConfigureHttpClientDefaults. From Keyed Services perspective, it results in the KeyedService.AnyKey registration.

services.ConfigureHttpClientDefaults(b => b.AddAsKeyed());

services.AddHttpClient("foo", /* ... */);
services.AddHttpClient("bar", /* ... */);

public class MyController(
    [FromKeyedServices("foo")] HttpClient foo,
    [FromKeyedServices("bar")] HttpClient bar)
//{ ...

Even though the “global” opt-in is a one-liner, it’s unfortunate that the feature still requires it, instead of just working “out of the box”. For full context and reasoning on that decision, see dotnet/runtime#89755 and dotnet/runtime#104943.

You can explicitly opt out from Keyed DI for HttpClients by calling RemoveAsKeyed() (for example, per specific client, in case of the “global” opt-in):

services.ConfigureHttpClientDefaults(b => b.AddAsKeyed());      // opt IN by default
services.AddHttpClient("keyed", /* ... */);
services.AddHttpClient("not-keyed", /* ... */).RemoveAsKeyed(); // opt OUT per name

provider.GetRequiredKeyedService<HttpClient>("keyed");     // OK
provider.GetRequiredKeyedService<HttpClient>("not-keyed"); // Throws: No service for type 'System.Net.Http.HttpClient' has been registered.
provider.GetRequiredKeyedService<HttpClient>("unknown");   // OK (unconfigured instance)

If called together, or any of them more than once, AddAsKeyed() and RemoveAsKeyed() generally follow the rules of HttpClientFactory configs and DI registrations:

  1. If used within the same name, the last setting wins: the lifetime from the last AddAsKeyed() is used to create the Keyed registration (unless RemoveAsKeyed() was called last, in which case the name is excluded).
  2. If used only within ConfigureHttpClientDefaults, the last setting wins.
  3. If both ConfigureHttpClientDefaults and a specific client name were used, all defaults are considered to “happen” before all per-name settings for this client. Thus, the defaults can be disregarded, and the last of the per-name ones wins.

You can learn more about the feature in the dedicated conceptual docs.

Default Primary Handler Change

One of the most common problems HttpClientFactory users run into is when a Named or a Typed client erroneously gets captured in a Singleton service, or, in general, stored somewhere for a period of time that’s longer than the specified HandlerLifetime. Because HttpClientFactory can’t rotate such handlers, they might end up not respecting DNS changes. It is, unfortunately, easy and seemingly “intuitive” to inject a Typed client into a singleton, but hard to have any kind of check/analyzer to make sure HttpClient isn’t captured when it wasn’t supposed to. It might be even harder to troubleshoot the resulting issues.

On the other hand, the problem can be mitigated by using SocketsHttpHandler, which can control PooledConnectionLifetime. Similarly to HandlerLifetime, it allows regularly recreating connections to pick up the DNS changes, but on a lower level. A client with PooledConnectionLifetime set up can be safely used as a Singleton.

Therefore, to minimize the potential impact of the erroneous usage patterns, .NET 9 makes the default Primary handler a SocketsHttpHandler (on platforms that support it; other platforms, e.g. .NET Framework, continue to use HttpClientHandler). And most importantly, SocketsHttpHandler also has the PooledConnectionLifetime property preset to match the HandlerLifetime value (it reflects the latest value, if you configured HandlerLifetime one or more times).

The change only affects cases when the client was not configured to have a custom Primary handler (via e.g. ConfigurePrimaryHttpMessageHandler<T>()).

While the default Primary handler is an implementation detail, as it was never specified in the docs, it’s still considered a breaking change. There could be cases in which you wanted to use the specific type, for example, casting the Primary handler to HttpClientHandler to set properties like ClientCertificates, UseCookies, UseProxy, etc. If you need to use such properties, it’s suggested to check for both HttpClientHandler and SocketsHttpHandler in the configuration action:

services.AddHttpClient("test")
    .ConfigurePrimaryHttpMessageHandler((h, _) =>
    {
        if (h is HttpClientHandler hch)
        {
            hch.UseCookies = false;
        }

        if (h is SocketsHttpHandler shh)
        {
            shh.UseCookies = false;
        }
    });

Alternatively, you can explicitly specify a Primary handler for each of your clients:

services.AddHttpClient("test")
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler() { UseCookies = false });

Or, configure the default Primary handler for all clients using ConfigureHttpClientDefaults:

services.ConfigureHttpClientDefaults(b =>
    b.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler() { UseCookies = false }));

Security

In System.Net.Security, we’re introducing the highly sought support for SSLKEYLOGFILE, more scenarios supporting TLS resume, and new additions in negotiate APIs.

SSLKEYLOGFILE Support

The most upvoted issue in the security space was to support logging of pre-master secret (dotnet/runtime#37915). The logged secret can be used by packet capturing tool Wireshark to decrypt the traffic. It’s a useful diagnostics tool when investigating networking issues. Moreover, the same functionality is provided by browsers like Firefox (via NSS) and Chrome and command line HTTP tools like cURL. We have implemented this feature for both SslStream and QuicConnection. For the former, the functionality is limited to the platforms on which we use OpenSSL as a cryptographic library. In the terms of the officially released .NET runtime, it means only on Linux operating systems. For the latter, it’s supported everywhere, regardless of the cryptographic library. That’s because TLS is part of the QUIC protocol (RFC 9001) so the user-space MsQuic has access to all the secrets and so does .NET. The limitation of SslStream on Windows comes from SChannel using a separate, privileged process for TLS which won’t allow exporting secrets due to security concerns (dotnet/runtime#94843).

This feature exposes security secrets and relying solely on an environmental variable could unintentionally leak them. For that reason, we’ve decided to introduce an additional AppContext switch necessary to enable the feature (dotnet/runtime#100665). It requires the user to prove the ownership of the application by either setting it programmatically in the code:

AppContext.SetSwitch("System.Net.EnableSslKeyLogging", true);

or by changing the {appname}.runtimeconfig.json next to the application:

{
  "runtimeOptions": {
    "configProperties": {
      "System.Net.EnableSslKeyLogging": true
    }
  }
}

The last thing is to set up an environmental variable SSLKEYLOGFILE and run the application:

export SSLKEYLOGFILE=~/keylogfile

./<appname>

At this point, ~/keylogfile will contain pre-master secrets that can be used by Wireshark to decrypt the traffic. For more information, see TLS Using the (Pre)-Master-Secret documentation.

TLS Resume with Client Certificate

TLS resume enables reusing previously stored TLS data to re-establish connection to previously connected server. It can save round trips during the handshake as well as CPU processing. This feature is a native part of Windows SChannel, therefore it’s implicitly used by .NET on Windows platforms. However, on Linux platforms where we use OpenSSL as a cryptographic library, enabling caching and reusing TLS data is more involved. We first introduced the support in .NET 7 (see TLS Resume). It has its own limitations that in general are not present on Windows. One such limitation was that it was not supported for sessions using mutual authentication by providing a client certificate (dotnet/runtime#94561). It has been fixed in .NET 9 (dotnet/runtime#102656) and works if one these properties is set as described:

Negotiate API Integrity Checks

In .NET 7, we added NegotiateAuthentication APIs, see Negotiate API. The original implementation’s goal was to remove access via reflection to the internals of NTAuthentication. However, that proposal was missing functions to generate and verify message integrity codes from RFC 2743. They’re usually implemented as cryptographic signing operation with a negotiated key. The API was proposed in dotnet/runtime#86950 and implemented in dotnet/runtime#96712 and as the original change, all the work from the API proposal to the implementation was done by a community contributor filipnavara.

Networking Primitives

This section encompasses changes in System.Net namespace. We’re introducing new support for server-side events and some small additions in APIs, for example new MIME types.

Server-Sent Events Parser

Server-sent events is a technology that allows servers to push data updates on clients via an HTTP connection. It is defined in living HTML standard. It uses text/event-stream MIME type and it’s always decoded as UTF-8. The advantage of the server-push approach over client-pull is that it can make better use of network resources and also save battery life of mobile devices.

In this release, we’re introducing an OOB package System.Net.ServerSentEvents. It’s available as a .NET Standard 2.0 NuGet package. The package offers a parser for server-sent event stream, following the specification. The protocol is stream based, with individual items separated by an empty line.

Each item has two fields:

  • type – default type is message
  • data – data itself

On top of that, there are two other optional fields that progressively update properties of the stream:

  • id – determines the last event id that is sent in Last-Event-Id header in case the connection needs to be reconnected
  • retry – number of milliseconds to wait between reconnection attempts

The library APIs were proposed in dotnet/runtime#98105 and contain type definitions for the parser and the items:

  • SseParser – static class to create the actual parser from the stream, allowing the user to optionally provide a parsing delegate for the item data
  • SseParser<T> – parser itself, offers methods to enumerate (synchronously or asynchronously) the stream and return the parsed items
  • SseItem<T> – struct holding parsed item data

Then the parser can be used like this, for example:

using HttpClient client = new HttpClient();
using Stream stream = await client.GetStreamAsync("https://server/sse");

var parser = SseParser.Create(stream, (type, data) =>
{
    var str = Encoding.UTF8.GetString(data);
    return Int32.Parse(str);
});
await foreach (var item in parser.EnumerateAsync())
{
    Console.WriteLine($"{item.EventType}: {item.Data} [{parser.LastEventId};{parser.ReconnectionInterval}]");
}

And for the following input:

: stream of integers

data: 123
id: 1
retry: 1000

data: 456
id: 2

data: 789
id: 3

It outputs:

message: 123 [1;00:00:01]
message: 456 [2;00:00:01]
message: 789 [3;00:00:01]

Primitives Additions

Apart from server sent event, System.Net namespace got a few small other additions:

Final Notes

As each year, we try to write about the interesting and impactful changes in the networking space. This article can’t possibly cover all the changes that were made. If you are interested, you can find the complete list in our dotnet/runtime repository where you can also reach out to us with question and bugs. On top of that, many of the performance changes that are not mentioned here are in Stephen’s great article Performance Improvements in .NET 9. We’d also like to hear from you, so if you encounter an issue or have any feedback, you can file it in our GitHub repo.

Lastly, I’d like to thank my co-authors:

Author

Máňa
Software Engineer

Máňa is a Software Engineer on the networking team for .NET libraries. She owns two aquatic turtles, swears like a sailor and drinks too much coffee.

Natalia Kondratyeva
Software Engineer

1 comment

  • silkfire 10 hours ago

    Wasn’t SocketsHttpHandler always the default handler since .NET Core 2.1? This doesn’t seem like a new behaviour to me.