Merge pull request #47987 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

.github/prompts/whats-new-net.md

@@ -27,18 +27,35 @@ For preview releases, the path is `<major-release>/preview/preview<n>` where:
 
 The primary release notes are in the `README.MD` file in that folder.  That file contains links to other release notes for components of .NET: libraries, runtime, SDK, languages, and so on. Use all that information for source.
 
+The source files you use are release notes from the product team. These take the form of announcements, so you should edit any incorporated content per the following guidelines:
+
+- Remove any 1st person references (we, us, our), and rewrite that information in the 2nd person: Tell the reader what the reader can do, using "you" to refer to the reader.
+- Remove any marketing and promotional language. These articles provide technical information, not marketing copy.
+
 ## Updates for each file
 
+Each file should be organized to provide a cohesive story about "What's new" in the release. When you edit:
+
+- The introductory paragraph states when the last update was made (Preview N, general release, any service release). That is the only mention of the latest minor, patch, or preview version.
+- If one of the areas (SDK, libraries, or runtime) doesn't have any updates for the current release (preview, RC, or GA), update the introductory paragraph and ms.date value, without making any other changes.
+- Each file should organize updates by feature area, not by when an update was made. In other words, starting with the 2nd preview, incorporate updates to the existing text to provide a single view of all updates made in the major release. For example, the "RC1" updates should add in updates in RC1 where it fits in the document, not make a new "RC1" section.
+- If a preview introduces a new feature that's unrelated to existing new features, add a new H2 for that feature area.
+
+In addition, follow these recommendations:
+
+- Follow the Microsoft Writing Style Guide, as noted in the `.github/copilot-instructions.md` file in this repository.
 - Each file should have its `ms.date` metadata field updated to match the date you're assigned the issue.
 - Ensure each file has the `ai-usage: ai-assisted` metadata field added.
 - Update phrasing on the latest update to reference the current release (preview, GA, or service release). Individual features shouldn't reference a given preview release, but the article should make it clear which was the last preview.
 - Search this repository for articles that have been recently updated pertaining to new features. Add links to those as you write about that feature. Or, add applicable information from the release notes into existing feature articles where it makes sense.
 - For the runtime and libraries articles, include extensive examples as well as links to recently updated articles related to the new feature. The examples should be at least as thorough as the examples from the source release notes.
 - Where applicable, the SDK article should include the samples.
 - The overview article generally doesn't include examples. Its purpose is to direct readers to more detailed information in other articles.
-- All APIs should be referenced using an `xref` style link, at least on first mention.
+- All APIs should be referenced using an `xref` style link, at least on first mention. Later mentions should be code-fenced in single back-ticks.
 - All links to article in the `dotnet/docs` repository should be file relative.
 - Spell out acronyms on first use in each file.
+- Avoid gerund form in headings.
 - In general, don't mention specific contributors or pull requests to the product repos.
+- Code snippets longer than 6 lines should be moved to a code file and included using the `:::` extension. All code files should be included in a buildable project to ensure the snippets build correctly.
 
 Next, create a pull request. In the description, include the text "Fixes #\<issue-number>", where "issue-number" is the GitHub issue number.

docs/core/compatibility/10.0.md

@@ -39,6 +39,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | Title | Type of change    | Introduced version |
 |-------|-------------------|--------------------|
 | [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 |
+| [Arm64 SVE nonfaulting loads require mask](core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md) | Binary/source incompatible | Preview 1 |
 | [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 |
 | [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 |
 | [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 |

docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md

@@ -0,0 +1,79 @@
+---
+title: "Breaking change: Arm64 SVE nonfaulting loads require mask parameter"
+description: "Learn about the breaking change in .NET 10 where Arm64 SVE nonfaulting load APIs now require a mask parameter as the first argument."
+ms.date: 08/11/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/47439
+---
+
+# Arm64 SVE nonfaulting loads require mask parameter
+
+All Arm64 SVE nonfaulting load APIs have been updated to include a `mask` parameter in the first position. This change affects all methods with `LoadVector*NonFaulting` in their name in the <xref:System.Runtime.Intrinsics.Arm.Sve?displayProperty=nameWithType> class.
+
+## Version introduced
+
+.NET 10 Preview 7
+
+## Previous behavior
+
+Previously, nonfaulting load APIs took only an address parameter and loaded a full vector:
+
+```csharp
+Vector<short> result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address);
+```
+
+To do nonfaulting load with masked-out elements, you had to use <xref:System.Runtime.Intrinsics.Arm.Sve.ConditionalSelect*>:
+
+```csharp
+Vector<short> maskedResult = Sve.ConditionalSelect(
+    mask,
+    Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address),
+    zero);
+```
+
+## New behavior
+
+Starting in .NET 10, nonfaulting load APIs require a mask parameter as the first argument.
+
+To do a nonfaulting load for all elements, create and pass a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);`
+
+## Type of breaking change
+
+This change can affect [binary compatibility](../../categories.md#binary-compatibility) and [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+This change was necessary because a nonfaulting load updates the first fault register (FFR) depending on which vector lanes are loaded. The standard conversion of `ConditionalSelect(mask, LoadVectorNonFaulting(addr), zero)` to a masked load can't be used because it doesn't properly handle the FFR register state. Therefore, the only valid way to implement a masked nonfaulting load is by exposing it as a dedicated API.
+
+## Recommended action
+
+- For existing uses of `Sve.ConditionalSelect(mask, Sve.LoadVector*NonFaulting*(addr), zero)`, replace them with `Sve.LoadVector*NonFaulting*(mask, addr)`.
+- Update other uses of nonfaulting loads to include a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr)`.
+
+## Affected APIs
+
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorNonFaulting%2A?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt16(System.Byte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt32(System.Byte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt64(System.Byte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt16(System.Byte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt32(System.Byte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt64(System.Byte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToInt32(System.Int16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToInt64(System.Int16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToUInt32(System.Int16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToUInt64(System.Int16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt32NonFaultingSignExtendToInt64(System.Int32*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt32NonFaultingSignExtendToUInt64(System.Int32*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt16(System.SByte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt32(System.SByte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt64(System.SByte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt16(System.SByte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt32(System.SByte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt64(System.SByte*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToInt32(System.UInt16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToInt64(System.UInt16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToUInt32(System.UInt16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToUInt64(System.UInt16*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt32NonFaultingZeroExtendToInt64(System.UInt32*)?displayProperty=fullName>
+- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt32NonFaultingZeroExtendToUInt64(System.UInt32*)?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -36,6 +36,8 @@ items:
                 href: core-libraries/10.0/obsolete-apis.md
               - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
                 href: core-libraries/10.0/activity-sampling.md
+              - name: Arm64 SVE nonfaulting loads require mask
+                href: core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md
               - name: C# 14 overload resolution with span parameters
                 href: core-libraries/10.0/csharp-overload-resolution.md
               - name: Consistent shift behavior in generic math

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

@@ -61,9 +61,9 @@ If you want even more control, you can use [the overload](xref:System.Security.C
 
 .NET 10 includes support for three new asymmetric algorithms: ML-KEM (FIPS 203), ML-DSA (FIPS 204), and SLH-DSA (FIPS 205). The new types are:
 
-- `System.Security.Cryptography.MLKem` <!--xref:System.Security.Cryptography.MLKem-->
-- `System.Security.Cryptography.MLDsa` <!--xref:System.Security.Cryptography.MLDsa-->
-- `System.Security.Cryptography.SlhDsa` <!--xref:System.Security.Cryptography.SlhDsa-->
+- <xref:System.Security.Cryptography.MLKem?displayProperty=fullName>
+- <xref:System.Security.Cryptography.MLDsa?displayProperty=fullName>
+- <xref:System.Security.Cryptography.SlhDsa?displayProperty=fullName>
 
 Because it adds little benefit, these new types don't derive from <xref:System.Security.Cryptography.AsymmetricAlgorithm>. Rather than the `AsymmetricAlgorithm` approach of creating an object and then importing a key into it, or generating a fresh key, the new types all use static methods to generate or import a key:
 
@@ -95,7 +95,7 @@ using (MLKem key = MLKem.GenerateKey(MLKemAlgorithm.MLKem768))
 
 These algorithms all continue with the pattern of having a static `IsSupported` property to indicate if the algorithm is supported on the current system.
 
-.NET 10 includes Windows Cryptography API: Next Generation (CNG) support for Post-Quantum Cryptography (PQC), making these algorithms available on Windows systems with PQC support. For example:
+.NET 10 includes Windows Cryptography API: Next Generation (CNG) support for Post-Quantum Cryptography (PQC), which makes these algorithms available on Windows systems with PQC support. For example:
 
 ```csharp
 using System;
@@ -130,7 +130,7 @@ private static byte[] SignData(string privateKeyPath, ReadOnlySpan<byte> data)
 }
 ```
 
-Additionally, this release added support for HashML-DSA, which is called "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 might evolve as more scenarios using HashML-DSA become well-defined.
+Additionally, .NET 10 adds support for HashML-DSA, which is called "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 might evolve as more scenarios using HashML-DSA become well-defined.
 
 ```csharp
 private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan<byte> data)
@@ -142,7 +142,7 @@ private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan<byte> d
 
 #### Composite ML-DSA
 
-.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (currently at draft 7), including `CompositeMLDsa` and `CompositeMLDsaAlgorithm` types with implementation of the primitive methods for RSA variants.
+.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (currently at draft 7), including the <xref:System.Security.Cryptography.CompositeMLDsa> and <xref:System.Security.Cryptography.CompositeMLDsaAlgorithm> types, with implementation of the primitive methods for RSA variants.
 
 ```csharp
 var algorithm = CompositeMLDsaAlgorithm.MLDsa65WithRSA4096Pss;
@@ -160,7 +160,7 @@ Console.WriteLine(publicKey.VerifyData(data, signature)); // False
 
 ### AES KeyWrap with Padding (IETF RFC 5649)
 
-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.
+AES-KWP is an algorithm that's 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.
 
 .NET now supports the AES-KWP algorithm via instance methods on the <xref:System.Security.Cryptography.Aes> class:
 
@@ -440,7 +440,7 @@ For Windows, you can now use <xref:System.Diagnostics.ProcessStartInfo.CreateNew
 
 ### WebSocketStream
 
-.NET 10 introduces `WebSocketStream` <!--<xref:System.Net.WebSockets.WebSocketStream>-->, a new API designed to simplify some of the most common&mdash;and previously cumbersome&mdash;<xref:System.Net.WebSockets.WebSocket> scenarios in .NET.
+.NET 10 introduces <xref:System.Net.WebSockets.WebSocketStream>, a new API designed to simplify some of the most common&mdash;and previously cumbersome&mdash;<xref:System.Net.WebSockets.WebSocket> scenarios in .NET.
 
 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.
 
@@ -485,7 +485,7 @@ Here are a few examples of how `WebSocketStream` simplifies typical `WebSocket`
 Use an AppContext switch in code:
 
 ```csharp
-// Opt in to Network.framework-backed TLS on Apple platforms
+// Opt in to Network.framework-backed TLS on Apple platforms.
 AppContext.SetSwitch("System.Net.Security.UseNetworkFramework", true);
 
 using var client = new HttpClient();

docs/core/whats-new/dotnet-10/overview.md

@@ -26,14 +26,12 @@ For more information, see [What's new in the .NET 10 runtime](runtime.md).
 The .NET 10 libraries introduce new APIs in cryptography, globalization, numerics, serialization, collections, and diagnostics, and when working with ZIP files. New JSON serialization options include disallowing duplicate properties, strict serialization settings, and `PipeReader` support for improved efficiency. Post-quantum cryptography support has been expanded with Windows Cryptography API: Next Generation (CNG) support, enhanced ML-DSA with simplified APIs and HashML-DSA support, plus Composite ML-DSA. Additional cryptography enhancements include AES KeyWrap with Padding support. New networking capabilities include `WebSocketStream` for simplified `WebSocket` usage and TLS 1.3 support for macOS clients. Process management gains Windows process group support for better signal isolation.
 
 For more information, see [What's new in the .NET 10 libraries](libraries.md).
-For details on JSON serialization, see [System.Text.Json overview](/dotnet/standard/serialization/system-text-json/overview).
 
 ## .NET SDK
 
 The .NET 10 SDK includes support for [Microsoft.Testing.Platform](../../testing/microsoft-testing-platform-intro.md) in `dotnet test`, standardizes CLI command order, and updates the CLI to generate native tab-completion scripts for popular shells. For containers, console apps can natively create container images, and a new property lets you explicitly set the format of container images. The SDK also supports platform-specific .NET tools with enhanced compatibility via the `any` RuntimeIdentifier, one-shot tool execution with `dotnet tool exec`, the new `dnx` tool execution script, CLI introspection with `--cli-schema`, and enhanced file-based apps with publish support and native AOT.
 
 For more information, see [What's new in the SDK for .NET 10](sdk.md).
-For details on .NET tools, see [Manage .NET tools](/dotnet/core/tools/global-tools).
 
 ## .NET Aspire