Skip to content

Commit 6bad9ed

Browse files
CamSopergewarren
CamSoper
and
gewarren
authoredJan 31, 2025··
.NET 10 Preview 1 breaking changes batch (#44625)
* issues/44500 * Fix for 44500 * tweaks to 44500, issue 44403 * linting * More 44500 * xref * issue 44282 * xref fix * issue 43952 * fix linting * issue 43885 * issue 43828 * fix xref * issue 43303 * issue 43284 * lint * 43156 * issue 42558 * issue 42027 * build fix * Apply suggestions from code review. Thank you @gewarren! Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Apply all new suggestions and AI disclosure * Missed a couple suggestions * Fixed linting issues introduced by VSCode --------- Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
1 parent 4aaaae3 commit 6bad9ed

16 files changed

+683
-6
lines changed
 

‎docs/core/compatibility/10.0.md

+29-4
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
title: Breaking changes in .NET 10
33
titleSuffix: ""
44
description: Navigate to the breaking changes in .NET 10.
5-
ms.date: 12/19/2024
5+
ms.date: 01/30/2025
6+
ai-usage: ai-assisted
67
no-loc: [Blazor, Razor, Kestrel]
78
---
89
# Breaking changes in .NET 10
@@ -17,6 +18,30 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
1718
1819
## Core .NET libraries
1920

20-
| Title | Type of change | Introduced version |
21-
|------------------------------------------------------------------------------------------|---------------------|--------------------|
22-
| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 |
21+
| Title | Type of change | Introduced version |
22+
|----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
23+
| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 |
24+
| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 |
25+
| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 |
26+
| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 |
27+
| [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md) | Behavioral change | Preview 1 |
28+
| [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md) | Behavioral change | Preview 1 |
29+
30+
## Globalization
31+
32+
| Title | Type of change | Introduced version |
33+
|-------------------------------------------------------------------------------------------------------|-------------------|--------------------|
34+
| [Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE](globalization/10.0/version-override.md) | Behavioral change | Preview 1 |
35+
36+
## Cryptography
37+
38+
| Title | Type of change | Introduced version |
39+
|--------------------------------------------------------------------------------------------------------|-------------------|--------------------|
40+
| [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 |
41+
42+
## Windows Forms
43+
44+
| Title | Type of change | Introduced version |
45+
|-------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
46+
| [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 |
47+
| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 |

‎docs/core/compatibility/core-libraries/10.0/activity-sampling.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: "Breaking change: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior changes"
3+
description: Learn about the .NET 10.0 breaking change in core .NET libraries where ActivitySource.CreateActivity and ActivitySource.StartActivity behavior is modified.
4+
ms.date: 01/30/2025
5+
ai-usage: ai-assisted
6+
---
7+
# ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
8+
9+
The <xref:System.Diagnostics.ActivitySource.CreateActivity*?displayProperty=nameWithType> and <xref:System.Diagnostics.ActivitySource.StartActivity*?displayProperty=nameWithType> APIs only return an <xref:System.Diagnostics.Activity> when there's a registered listener that decides the instance should be created. This is generally known as sampling.
10+
11+
The <xref:System.Diagnostics.ActivitySamplingResult?displayProperty=nameWithType> enum defines the possible sampling decisions.
12+
13+
When creating an `Activity` without a parent, `ActivitySamplingResult` drives whether the `Activity` is created and then how the `Recorded` and `IsAllDataRequested` properties are set:
14+
15+
|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested|
16+
|---|---|---|---|
17+
|None|No|||
18+
|PropagationData|Yes|False|False|
19+
|AllData|Yes|False|True|
20+
|AllDataAndRecorded|Yes|True|True|
21+
22+
It is also possible to create an `Activity` with a parent. The parent could be in the same process, or it could be a remote parent propagated to the current process.
23+
24+
## Previous behavior
25+
26+
Previously, when creating an `Activity` as `PropagationData` with a parent marked as `Recorded`, the `Recorded` and `IsAllDataRequested` properties were set as follows:
27+
28+
|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested|
29+
|---|---|---|---|
30+
|PropagationData|Yes|True|False|
31+
32+
## New behavior
33+
34+
Starting in .NET 10, when you create an `Activity` as `PropagationData` with a parent marked as `Recorded`, the `Recorded` and `IsAllDataRequested` properties are set as follows:
35+
36+
|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested|
37+
|---|---|---|---|
38+
|PropagationData|Yes|False|False|
39+
40+
## Version introduced
41+
42+
.NET 10 Preview 1
43+
44+
## Type of breaking change
45+
46+
This change is a [behavioral change](../../categories.md#behavioral-change).
47+
48+
## Reason for change
49+
50+
The previous behavior did not follow the OpenTelemetry specification.
51+
52+
## Recommended action
53+
54+
If you've implemented `ActivityListener.Sample` directly AND use `ActivitySamplingResult.PropagationData`, verify that you're not reliant on the flawed behavior. To restore the previous behavior, you can set `Activity.ActivityTraceFlags` to `Recorded` after the `CreateActivity` or `StartActivity` call.
55+
56+
If you use OpenTelemetry .NET and have customized the sampler, verify your sampler configuration. The default OpenTelemetry .NET configuration uses a parent-based algorithm that isn't impacted.
57+
58+
## Affected APIs
59+
60+
- <xref:System.Diagnostics.ActivitySource.CreateActivity*?displayProperty=fullName>
61+
- <xref:System.Diagnostics.ActivitySource.StartActivity*?displayProperty=fullName>

‎docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: "Breaking change: C# 14 overload resolution with span parameters"
3+
description: Learn about the .NET 10 breaking change in core .NET libraries where overloads with span parameters are applicable in more scenarios.
4+
ms.date: 01/30/2025
5+
ai-usage: ai-assisted
6+
---
7+
# C# 14 overload resolution with span parameters
8+
9+
C# 14, which ships with .NET 10, introduces new [built-in span conversions and type inference rules](https://github.com/dotnet/csharplang/issues/7905). Those changes make overloads with span parameters applicable in more scenarios.
10+
11+
## Previous behavior
12+
13+
In C# 13 and earlier, an extension method taking a `ReadOnlySpan<T>` or `Span<T>` receiver was not applicable to a value of type `T[]`. Therefore, only non-span extension methods like the ones from the `System.Linq.Enumerable` class were usually bound inside Expression lambdas.
14+
15+
## New behavior
16+
17+
In C# 14 and later, methods with `ReadOnlySpan<T>` or `Span<T>` parameters can participate in type inference or be used as extension methods in more scenarios. This makes span-based methods like the ones from the `System.MemoryExtensions` class bind in more scenarios, including inside Expression lambdas where they will cause run-time exceptions when compiled with interpretation.
18+
19+
## Version introduced
20+
21+
.NET 10 Preview 1
22+
23+
## Type of breaking change
24+
25+
This change is a [behavioral change](../../categories.md#behavioral-change).
26+
27+
## Reason for change
28+
29+
The C# language feature allows simplified API design and usage (for example, one <xref:System.ReadOnlySpan`1> extension method can apply to both spans and arrays).
30+
31+
## Recommended action
32+
33+
If you need to continue using Expression interpretation, make sure the non-span overloads are bound, for example, by casting arguments to the exact types the method signature takes or calling the extension methods as explicit static invocations:
34+
35+
```csharp
36+
using System;
37+
using System.Collections.Generic;
38+
using System.Linq;
39+
using System.Linq.Expressions;
40+
41+
M((array, num) => array.Contains(num)); // fails, binds to MemoryExtensions.Contains
42+
M((array, num) => ((IEnumerable<int>)array).Contains(num)); // ok, binds to Enumerable.Contains
43+
M((array, num) => array.AsEnumerable().Contains(num)); // ok, binds to Enumerable.Contains
44+
M((array, num) => Enumerable.Contains(array, num)); // ok, binds to Enumerable.Contains
45+
46+
void M(Expression<Func<int[], int, bool>> e) => e.Compile(preferInterpretation: true);
47+
```
48+
49+
## Affected APIs
50+
51+
- <xref:System.Linq.Expressions.Expression`1.Compile*?displayProperty=fullName>

‎docs/core/compatibility/core-libraries/10.0/generic-math.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: "Breaking change: Consistent shift behavior in generic math"
3+
description: Learn about the .NET 10 breaking change in core .NET libraries where shift operations in generic math now have consistent behavior.
4+
ms.date: 01/30/2025
5+
ai-usage: ai-assisted
6+
---
7+
# Consistent shift behavior in generic math
8+
9+
Shift operations in generic math now have consistent behavior across all built-in integer types.
10+
11+
## Previous behavior
12+
13+
The behavior when utilizing generic math to perform a shift on a `T` could differ based on the type. In some cases, it appropriately masked the shift amount by `sizeof(T) - 1`. And in other cases, there was no masking. This meant that "overshifting" (such as shifting a `byte` by 8) could result in different answers than expected.
14+
15+
## New behavior
16+
17+
The implementations were updated to mask the shift amount, as appropriate, to ensure consistent behavior across all built-in integer types and with the behavior documented by the <xref:System.Numerics.IShiftOperators`3?displayProperty=nameWithType> interface.
18+
19+
## Version introduced
20+
21+
.NET 10 Preview 1
22+
23+
## Type of breaking change
24+
25+
This change is a [behavioral change](../../categories.md#behavioral-change).
26+
27+
## Reason for change
28+
29+
The behavior differed from the designed behavior due to a difference in how masking works for small integer types in C#.
30+
31+
## Recommended action
32+
33+
Update any code that relies on the previous inconsistent behavior to ensure it works with the new consistent behavior.
34+
35+
## Affected APIs
36+
37+
- `operator <<`
38+
- `operator >>`
39+
- `operator >>>` for `byte`, `char`, `sbyte`, `short`, and `ushort` when used via generic math, which requires a `T` constrained to `where T : IShiftOperators<T, int, T>` or a similar interface.

‎docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: "Breaking change: LDAP DirectoryControl parsing is now more stringent"
3+
description: Learn about the .NET 10 breaking change in core .NET libraries where LDAP DirectoryControl parsing is now more stringent.
4+
ms.date: 01/30/2025
5+
ai-usage: ai-assisted
6+
---
7+
8+
# LDAP DirectoryControl parsing is now more stringent
9+
10+
Previously, .NET used <xref:System.DirectoryServices.Protocols.BerConverter?displayProperty=nameWithType> to parse the <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> objects it received over the network and to generate the <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> byte arrays it sent. <xref:System.DirectoryServices.Protocols.BerConverter?displayProperty=nameWithType> used the OS-specific BER parsing functionality. This parsing functionality is now implemented in managed code.
11+
12+
## Previous behavior
13+
14+
As a result of using <xref:System.DirectoryServices.Protocols.BerConverter?displayProperty=nameWithType>, the parsing of <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> objects was fairly loose:
15+
16+
- The ASN.1 tags of each value weren't checked.
17+
- Trailing data after the end of the parsed DirectoryControl was ignored, as was trailing data within an ASN.1 SEQUENCE.
18+
- On Linux, OCTET STRING lengths that extended beyond the end of their parent sequence returned data outside the parent sequence.
19+
- On earlier versions of Windows, a zero-length OCTET STRING returned `null` rather than an empty string.
20+
- When reading the contents of a <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> as a UTF8-encoded string, an invalid UTF8 sequence did not throw an exception.
21+
- When passing an invalid UTF8 string to the constructor of [VlvRequestControl](xref:System.DirectoryServices.Protocols.VlvRequestControl), no exception was thrown.
22+
23+
While not a breaking change, Windows always encoded ASN.1 tags with a four-byte length while Linux only used as many bytes for the tag length as it needed. Both representations were valid, but this behavioral difference between platforms is now gone; the Linux behavior now also appears on Windows.
24+
25+
## New behavior
26+
27+
The DirectoryControl parsing is much more stringent, and is now consistent across platforms and versions:
28+
29+
- ASN.1 tags are now checked.
30+
- Trailing data is no longer permitted.
31+
- The length of `OCTET STRING`s and `SEQUENCE`s is now checked.
32+
- Zero-length `OCTET STRING`s now always return an empty string.
33+
- If the server sends an invalid UTF8 byte sequence, the <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> parsing logic now throws an exception rather than silently substituting the invalid characters with a known value.
34+
35+
We also validate errors more thoroughly when calling the <xref:System.DirectoryServices.Protocols.VlvRequestControl> constructor. Passing a string which cannot be encoded as a UTF8 value now throws an <xref:System.Text.EncoderFallbackException>.
36+
37+
## Version introduced
38+
39+
.NET 10 Preview 1
40+
41+
## Type of breaking change
42+
43+
This change is a [behavioral change](../../categories.md#behavioral-change).
44+
45+
## Reason for change
46+
47+
This change was made for RFC and specification compliance. In the various RFCs and sections of MS-ADTS, the controlValue is specified as the BER encoding of an ASN.1 structure with wording similar to the following (from [RFC2891, section 1.2](https://datatracker.ietf.org/doc/html/rfc2891#section-1.2)):
48+
49+
> The controlType is set to "1.2.840.113556.1.4.474". The criticality is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value is the BER encoding of a value of the following SEQUENCE:
50+
51+
This precludes trailing data. It also rules out BER encodings of ASN.1 structures with differing ASN.1 tags, and of invalid BER encodings (such as OCTET STRINGs which are longer than their containing SEQUENCE.)
52+
53+
For the <xref:System.DirectoryServices.Protocols.VlvRequestControl> constructor, throwing the exception early means that users can trust that only the values they explicitly specify are sent to the server. There are no circumstances where they can accidentally send `EF BF BD` to the server because they've passed a string that can't be encoded to valid UTF8 bytes.
54+
55+
## Recommended action
56+
57+
Servers should comply with the RFCs and specifications. Make sure to handle an <xref:System.Text.EncoderFallbackException> when calling the <xref:System.DirectoryServices.Protocols.VlvRequestControl> constructor.
58+
59+
## Affected APIs
60+
61+
- <xref:System.DirectoryServices.Protocols.LdapConnection.SendRequest*?displayProperty=fullName>
62+
- <xref:System.DirectoryServices.Protocols.LdapConnection.EndSendRequest*?displayProperty=fullName>
63+
- <xref:System.DirectoryServices.Protocols.VlvRequestControl.%23ctor*>

‎docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Breaking change: MacCatalyst version normalization"
3+
description: Learn about the .NET 10 breaking change in core .NET libraries where MacCatalyst version components are normalized.
4+
ms.date: 01/01/2025
5+
ai-usage: ai-assisted
6+
---
7+
8+
# MacCatalyst version normalization
9+
10+
This update ensures that MacCatalyst version components retrieved from the OS are always normalized to three components: major, minor, and build. The build component is set to `0` if undefined (`-1`), ensuring consistent behavior between iOS and MacCatalyst versions for version checks.
11+
12+
## Previous behavior
13+
14+
The build component in `Version` was not previously normalized, which led to incorrect version checks on MacCatalyst when only two components (major and minor) were provided. This resulted in invalid version checks.
15+
16+
## New behavior
17+
18+
The MacCatalyst build component is now normalized to `0`, ensuring consistent version checks. The revision component is always set to `-1`, as it is not specified on MacCatalyst or iOS.
19+
20+
## Version introduced
21+
22+
.NET 10 Preview 1
23+
24+
## Type of breaking change
25+
26+
This change is a [behavioral change](../../categories.md#behavioral-change).
27+
28+
## Reason for change
29+
30+
This changed was made to prevent incorrect version checks and align MacCatalyst versioning with iOS, ensuring consistent version components.
31+
32+
## Recommended action
33+
34+
Use versions of up to three components (major, minor, and build) on MacCatalyst.
35+
36+
## Affected APIs
37+
38+
- <xref:System.OperatingSystem.IsMacCatalystVersionAtLeast(System.Int32,System.Int32,System.Int32)?displayProperty=fullName>
39+
- <xref:System.OperatingSystem.IsOSPlatformVersionAtLeast(System.String,System.Int32,System.Int32,System.Int32,System.Int32)?displayProperty=fullName>
40+
- <xref:System.Environment.OSVersion?displayProperty=fullName>

0 commit comments

Comments
 (0)
Please sign in to comment.