Skip to content

Commit 3bbba6b

Browse files
CopilotBillWagner
Copilot
and
BillWagner
committed
Update .NET 10 documentation for Preview 7 release
Co-authored-by: BillWagner <[email protected]>
1 parent d5295aa commit 3bbba6b

File tree

4 files changed

+401
-10
lines changed

4 files changed

+401
-10
lines changed

‎docs/core/whats-new/dotnet-10/libraries.md‎

Lines changed: 362 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
title: What's new in .NET libraries for .NET 10
33
description: Learn about the updates to the .NET libraries for .NET 10.
44
titleSuffix: ""
5-
ms.date: 07/16/2025
5+
ms.date: 08/12/2025
66
ms.topic: whats-new
77
ai-usage: ai-assisted
88
---
99

1010
# What's new in .NET libraries for .NET 10
1111

12-
This article describes new features in the .NET libraries for .NET 10. It's been updated for Preview 6.
12+
This article describes new features in the .NET libraries for .NET 10. It's been updated for Preview 7.
1313

1414
## Cryptography
1515

@@ -328,3 +328,363 @@ A community contribution improved the performance of <xref:System.IO.Compression
328328

329329
- Eliminates repeated allocation of ~64-80 bytes of memory per concatenated stream, with additional unmanaged memory savings.
330330
- Reduces execution time by approximately 400 ns per concatenated stream.
331+
332+
## Preview 7 additions
333+
334+
The following features were added in Preview 7:
335+
336+
- [Launch Windows processes in new process group](#launch-windows-processes-in-new-process-group)
337+
- [AES KeyWrap with Padding (IETF RFC 5649)](#aes-keywrap-with-padding-ietf-rfc-5649)
338+
- [Post-quantum cryptography updates](#post-quantum-cryptography-updates)
339+
- [PipeReader support for JSON serializer](#pipereader-support-for-json-serializer)
340+
- [WebSocketStream](#websocketstream)
341+
- [TLS 1.3 for macOS (client)](#tls-13-for-macos-client)
342+
343+
### Launch Windows processes in new process group
344+
345+
For Windows, you can now use <xref:System.Diagnostics.ProcessStartInfo.CreateNewProcessGroup?displayProperty=nameWithType> to launch a process in a separate process group. This allows you to send isolated signals to child processes which could otherwise take down the parent without proper handling. Sending signals is convenient to avoid forceful termination.
346+
347+
```csharp
348+
using System;
349+
using System.Diagnostics;
350+
using System.IO;
351+
using System.Runtime.InteropServices;
352+
using System.Threading;
353+
354+
class Program
355+
{
356+
static void Main(string[] args)
357+
{
358+
bool isChildProcess = args.Length > 0 && args[0] == "child";
359+
if (!isChildProcess)
360+
{
361+
var psi = new ProcessStartInfo
362+
{
363+
FileName = Environment.ProcessPath,
364+
Arguments = "child",
365+
CreateNewProcessGroup = true,
366+
};
367+
368+
using Process process = Process.Start(psi)!;
369+
Thread.Sleep(5_000);
370+
371+
GenerateConsoleCtrlEvent(CTRL_C_EVENT, (uint)process.Id);
372+
process.WaitForExit();
373+
374+
Console.WriteLine("Child process terminated gracefully, continue with the parent process logic if needed.");
375+
}
376+
else
377+
{
378+
// If you need to send a CTRL+C, the child process needs to re-enable CTRL+C handling, if you own the code, you can call SetConsoleCtrlHandler(NULL, FALSE).
379+
// see https://learn.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw#remarks
380+
SetConsoleCtrlHandler((IntPtr)null, false);
381+
382+
Console.WriteLine("Greetings from the child process! I need to be gracefully terminated, send me a signal!");
383+
384+
bool stop = false;
385+
386+
var registration = PosixSignalRegistration.Create(PosixSignal.SIGINT, ctx =>
387+
{
388+
stop = true;
389+
ctx.Cancel = true;
390+
Console.WriteLine("Received CTRL+C, stopping...");
391+
});
392+
393+
StreamWriter sw = File.AppendText("log.txt");
394+
int i = 0;
395+
while (!stop)
396+
{
397+
Thread.Sleep(1000);
398+
sw.WriteLine($"{++i}");
399+
Console.WriteLine($"Logging {i}...");
400+
}
401+
402+
// Clean up
403+
sw.Dispose();
404+
registration.Dispose();
405+
406+
Console.WriteLine("Thanks for not killing me!");
407+
}
408+
}
409+
410+
private const int CTRL_C_EVENT = 0;
411+
private const int CTRL_BREAK_EVENT = 1;
412+
413+
[DllImport("kernel32.dll", SetLastError = true)]
414+
[return: MarshalAs(UnmanagedType.Bool)]
415+
private static extern bool SetConsoleCtrlHandler(IntPtr handler, [MarshalAs(UnmanagedType.Bool)] bool Add);
416+
417+
[DllImport("kernel32.dll", SetLastError = true)]
418+
[return: MarshalAs(UnmanagedType.Bool)]
419+
private static extern bool GenerateConsoleCtrlEvent(uint dwCtrlEvent, uint dwProcessGroupId);
420+
}
421+
```
422+
423+
### AES KeyWrap with Padding (IETF RFC 5649)
424+
425+
AES-KWP is an algorithm that is occasionally used in constructions like Cryptographic Message Syntax (CMS) EnvelopedData, where content is encrypted once, but the decryption key needs to be distributed to multiple parties, each one in a distinct secret form.
426+
427+
.NET now supports the AES-KWP algorithm via instance methods on the <xref:System.Security.Cryptography.Aes> class:
428+
429+
```csharp
430+
private static byte[] DecryptContent(ReadOnlySpan<byte> kek, ReadOnlySpan<byte> encryptedKey, ReadOnlySpan<byte> ciphertext)
431+
{
432+
using (Aes aes = Aes.Create())
433+
{
434+
aes.SetKey(kek);
435+
436+
Span<byte> dek = stackalloc byte[256 / 8];
437+
int length = aes.DecryptKeyWrapPadded(encryptedKey, dek);
438+
439+
aes.SetKey(dek.Slice(0, length));
440+
return aes.DecryptCbc(ciphertext);
441+
}
442+
}
443+
```
444+
445+
### Post-quantum cryptography updates
446+
447+
#### ML-DSA
448+
449+
The <xref:System.Security.Cryptography.MLDsa> class gained ease-of-use updates in this release, allowing some common code patterns to be simplified:
450+
451+
```diff
452+
private static byte[] SignData(string privateKeyPath, ReadOnlySpan<byte> data)
453+
{
454+
using (MLDsa signingKey = MLDsa.ImportFromPem(File.ReadAllBytes(privateKeyPath)))
455+
{
456+
- byte[] signature = new byte[signingKey.Algorithm.SignatureSizeInBytes];
457+
- signingKey.SignData(data, signature);
458+
+ return signingKey.SignData(data);
459+
- return signature;
460+
}
461+
}
462+
```
463+
464+
Additionally, this release added support for HashML-DSA, which we call "PreHash" to help distinguish it from "pure" ML-DSA. As the underlying specification interacts with the Object Identifier (OID) value, the SignPreHash and VerifyPreHash methods on this `[Experimental]` type take the dotted-decimal OID as a string. This may evolve as more scenarios using HashML-DSA become well-defined.
465+
466+
```csharp
467+
private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan<byte> data)
468+
{
469+
const string Sha3_256Oid = "2.16.840.1.101.3.4.2.8";
470+
return signingKey.SignPreHash(SHA3_256.HashData(data), Sha3_256Oid);
471+
}
472+
```
473+
474+
#### Composite ML-DSA
475+
476+
This release also introduces new types to support ietf-lamps-pq-composite-sigs (currently at draft 7), and an implementation of the primitive methods for RSA variants.
477+
478+
```csharp
479+
var algorithm = CompositeMLDsaAlgorithm.MLDsa65WithRSA4096Pss;
480+
using var privateKey = CompositeMLDsa.GenerateKey(algorithm);
481+
482+
byte[] data = [42];
483+
byte[] signature = privateKey.SignData(data);
484+
485+
using var publicKey = CompositeMLDsa.ImportCompositeMLDsaPublicKey(algorithm, privateKey.ExportCompositeMLDsaPublicKey());
486+
Console.WriteLine(publicKey.VerifyData(data, signature)); // True
487+
488+
signature[0] ^= 1; // Tamper with signature
489+
Console.WriteLine(publicKey.VerifyData(data, signature)); // False
490+
```
491+
492+
### PipeReader support for JSON serializer
493+
494+
<xref:System.Text.Json.JsonSerializer.Deserialize%2A?displayProperty=nameWithType> now supports <xref:System.IO.Pipelines.PipeReader>, complementing the existing <xref:System.IO.Pipelines.PipeWriter> support. Previously, deserializing from a `PipeReader` required converting it to a <xref:System.IO.Stream>, but the new overloads eliminate that step by integrating `PipeReader` directly into the serializer. As a bonus, not having to convert from what you're already holding can yield some efficiency benefits.
495+
496+
This shows the basic usage:
497+
498+
```csharp
499+
var pipe = new Pipe();
500+
501+
// Serialize to writer
502+
await JsonSerializer.SerializeAsync(pipe.Writer, new Person("Alice"));
503+
await pipe.Writer.CompleteAsync();
504+
505+
// Deserialize from reader
506+
var result = await JsonSerializer.DeserializeAsync<Person>(pipe.Reader);
507+
await pipe.Reader.CompleteAsync();
508+
509+
Console.WriteLine($"Your name is {result.Name}.");
510+
// Output: Your name is Alice.
511+
512+
record Person(string Name);
513+
```
514+
515+
Here is an example of a producer that produces tokens in chunks and a consumer that receives and displays them.
516+
517+
```csharp
518+
var pipe = new Pipe();
519+
520+
// Producer writes to the pipe in chunks
521+
var producerTask = Task.Run(async () =>
522+
{
523+
async static IAsyncEnumerable<Chunk> GenerateResponse()
524+
{
525+
yield return new Chunk("The quick brown fox", DateTime.Now);
526+
await Task.Delay(500);
527+
yield return new Chunk(" jumps over", DateTime.Now);
528+
await Task.Delay(500);
529+
yield return new Chunk(" the lazy dog.", DateTime.Now);
530+
}
531+
532+
await JsonSerializer.SerializeAsync<IAsyncEnumerable<Chunk>>(pipe.Writer, GenerateResponse());
533+
await pipe.Writer.CompleteAsync();
534+
});
535+
536+
// Consumer reads from the pipe and outputs to console
537+
var consumerTask = Task.Run(async () =>
538+
{
539+
var thinkingString = "...";
540+
var clearThinkingString = new string("\b\b\b");
541+
var lastTimestamp = DateTime.MinValue;
542+
543+
// Read response to end
544+
Console.Write(thinkingString);
545+
await foreach (var chunk in JsonSerializer.DeserializeAsyncEnumerable<Chunk>(pipe.Reader))
546+
{
547+
Console.Write(clearThinkingString);
548+
Console.Write(chunk.Message);
549+
Console.Write(thinkingString);
550+
lastTimestamp = DateTime.Now;
551+
}
552+
553+
Console.Write(clearThinkingString);
554+
Console.WriteLine($" Last message sent at {lastTimestamp}.");
555+
556+
await pipe.Reader.CompleteAsync();
557+
});
558+
559+
await producerTask;
560+
await consumerTask;
561+
562+
record Chunk(string Message, DateTime Timestamp);
563+
564+
// Output (500ms between each line):
565+
// The quick brown fox...
566+
// The quick brown fox jumps over...
567+
// The quick brown fox jumps over the lazy dog. Last message sent at 8/1/2025 6:41:35 PM.
568+
```
569+
570+
Note that all of this is serialized as JSON in the <xref:System.IO.Pipelines.Pipe> (formatted here for readability):
571+
572+
```json
573+
[
574+
{
575+
"Message": "The quick brown fox",
576+
"Timestamp": "2025-08-01T18:37:27.2930151-07:00"
577+
},
578+
{
579+
"Message": " jumps over",
580+
"Timestamp": "2025-08-01T18:37:27.8594502-07:00"
581+
},
582+
{
583+
"Message": " the lazy dog.",
584+
"Timestamp": "2025-08-01T18:37:28.3753669-07:00"
585+
}
586+
]
587+
```
588+
589+
### WebSocketStream
590+
591+
This release introduces `WebSocketStream`, a new API designed to simplify some of the most common—and previously cumbersome—<xref:System.Net.WebSockets.WebSocket> scenarios in .NET.
592+
593+
Traditional `WebSocket` APIs are low-level and require significant boilerplate: handling buffering and framing, reconstructing messages, managing encoding/decoding, and writing custom wrappers to integrate with streams, channels, or other transport abstractions. These complexities make it difficult to use WebSockets as a transport, especially for apps with streaming or text-based protocols, or event-driven handlers.
594+
595+
**WebSocketStream** addresses these pain points by providing a <xref:System.IO.Stream>-based abstraction over a WebSocket. This enables seamless integration with existing APIs for reading, writing, and parsing data, whether binary or text, and reduces the need for manual plumbing.
596+
597+
#### Common usage patterns
598+
599+
Here are a few examples of how `WebSocketStream` simplifies typical WebSocket workflows:
600+
601+
##### Streaming text protocol (for example, STOMP)
602+
603+
```csharp
604+
using Stream transportStream = WebSocketStream.Create(
605+
connectedWebSocket,
606+
WebSocketMessageType.Text,
607+
ownsWebSocket: true);
608+
// Integration with Stream-based APIs
609+
// Don't close the stream, as it's also used for writing
610+
using var transportReader = new StreamReader(transportStream, leaveOpen: true);
611+
var line = await transportReader.ReadLineAsync(cancellationToken); // Automatic UTF-8 and new line handling
612+
transportStream.Dispose(); // Automatic closing handshake handling on `Dispose`
613+
```
614+
615+
##### Streaming binary protocol (for example, AMQP)
616+
617+
```csharp
618+
Stream transportStream = WebSocketStream.Create(
619+
connectedWebSocket,
620+
WebSocketMessageType.Binary,
621+
closeTimeout: TimeSpan.FromSeconds(10));
622+
await message.SerializeToStreamAsync(transportStream, cancellationToken);
623+
var receivePayload = new byte[payloadLength];
624+
await transportStream.ReadExactlyAsync(receivePayload, cancellationToken);
625+
transportStream.Dispose();
626+
// `Dispose` automatically handles closing handshake
627+
```
628+
629+
##### Reading a single message as a stream (for example, JSON deserialization)
630+
631+
```csharp
632+
using Stream messageStream = WebSocketStream.CreateReadableMessageStream(connectedWebSocket, WebSocketMessageType.Text);
633+
// JsonSerializer.DeserializeAsync reads until the end of stream.
634+
var appMessage = await JsonSerializer.DeserializeAsync<AppMessage>(messageStream);
635+
```
636+
637+
##### Writing a single message as a stream (for example, binary serialization)
638+
639+
```csharp
640+
public async Task SendMessageAsync(AppMessage message, CancellationToken cancellationToken)
641+
{
642+
using Stream messageStream = WebSocketStream.CreateWritableMessageStream(_connectedWebSocket, WebSocketMessageType.Binary);
643+
foreach (ReadOnlyMemory<byte> chunk in message.SplitToChunks())
644+
{
645+
await messageStream.WriteAsync(chunk, cancellationToken);
646+
}
647+
} // EOM sent on messageStream.Dispose()
648+
```
649+
650+
**WebSocketStream** enables high-level, familiar APIs for common WebSocket consumption and production patterns—reducing friction and making advanced scenarios easier to implement.
651+
652+
### TLS 1.3 for macOS (client)
653+
654+
This release adds client-side TLS 1.3 support on macOS by integrating Apple's Network.framework into <xref:System.Net.Security.SslStream> and <xref:System.Net.Http.HttpClient>. Historically, macOS used Secure Transport which doesn't support TLS 1.3; opting into Network.framework enables TLS 1.3.
655+
656+
#### Scope and behavior
657+
658+
- macOS only, client-side in this release.
659+
- Opt-in. Existing apps continue to use the current stack unless enabled.
660+
- When enabled, older TLS versions (TLS 1.0 and 1.1) may no longer be available via Network.framework.
661+
662+
#### How to enable
663+
664+
Use an AppContext switch in code:
665+
666+
```csharp
667+
// Opt in to Network.framework-backed TLS on Apple platforms
668+
AppContext.SetSwitch("System.Net.Security.UseNetworkFramework", true);
669+
670+
using var client = new HttpClient();
671+
var html = await client.GetStringAsync("https://example.com");
672+
```
673+
674+
Or use an environment variable:
675+
676+
```bash
677+
# Opt-in via environment variable (set for the process or machine as appropriate)
678+
DOTNET_SYSTEM_NET_SECURITY_USENETWORKFRAMEWORK=1
679+
# or
680+
DOTNET_SYSTEM_NET_SECURITY_USENETWORKFRAMEWORK=true
681+
```
682+
683+
#### Notes
684+
685+
- Applies to <xref:System.Net.Security.SslStream> and APIs built on it (for example, <xref:System.Net.Http.HttpClient>/<xref:System.Net.Http.HttpMessageHandler>).
686+
- Cipher suites are controlled by macOS via Network.framework.
687+
- Underlying stream behavior may differ when Network.framework is enabled (for example, buffering, read/write completion, cancellation semantics).
688+
- Zero-byte reads: semantics may differ. Avoid relying on zero-length reads for detecting data availability.
689+
- Internationalized domain names (IDN): certain IDN hostnames may be rejected by Network.framework. Prefer ASCII/Punycode (A-label) hostnames or validate names against macOS/Network.framework constraints.
690+
- If your app relies on specific <xref:System.Net.Security.SslStream> edge-case behavior, validate it under Network.framework.

0 commit comments

Comments
 (0)