[Breaking change]: Switch the default trace context propagator from Legacy to W3C

docs/core/compatibility/10.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 10
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 10.
-ms.date: 04/08/2025
+ms.date: 04/21/2025
 ai-usage: ai-assisted
 no-loc: [Blazor, Razor, Kestrel]
 ---
@@ -29,6 +29,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change   | 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          |
 | [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md)                | Behavioral change   | Preview 1          |
 | [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md)                              | Behavioral change   | Preview 1          |
 | [System.Linq.AsyncEnumerable included in core libraries](core-libraries/10.0/asyncenumerable.md)                           | Source incompatible | Preview 1          |

docs/core/compatibility/core-libraries/10.0/default-trace-context-propagator.md

@@ -0,0 +1,55 @@
+---
+title: "Breaking change - Default trace context propagator updated to W3C standard"
+description: "Learn about the breaking change in .NET 10 where the default trace context propagator is switched from Legacy to W3C."
+ms.date: 4/21/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/45793
+---
+
+# Default trace context propagator updated to W3C standard
+
+The default trace context propagator has been switched from the legacy propagator to the W3C propagator. The new propagator uses the `baggage` header instead of `Correlation-Context`, enforces W3C-compliant encoding, and supports only W3C-formatted trace parent IDs.
+
+## Version introduced
+
+.NET 10 Preview 4
+
+## Previous behavior
+
+The <xref:System.Diagnostics.DistributedContextPropagator.CreateDefaultPropagator?displayProperty=nameWithType> method returned an instance of the legacy propagator. By default, <xref:System.Diagnostics.DistributedContextPropagator.Current?displayProperty=nameWithType> was set to this legacy instance.
+
+## New behavior
+
+The <xref:System.Diagnostics.DistributedContextPropagator.CreateDefaultPropagator?displayProperty=nameWithType> method now returns an instance of the W3C propagator. By default, <xref:System.Diagnostics.DistributedContextPropagator.Current?displayProperty=nameWithType> is set to this W3C instance.
+
+Example of setting the default propagator to the legacy propagator:
+
+```csharp
+DistributedContextPropagator.Current = DistributedContextPropagator.CreatePreW3CPropagator();
+```
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change ensures full compliance with the W3C Trace Context and Baggage specifications. The W3C propagator enforces strict formatting for trace parent, trace state, and baggage keys and values, aligning with the W3C standards. The legacy propagator was more lenient and used the non-standard `Correlation-Context` header for baggage propagation.
+
+For more details, see the following GitHub issues:
+
+- [Pull Request #114583](https://github.com/dotnet/runtime/pull/114583)
+- [Issue #114584](https://github.com/dotnet/runtime/issues/114584)
+
+## Recommended action
+
+If you need to retain the legacy behavior, use the `DistributedContextPropagator.CreatePreW3CPropagator()` method to retrieve the legacy propagator instance. Set it as the current propagator as shown below:
+
+```csharp
+DistributedContextPropagator.Current = DistributedContextPropagator.CreatePreW3CPropagator();
+```
+
+## Affected APIs
+
+- <xref:System.Diagnostics.DistributedContextPropagator.Current?displayProperty=fullName>
+- <xref:System.Diagnostics.DistributedContextPropagator.CreateDefaultPropagator?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -22,6 +22,8 @@ items:
                 href: core-libraries/10.0/csharp-overload-resolution.md
               - name: Consistent shift behavior in generic math
                 href: core-libraries/10.0/generic-math.md
+              - name: Default trace context propagator updated to W3C Standard
+                href: core-libraries/10.0/default-trace-context-propagator.md
               - name: LDAP DirectoryControl parsing is now more stringent
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
               - name: MacCatalyst version normalization
@@ -1390,6 +1392,8 @@ items:
                 href: core-libraries/10.0/csharp-overload-resolution.md
               - name: Consistent shift behavior in generic math
                 href: core-libraries/10.0/generic-math.md
+              - name: Default trace context propagator updated to W3C Standard
+                href: core-libraries/10.0/default-trace-context-propagator.md
               - name: LDAP DirectoryControl parsing is now more stringent
                 href: core-libraries/10.0/ldap-directorycontrol-parsing.md
               - name: MacCatalyst version normalization