diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 7380d328c6e5e..e9ac7d2247509 100644 --- a/docs/core/compatibility/10.0.md +++ b/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 | diff --git a/docs/core/compatibility/core-libraries/10.0/default-trace-context-propagator.md b/docs/core/compatibility/core-libraries/10.0/default-trace-context-propagator.md new file mode 100644 index 0000000000000..5a7394ef77805 --- /dev/null +++ b/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> diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 74a1a6e83698c..9a68a1eeca6c4 100644 --- a/docs/core/compatibility/toc.yml +++ b/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