diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 91ded5b8daec0..3cfb3b62328eb 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -2,7 +2,8 @@ title: Breaking changes in .NET 10 titleSuffix: "" description: Navigate to the breaking changes in .NET 10. -ms.date: 12/19/2024 +ms.date: 01/30/2025 +ai-usage: ai-assisted no-loc: [Blazor, Razor, Kestrel] --- # 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 ## Core .NET libraries -| Title | Type of change | Introduced version | -|------------------------------------------------------------------------------------------|---------------------|--------------------| -| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 | +| Title | Type of change | Introduced version | +|----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| +| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 | +| [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 | +| [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 | + +## Globalization + +| Title | Type of change | Introduced version | +|-------------------------------------------------------------------------------------------------------|-------------------|--------------------| +| [Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE](globalization/10.0/version-override.md) | Behavioral change | Preview 1 | + +## Cryptography + +| Title | Type of change | Introduced version | +|--------------------------------------------------------------------------------------------------------|-------------------|--------------------| +| [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 | + +## Windows Forms + +| Title | Type of change | Introduced version | +|-------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| +| [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 | +| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md new file mode 100644 index 0000000000000..04c63c8246214 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -0,0 +1,61 @@ +--- +title: "Breaking change: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior changes" +description: Learn about the .NET 10.0 breaking change in core .NET libraries where ActivitySource.CreateActivity and ActivitySource.StartActivity behavior is modified. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change + +The and APIs only return an when there's a registered listener that decides the instance should be created. This is generally known as sampling. + +The enum defines the possible sampling decisions. + +When creating an `Activity` without a parent, `ActivitySamplingResult` drives whether the `Activity` is created and then how the `Recorded` and `IsAllDataRequested` properties are set: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|None|No||| +|PropagationData|Yes|False|False| +|AllData|Yes|False|True| +|AllDataAndRecorded|Yes|True|True| + +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. + +## Previous behavior + +Previously, when creating an `Activity` as `PropagationData` with a parent marked as `Recorded`, the `Recorded` and `IsAllDataRequested` properties were set as follows: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|PropagationData|Yes|True|False| + +## New behavior + +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: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|PropagationData|Yes|False|False| + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The previous behavior did not follow the OpenTelemetry specification. + +## Recommended action + +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. + +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. + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md b/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md new file mode 100644 index 0000000000000..5033409d99d93 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md @@ -0,0 +1,51 @@ +--- +title: "Breaking change: C# 14 overload resolution with span parameters" +description: Learn about the .NET 10 breaking change in core .NET libraries where overloads with span parameters are applicable in more scenarios. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# C# 14 overload resolution with span parameters + +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. + +## Previous behavior + +In C# 13 and earlier, an extension method taking a `ReadOnlySpan` or `Span` 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. + +## New behavior + +In C# 14 and later, methods with `ReadOnlySpan` or `Span` 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. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The C# language feature allows simplified API design and usage (for example, one extension method can apply to both spans and arrays). + +## Recommended action + +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: + +```csharp +using System; +using System.Collections.Generic; +using System.Linq; +using System.Linq.Expressions; + +M((array, num) => array.Contains(num)); // fails, binds to MemoryExtensions.Contains +M((array, num) => ((IEnumerable)array).Contains(num)); // ok, binds to Enumerable.Contains +M((array, num) => array.AsEnumerable().Contains(num)); // ok, binds to Enumerable.Contains +M((array, num) => Enumerable.Contains(array, num)); // ok, binds to Enumerable.Contains + +void M(Expression> e) => e.Compile(preferInterpretation: true); +``` + +## Affected APIs + +- diff --git a/docs/core/compatibility/core-libraries/10.0/generic-math.md b/docs/core/compatibility/core-libraries/10.0/generic-math.md new file mode 100644 index 0000000000000..7d418a0d0678c --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/generic-math.md @@ -0,0 +1,39 @@ +--- +title: "Breaking change: Consistent shift behavior in generic math" +description: Learn about the .NET 10 breaking change in core .NET libraries where shift operations in generic math now have consistent behavior. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# Consistent shift behavior in generic math + +Shift operations in generic math now have consistent behavior across all built-in integer types. + +## Previous behavior + +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. + +## New behavior + +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 interface. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The behavior differed from the designed behavior due to a difference in how masking works for small integer types in C#. + +## Recommended action + +Update any code that relies on the previous inconsistent behavior to ensure it works with the new consistent behavior. + +## Affected APIs + +- `operator <<` +- `operator >>` +- `operator >>>` for `byte`, `char`, `sbyte`, `short`, and `ushort` when used via generic math, which requires a `T` constrained to `where T : IShiftOperators` or a similar interface. diff --git a/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md new file mode 100644 index 0000000000000..ba4bf5d6e8030 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md @@ -0,0 +1,63 @@ +--- +title: "Breaking change: LDAP DirectoryControl parsing is now more stringent" +description: Learn about the .NET 10 breaking change in core .NET libraries where LDAP DirectoryControl parsing is now more stringent. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- + +# LDAP DirectoryControl parsing is now more stringent + +Previously, .NET used to parse the objects it received over the network and to generate the byte arrays it sent. used the OS-specific BER parsing functionality. This parsing functionality is now implemented in managed code. + +## Previous behavior + +As a result of using , the parsing of objects was fairly loose: + +- The ASN.1 tags of each value weren't checked. +- Trailing data after the end of the parsed DirectoryControl was ignored, as was trailing data within an ASN.1 SEQUENCE. +- On Linux, OCTET STRING lengths that extended beyond the end of their parent sequence returned data outside the parent sequence. +- On earlier versions of Windows, a zero-length OCTET STRING returned `null` rather than an empty string. +- When reading the contents of a as a UTF8-encoded string, an invalid UTF8 sequence did not throw an exception. +- When passing an invalid UTF8 string to the constructor of [VlvRequestControl](xref:System.DirectoryServices.Protocols.VlvRequestControl), no exception was thrown. + +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. + +## New behavior + +The DirectoryControl parsing is much more stringent, and is now consistent across platforms and versions: + +- ASN.1 tags are now checked. +- Trailing data is no longer permitted. +- The length of `OCTET STRING`s and `SEQUENCE`s is now checked. +- Zero-length `OCTET STRING`s now always return an empty string. +- If the server sends an invalid UTF8 byte sequence, the parsing logic now throws an exception rather than silently substituting the invalid characters with a known value. + +We also validate errors more thoroughly when calling the constructor. Passing a string which cannot be encoded as a UTF8 value now throws an . + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +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)): + +> 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: + +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.) + +For the 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. + +## Recommended action + +Servers should comply with the RFCs and specifications. Make sure to handle an when calling the constructor. + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md b/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md new file mode 100644 index 0000000000000..bd0bc72aed39a --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md @@ -0,0 +1,40 @@ +--- +title: "Breaking change: MacCatalyst version normalization" +description: Learn about the .NET 10 breaking change in core .NET libraries where MacCatalyst version components are normalized. +ms.date: 01/01/2025 +ai-usage: ai-assisted +--- + +# MacCatalyst version normalization + +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. + +## Previous behavior + +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. + +## New behavior + +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. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This changed was made to prevent incorrect version checks and align MacCatalyst versioning with iOS, ensuring consistent version components. + +## Recommended action + +Use versions of up to three components (major, minor, and build) on MacCatalyst. + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md index 2a5e9c98f4344..391fcf47ee01c 100644 --- a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md +++ b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md @@ -3,6 +3,7 @@ title: "Breaking change: .NET 10 obsoletions with custom IDs" titleSuffix: "" description: Learn about the APIs that have been marked as obsolete in .NET 10 with a custom diagnostic ID. ms.date: 01/14/2025 +ai-usage: ai-assisted --- # API obsoletions with non-default diagnostic IDs (.NET 10) @@ -16,11 +17,13 @@ The following table lists the custom diagnostic IDs and their corresponding warn | Diagnostic ID | Description | Severity | |---------------|-------------|----------| +| [SYSLIB0058](../../../../fundamentals/syslib-diagnostics/syslib0058.md) | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | Warning | | [SYSLIB0059](../../../../fundamentals/syslib-diagnostics/syslib0059.md) | callbacks aren't run before the process exits. Use instead. | Warning | +| [SYSLIB0060](../../../../fundamentals/syslib-diagnostics/syslib0060.md) | constructors are obsolete. Use instead. | Warning | ## Version introduced -.NET 9 +.NET 10 ## Type of breaking change @@ -34,10 +37,27 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c ## Affected APIs +### SYSLIB0058 + +- +- +- +- +- +- +- +- +- + ### SYSLIB0059 - +### SYSLIB0060 + +- +- + ## See also - [API obsoletions with non-default diagnostic IDs (.NET 9)](../9.0/obsolete-apis-with-custom-diagnostics.md) diff --git a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md new file mode 100644 index 0000000000000..150dd22b4fcdb --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md @@ -0,0 +1,59 @@ +--- +title: "Breaking change: X500DistinguishedName validation is stricter" +description: Learn about the .NET 10 breaking change in cryptography where X500DistinguishedName validation is stricter. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# X500DistinguishedName validation is stricter + +Starting in .NET 10, the constructor that accepts a string-encoded distinguished name might reject previously accepted invalid input or encode it differently on non-Windows systems. This aligns with encoding specifications and Windows behavior. + +## Previous behavior + +Previous versions of .NET on non-Windows systems permitted incorrect distinguished names or encoded them in a way not permitted by X.520 encoding rules. The flag forced components to use a UTF8String even if it wasn't a valid representation. + +## New behavior + +Starting in .NET 10, components that violate encoding rules throw a on non-Windows systems, matching Windows behavior. The flag only UTF-8 encodes components when permissible. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Different X.500 components have specific encoding rules. For example, `id-at-telephoneNumber` must be encoded as an ASN.1 . The exclamation point character is invalid for a PrintableString. Consider the following code: + +```csharp +new X500DistinguishedName("Phone=!!"); +``` + +This code threw an exception on Windows but was encoded as a UTF8String on non-Windows. Similarly, using forced UTF8String encoding even when not permitted: + +```csharp +new X500DistinguishedName("Phone=000-555-1234", X500DistinguishedNameFlags.ForceUTF8Encoding); +``` + +This change ensures encoding aligns with specifications and Windows behavior. + +## Recommended action + +Generally, no action is needed unless compatibility with incorrect encoding is required. Use to create instances with desired encoding: + +```csharp +using System.Formats.Asn1; +using System.Security.Cryptography.X509Certificates; + +X500DistinguishedNameBuilder builder = new(); +builder.Add("2.5.4.20", "000-555-1234", UniversalTagNumber.UTF8String); +X500DistinguishedName dn = builder.Build(); +``` + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/globalization/10.0/version-override.md b/docs/core/compatibility/globalization/10.0/version-override.md new file mode 100644 index 0000000000000..fc1cc13e80a3b --- /dev/null +++ b/docs/core/compatibility/globalization/10.0/version-override.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE" +description: Learn about the .NET 10 breaking change in globalization where the environment variable CLR_ICU_VERSION_OVERRIDE was renamed to DOTNET_ICU_VERSION_OVERRIDE. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- + +# Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + +.NET previously supported a configuration-switch environment variable called `CLR_ICU_VERSION_OVERRIDE`, which allowed users to specify the preferred ICU library version for apps running on Linux. In .NET 10, this environment variable has been renamed to `DOTNET_ICU_VERSION_OVERRIDE` to align with the naming convention of other configuration switch environment variables in .NET. + +## Previous behavior + +The `CLR_ICU_VERSION_OVERRIDE` environment variable was used to specify the preferred ICU version to be loaded in the application. + +## New behavior + +The `DOTNET_ICU_VERSION_OVERRIDE` environment variable is used to specify the preferred ICU version to be loaded in the application. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change ensures the environment variable is consistent with the naming convention used for all [.NET environment variables](../../../tools/dotnet-environment-variables.md). + +## Recommended action + +If you have a .NET 10 app that previously used the `CLR_ICU_VERSION_OVERRIDE` environment variable, use `DOTNET_ICU_VERSION_OVERRIDE` instead. + +## Affected APIs + +N/A diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 3a923d1625876..d512dd2bc91aa 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -12,6 +12,30 @@ items: items: - name: API obsoletions with non-default diagnostic IDs 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: C# 14 overload resolution with span parameters + 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: LDAP DirectoryControl parsing is now more stringent + href: core-libraries/10.0/ldap-directorycontrol-parsing.md + - name: MacCatalyst version normalization + href: core-libraries/10.0/maccatalyst-version-normalization.md + - name: Cryptography + items: + - name: X500DistinguishedName validation is stricter + href: cryptography/10.0/x500distinguishedname-validation.md + - name: Globalization + items: + - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + href: globalization/10.0/version-override.md + - name: Windows Forms + items: + - name: Renamed parameter in HtmlElement.InsertAdjacentElement + href: windows-forms/10.0/insertadjacentelement-orientation.md + - name: TreeView checkbox image truncation + href: windows-forms/10.0/treeview-text-location.md - name: .NET 9 items: - name: Overview @@ -1312,6 +1336,16 @@ items: items: - name: API obsoletions with non-default diagnostic IDs 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: C# 14 overload resolution with span parameters + 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: LDAP DirectoryControl parsing is now more stringent + href: core-libraries/10.0/ldap-directorycontrol-parsing.md + - name: MacCatalyst version normalization + href: core-libraries/10.0/maccatalyst-version-normalization.md - name: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags @@ -1546,6 +1580,10 @@ items: href: corefx.md - name: Cryptography items: + - name: .NET 10 + items: + - name: X500DistinguishedName validation is stricter + href: cryptography/10.0/x500distinguishedname-validation.md - name: .NET 9 items: - name: SafeEvpPKeyHandle.DuplicateHandle up-refs the handle @@ -1674,6 +1712,10 @@ items: href: extensions/6.0/service-provider-disposed.md - name: Globalization items: + - name: .NET 10 + items: + - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + href: globalization/10.0/version-override.md - name: .NET 8 items: - name: Date and time converters honor culture argument @@ -2046,6 +2088,12 @@ items: href: wcf-client/6.0/duplex-synchronization-context.md - name: Windows Forms items: + - name: .NET 10 + items: + - name: Renamed parameter in HtmlElement.InsertAdjacentElement + href: windows-forms/10.0/insertadjacentelement-orientation.md + - name: TreeView checkbox image truncation + href: windows-forms/10.0/treeview-text-location.md - name: .NET 9 items: - name: BindingSource.SortDescriptions doesn't return null diff --git a/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md new file mode 100644 index 0000000000000..afb741bde02eb --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md @@ -0,0 +1,54 @@ +--- +title: "Breaking change: Renamed parameter in HtmlElement.InsertAdjacentElement" +description: Learn about the .NET 10 Preview 1 breaking change in Windows Forms where the parameter `orient` was renamed to `orientation`. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- + +# Renamed parameter in HtmlElement.InsertAdjacentElement + + parameter `orient` was renamed to `orientation`. + +## Previous behavior + +Calls to included the `orient` parameter: + +```csharp +element.InsertAdjacentElement(orient: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## New behavior + +The new parameter name is `orientation`. + +```csharp +element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +The parameter name was changed to provide a more descriptive name. + +## Recommended action + +Edit any calls with a named argument to use the new parameter name or remove the parameter name: + +```csharp +element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +```csharp +element.InsertAdjacentElement(HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## Affected APIs + +- diff --git a/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md new file mode 100644 index 0000000000000..01307f712a5b8 --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md @@ -0,0 +1,52 @@ +--- +title: "Breaking change: TreeView checkbox image truncation" +description: Learn about the .NET 10 breaking change in Windows Forms where the TreeView checkbox image is truncated under certain conditions. +ms.date: 01/30/2025 +--- +# TreeView checkbox image truncation + +The in the control allows users to customize the DrawMode and add checkboxes. However, the checkbox image will be truncated due to the position of the TreeNode text drawing. To avoid affecting normal, common use, you can use an AppContext switch setting to avoid checkbox truncation in these specific situations. + +The checkbox image is truncated when all of the following conditions are met: + +- `CheckBoxes` is set to `true` +- `DrawMode` is set to `OwnerDrawText` +- `DrawDefault` is set to `true` in the `OnDrawNode` event + +## Previous behavior + +In previous versions, when the TreeView control had `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event, the TreeNode checkbox images were shown truncated on the right border. + +## New behavior + +By setting the switch `"System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": true` in the project's runtime config file, the TreeNode checkboxes are displayed completely when the TreeView has `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change ensures that the checkbox of the node in the TreeView control can be fully displayed. + +## Recommended action + +Manually add `"System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": true` to the project's *runtimeconfig.json* file to enable the switch. + +```json +{ + "runtimeOptions": { + "configProperties": { + "System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": true + } + } +} +``` + +## Affected APIs + +- diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index b7ca9e2eef5c1..fac18796d6033 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -1,8 +1,8 @@ --- title: Obsolete features in .NET 5+ -titleSuffix: "" description: Learn about APIs that are marked as obsolete in .NET 5 and later versions that produce SYSLIB compiler warnings. ms.date: 01/14/2025 +ai-usage: ai-assisted --- # Obsolete features in .NET 5+ @@ -80,6 +80,7 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+ | [SYSLIB0057](syslib0057.md) | Warning | `X509Certificate2` and `X509Certificate` constructors for binary and file content are obsolete. | | SYSLIB0058 | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | | [SYSLIB0059](syslib0059.md) | Warning | callbacks aren't run before the process exits. Use instead. | +| [SYSLIB0060](syslib0060.md) | Warning | Constructors on are obsolete. Use instead. | ## Suppress warnings diff --git a/docs/fundamentals/syslib-diagnostics/syslib0058.md b/docs/fundamentals/syslib-diagnostics/syslib0058.md new file mode 100644 index 0000000000000..efb7a660f80c3 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0058.md @@ -0,0 +1,58 @@ +--- +title: SYSLIB0058 warning - Certain SslStream properties are obsolete +description: Learn about the obsoletion of ExchangeAlgorithmType, CipherAlgorithmType, and HashAlgorithmType enums that generates compile-time warning SYSLIB0058. +ms.date: 01/01/2025 +ai-usage: ai-assisted +f1_keywords: + - SYSLIB0058 +--- +# SYSLIB0058: Certain SslStream properties are obsolete + +The following properties of are obsolete, starting in .NET 10: + +- +- +- +- +- +- + +, , and enums are obsolete since they were only used by the class. + +## Reason for obsoletion + +The obsoleted enum types were outdated and missing members for covering new algorithms. Since the same information is available via , the outdated properties were removed to clarify which one should be used for logging/auditing purposes. + +## Workaround + +Use instead. + +## Suppress a warning + +If you must use the obsolete API, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0058 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0058 +``` + +To suppress all the `SYSLIB0058` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0058 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). diff --git a/docs/fundamentals/syslib-diagnostics/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md new file mode 100644 index 0000000000000..eba580531f6ff --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -0,0 +1,64 @@ +--- +title: SYSLIB0060 warning - Rfc2898DeriveBytes constructors are obsolete +description: Learn about the obsoletion of Rfc2898DeriveBytes constructors. Use of these constructors generates compile-time warning SYSLIB0060. +ms.date: 01/30/2025 +ai-usage: ai-assisted +f1_keywords: + - SYSLIB0060 +--- +# SYSLIB0060: Rfc2898DeriveBytes constructors are obsolete + +Starting in .NET 10, all of the constructors on are obsolete. Calling these constructors in code generates warning `SYSLIB0060` at compile time. + +## Reason for obsoletion + +The instance-based implementation of PBKDF2, which provides, offers a non-standard usage by "streaming" bytes back by allowing successive calls to `GetBytes`. This is not the intended use of PBKDF2; the algorithm should be used as a one-shot. The one-shot functionality exists as the static method and should be used instead of instantiating . + +## Workaround + +Change instances of and calls to `GetBytes` to use the one-shot static method instead. + +For example, change: + +```csharp +using System.Security.Cryptography; + +Rfc2898DeriveBytes kdf = new Rfc2898DeriveBytes(password, salt, iterations, hashAlgorithm); +byte[] derivedKey = kdf.GetBytes(64); +``` + +to + +```csharp +byte[] derivedKey = Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, hashAlgorithm, 64); +``` + +## Suppress a warning + +If you must use the obsolete API, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0060 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0060 +``` + +To suppress all the `SYSLIB0060` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0060 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index bbf8858b1f20e..de24d0465b7f0 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1822,8 +1822,12 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0056.md - name: SYSLIB0057 href: ../../fundamentals/syslib-diagnostics/syslib0057.md + - name: SYSLIB0058 + href: ../../fundamentals/syslib-diagnostics/syslib0058.md - name: SYSLIB0059 href: ../../fundamentals/syslib-diagnostics/syslib0059.md + - name: SYSLIB0060 + href: ../../fundamentals/syslib-diagnostics/syslib0060.md - name: Experimental features items: - name: Overview