Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

.NET 10 Preview 1 breaking changes batch #44625

Open
wants to merge 20 commits into
base: main
Choose a base branch
from

Conversation

CamSoper
Copy link
Contributor

@CamSoper CamSoper commented Jan 30, 2025

Collection of breaking changes for .NET 10 Preview 1.

Fixes #44403
Fixes #44500
Fixes #44282
Fixes #43952
Fixes #43885
Fixes #43828
Fixes #43303
Fixes #43284
Fixes #43156
Fixes #42558
Fixes #42027


Internal previews

Toggle expand/collapse
📄 File 🔗 Preview link
docs/core/compatibility/10.0.md docs/core/compatibility/10.0
docs/core/compatibility/core-libraries/10.0/activity-sampling.md docs/core/compatibility/core-libraries/10.0/activity-sampling
docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution
docs/core/compatibility/core-libraries/10.0/generic-math.md docs/core/compatibility/core-libraries/10.0/generic-math
docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing
docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization
docs/core/compatibility/core-libraries/10.0/obsolete-apis.md docs/core/compatibility/core-libraries/10.0/obsolete-apis
docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation
docs/core/compatibility/globalization/10.0/version-override.md docs/core/compatibility/globalization/10.0/version-override
docs/core/compatibility/toc.yml docs/core/compatibility/toc
docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation
docs/core/compatibility/windows-forms/10.0/treeview-text-location.md docs/core/compatibility/windows-forms/10.0/treeview-text-location
docs/fundamentals/syslib-diagnostics/obsoletions-overview.md docs/fundamentals/syslib-diagnostics/obsoletions-overview
docs/fundamentals/syslib-diagnostics/syslib0058.md docs/fundamentals/syslib-diagnostics/syslib0058
docs/fundamentals/syslib-diagnostics/syslib0060.md docs/fundamentals/syslib-diagnostics/syslib0060
docs/navigate/tools-diagnostics/toc.yml docs/navigate/tools-diagnostics/toc

@CamSoper CamSoper self-assigned this Jan 30, 2025
@CamSoper CamSoper requested review from gewarren and a team as code owners January 30, 2025 20:35
@dotnetrepoman dotnetrepoman bot added this to the January 2025 milestone Jan 30, 2025
@CamSoper CamSoper marked this pull request as draft January 30, 2025 20:36
@CamSoper CamSoper removed request for a team and gewarren January 30, 2025 20:36
@CamSoper CamSoper changed the title .NET 10 Preview 1 breaking changes first batch .NET 10 Preview 1 breaking changes batch Jan 31, 2025
@CamSoper CamSoper marked this pull request as ready for review January 31, 2025 00:49
@CamSoper CamSoper requested review from gewarren and a team January 31, 2025 00:49
Copy link
Contributor

@gewarren gewarren left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not finished, but some comments for now.

---
# SYSLIB0060: Rfc2898DeriveBytes constructors are obsolete

Starting in .NET 10, all of the constructors on <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType> are obsolete. Referencing this event in code generates warning `SYSLIB0060` at compile time.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Starting in .NET 10, all of the constructors on <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType> are obsolete. Referencing this event in code generates warning `SYSLIB0060` at compile time.
Starting in .NET 10, all of the constructors on <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType> are obsolete. Calling these constructors in code generates warning `SYSLIB0060` at compile time.


## Reason for obsoletion

The instance-based implementation of PBKDF2, which <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType> 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 <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2*?displayProperty=nameWithType> and should be used instead of instantiating <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The instance-based implementation of PBKDF2, which <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType> 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 <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2*?displayProperty=nameWithType> and should be used instead of instantiating <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType>.
The instance-based implementation of PBKDF2, which <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType> 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 <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2*?displayProperty=nameWithType> and should be used instead of instantiating <xref:System.Security.Cryptography.Rfc2898DeriveBytes?displayProperty=nameWithType>.

---
# X500DistinguishedName validation is stricter

Starting in .NET 10, the <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedName.%23ctor*> constructor that accepts a string-encoded distinguished name may reject previously accepted invalid input or encode it differently on non-Windows systems. This aligns with encoding specifications and Windows behavior.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Starting in .NET 10, the <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedName.%23ctor*> constructor that accepts a string-encoded distinguished name may reject previously accepted invalid input or encode it differently on non-Windows systems. This aligns with encoding specifications and Windows behavior.
Starting in .NET 10, the <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedName.%23ctor*> 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 would permit incorrect distinguished names or encode them in a way not permitted by X.520 encoding rules. The <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedNameFlags.ForceUTF8Encoding?displayProperty=nameWithType> flag would force components to use a UTF8String even if it was not a valid representation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Previous versions of .NET on non-Windows systems would permit incorrect distinguished names or encode them in a way not permitted by X.520 encoding rules. The <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedNameFlags.ForceUTF8Encoding?displayProperty=nameWithType> flag would force components to use a UTF8String even if it was not a valid representation.
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 <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedNameFlags.ForceUTF8Encoding?displayProperty=nameWithType> flag forced components to use a UTF8String even if it wasn't a valid representation.


## New behavior

Starting in .NET 10, components violating encoding rules will throw a `CryptographicException` on non-Windows systems, matching Windows behavior. The <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedNameFlags.ForceUTF8Encoding?displayProperty=nameWithType> flag will only UTF-8 encode components when permissible.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Starting in .NET 10, components violating encoding rules will throw a `CryptographicException` on non-Windows systems, matching Windows behavior. The <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedNameFlags.ForceUTF8Encoding?displayProperty=nameWithType> flag will only UTF-8 encode components when permissible.
Starting in .NET 10, components that violate encoding rules throw a `CryptographicException` on non-Windows systems, matching Windows behavior. The <xref:System.Security.Cryptography.X509Certificates.X500DistinguishedNameFlags.ForceUTF8Encoding?displayProperty=nameWithType> flag only UTF-8 encodes components when permissible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've always included an Affected APIs section, and just put N/A if there are none. There's a tool that reads these files and it might expect that section.

@@ -0,0 +1,57 @@
---
title: "Breaking change: Renamed parameter in HtmlElement.InsertAdjacentElement"
description: Learn about the .NET 10 Preview 1 breaking change in core .NET libraries where the parameter `orient` was renamed to `orientation`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: Learn about the .NET 10 Preview 1 breaking change in core .NET libraries where the parameter `orient` was renamed to `orientation`.
description: Learn about the .NET 10 Preview 1 breaking change in Windows Forms where the parameter `orient` was renamed to `orientation`.

@@ -0,0 +1,32 @@
---
title: "Breaking change: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE"
description: Learn about the .NET 10 breaking change in core .NET libraries where the environment variable CLR_ICU_VERSION_OVERRIDE was renamed to DOTNET_ICU_VERSION_OVERRIDE.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: Learn about the .NET 10 breaking change in core .NET libraries where the environment variable CLR_ICU_VERSION_OVERRIDE was 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.

@@ -0,0 +1,58 @@
---
title: "Breaking change: X500DistinguishedName validation is stricter"
description: Learn about the .NET 10 breaking change in core .NET libraries where X500DistinguishedName validation is stricter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: Learn about the .NET 10 breaking change in core .NET libraries where X500DistinguishedName validation is stricter.
description: Learn about the .NET 10 breaking change in cryptography where X500DistinguishedName validation is stricter.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to list the affected APIs for each in the Affected APIs section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment