diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md index e0a2033806b50..26ed01bd350cd 100644 --- a/docs/core/compatibility/3.1-5.0.md +++ b/docs/core/compatibility/3.1-5.0.md @@ -92,11 +92,16 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v ## Core .NET libraries +- [Default ActivityIdFormat is W3C](#default-activityidformat-is-w3c) - [Behavior change for Vector2.Lerp and Vector4.Lerp](#behavior-change-for-vector2lerp-and-vector4lerp) - [SSE and SSE2 CompareGreaterThan methods properly handle NaN inputs](#sse-and-sse2-comparegreaterthan-methods-properly-handle-nan-inputs) - [CounterSet.CreateCounterSetInstance now throws InvalidOperationException if instance already exist](#countersetcreatecountersetinstance-now-throws-invalidoperationexception-if-instance-already-exists) - [Microsoft.DotNet.PlatformAbstractions package removed](#microsoftdotnetplatformabstractions-package-removed) +[!INCLUDE [default-activityidformat-changed](../../../includes/core-changes/corefx/5.0/default-activityidformat-changed.md)] + +*** + [!INCLUDE [vector-lerp-behavior-change](../../../includes/core-changes/corefx/5.0/vector-lerp-behavior-change.md)] *** diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md index c381d537fe8f9..0965ac871b103 100644 --- a/docs/core/compatibility/corefx.md +++ b/docs/core/compatibility/corefx.md @@ -11,6 +11,7 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | +| [Default ActivityIdFormat is W3C](#default-activityidformat-is-w3c) | 5.0 | | [Behavior change for Vector2.Lerp and Vector4.Lerp](#behavior-change-for-vector2lerp-and-vector4lerp) | 5.0 | | [SSE and SSE2 CompareGreaterThan methods properly handle NaN inputs](#sse-and-sse2-comparegreaterthan-methods-properly-handle-nan-inputs) | 5.0 | | [CounterSet.CreateCounterSetInstance now throws InvalidOperationException if instance already exist](#countersetcreatecountersetinstance-now-throws-invalidoperationexception-if-instance-already-exists) | 5.0 | @@ -39,6 +40,10 @@ The following breaking changes are documented on this page: ## .NET 5.0 +[!INCLUDE [default-activityidformat-changed](../../../includes/core-changes/corefx/5.0/default-activityidformat-changed.md)] + +*** + [!INCLUDE [vector-lerp-behavior-change](../../../includes/core-changes/corefx/5.0/vector-lerp-behavior-change.md)] *** diff --git a/includes/core-changes/corefx/5.0/default-activityidformat-changed.md b/includes/core-changes/corefx/5.0/default-activityidformat-changed.md new file mode 100644 index 0000000000000..d92a69dfc3851 --- /dev/null +++ b/includes/core-changes/corefx/5.0/default-activityidformat-changed.md @@ -0,0 +1,59 @@ +### Default ActivityIdFormat is W3C + +The default identifier format for activity () is now . + +#### Change description + +The W3C activity ID format was introduced in .NET Core 3.0 as an alternative to the hierarchical ID format. However, to preserve compatibility, the W3C format wasn't made the default until .NET 5.0. The default was changed in .NET 5.0 because the [W3C format has been ratified](https://www.w3.org/TR/trace-context/) and gained traction across multiple language implementations. + +If your app targets a platform other than .NET 5.0 or later, it will experience the old behavior, where is the default format. This default applies to platforms net45+, netstandard1.1+, and netcoreapp (1.x, 2.x, and 3.x). In .NET 5.0 and later, is set to . + +#### Version introduced + +5.0 Preview 7 + +#### Recommended action + +If your application is agnostic to the identifier that's used for distributed tracing, no action is needed. Libraries such as ASP.NET Core and can consume or propagate both versions of the . + +If you require interoperability with existing systems, or current systems rely on the format of the identifier, you can preserve the old behavior by setting to . Alternatively, you can set an AppContext switch in one of three ways: + +- In the project file. + + ```xml + + + + ``` + +- In the *runtimeconfig.json* file. + + ```json + { + "runtimeOptions": { + "configProperties": { + "System.Diagnostics.DefaultActivityIdFormatIsHierarchial": true + } + } + } + ``` + +- Through an environment variable. + + Set `DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL` to `true` or 1. + +#### Category + +Core .NET libraries + +#### Affected APIs + +- + +