From 500bd961c043e189c28808694160746da22d9139 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 20:32:54 +0000 Subject: [PATCH 01/24] issues/44500 --- docs/core/compatibility/10.0.md | 8 ++- .../10.0/rfc2898derivebytes-constructors.md | 53 +++++++++++++++++++ docs/core/compatibility/toc.yml | 8 +++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 91ded5b8daec0..91fa19374bab4 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: 12/19/2024 +ms.date: 01/30/2025 no-loc: [Blazor, Razor, Kestrel] --- # Breaking changes in .NET 10 @@ -20,3 +20,9 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |------------------------------------------------------------------------------------------|---------------------|--------------------| | [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 | + +## Cryptography + +| Title | Type of change | Introduced version | +|------------------------------------------------------------------------------------------------------|---------------------|--------------------| +| [Rfc2898DeriveBytes constructors are obsolete](cryptography/10.0/rfc2898derivebytes-constructors.md) | Source incompatible | Preview 1 | diff --git a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md new file mode 100644 index 0000000000000..135a5534f788a --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md @@ -0,0 +1,53 @@ +--- +title: "Breaking change: Rfc2898DeriveBytes constructors are obsolete" +description: Learn about the .NET 10 breaking change in core .NET libraries where Rfc2898DeriveBytes constructors are obsolete. +ms.date: 10/10/2023 +--- +# Rfc2898DeriveBytes constructors are obsolete + +Starting in .NET 10, all of the constructors on `Rfc2898DeriveBytes` are obsolete. + +## Previous behavior + +The `Rfc2898DeriveBytes` had constructors that were not obsolete, or obsolete under a different diagnostic ID. + +## New behavior + +The `Rfc2898DeriveBytes` constructors are obsolete with SYSLIB0060 diagnostic ID and message: + +> The constructors on Rfc2898DeriveBytes are obsolete. Use the static Pbkdf2 method instead. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [source incompatible](../../categories.md#source-incompatible) change. + +## Reason for change + +The instance-based implementation of PBKDF2, which `Rfc2898DeriveBytes` 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 [`Rfc2898DeriveBytes.Pbkdf2`](https://learn.microsoft.com/dotnet/api/system.security.cryptography.rfc2898derivebytes.pbkdf2) and should be used instead of instantiating `Rfc2898DeriveBytes`. + +## Recommended action + +Change instances of `Rfc2898DeriveBytes` and calls to `GetBytes` to use the `Pkbdf2` 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); +``` + +## Affected APIs + +- \ No newline at end of file diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 3a923d1625876..8d352a3bdbe31 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -12,6 +12,10 @@ items: items: - name: API obsoletions with non-default diagnostic IDs href: core-libraries/10.0/obsolete-apis.md + - name: Cryptography + items: + - name: RRfc2898DeriveBytes constructors are obsolete + href: cryptography/10.0/rfc2898derivebytes-constructors.md - name: .NET 9 items: - name: Overview @@ -1546,6 +1550,10 @@ items: href: corefx.md - name: Cryptography items: + - name: .NET 10 + items: + - name: Rfc2898DeriveBytes constructors are obsolete + href: cryptography/10.0/rfc2898derivedbytes-constructors.md - name: .NET 9 items: - name: SafeEvpPKeyHandle.DuplicateHandle up-refs the handle From a0905d2215eb3e617e486eff68b88f7eb808162b Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 20:58:27 +0000 Subject: [PATCH 02/24] Fix for 44500 --- .../cryptography/10.0/rfc2898derivebytes-constructors.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md index 135a5534f788a..5ba488aef8347 100644 --- a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md +++ b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md @@ -1,7 +1,7 @@ --- title: "Breaking change: Rfc2898DeriveBytes constructors are obsolete" description: Learn about the .NET 10 breaking change in core .NET libraries where Rfc2898DeriveBytes constructors are obsolete. -ms.date: 10/10/2023 +ms.date: 01/30/2025 --- # Rfc2898DeriveBytes constructors are obsolete @@ -23,7 +23,7 @@ The `Rfc2898DeriveBytes` constructors are obsolete with SYSLIB0060 diagnostic ID ## Type of breaking change -This change is a [source incompatible](../../categories.md#source-incompatible) change. +These obsoletions can affect [source compatibility](../../categories.md#source-compatibility). ## Reason for change @@ -50,4 +50,4 @@ byte[] derivedKey = Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, hashAl ## Affected APIs -- \ No newline at end of file +- (all overloads) From 11191b6247ce40c49d2519c5b6c0857b7851a2a2 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 21:35:11 +0000 Subject: [PATCH 03/24] tweaks to 44500, issue 44403 --- docs/core/compatibility/10.0.md | 8 +-- .../10.0/rfc2898derivebytes-constructors.md | 2 +- docs/core/compatibility/toc.yml | 14 ++--- .../10.0/treeview-text-location.md | 41 ++++++++++++ .../obsoletions-overview.md | 1 + .../syslib-diagnostics/syslib0060.md | 63 +++++++++++++++++++ 6 files changed, 117 insertions(+), 12 deletions(-) create mode 100644 docs/core/compatibility/windows-forms/10.0/treeview-text-location.md create mode 100644 docs/fundamentals/syslib-diagnostics/syslib0060.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 91fa19374bab4..43ab96aeb6789 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -21,8 +21,8 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af |------------------------------------------------------------------------------------------|---------------------|--------------------| | [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 | -## Cryptography +## Windows Forms -| Title | Type of change | Introduced version | -|------------------------------------------------------------------------------------------------------|---------------------|--------------------| -| [Rfc2898DeriveBytes constructors are obsolete](cryptography/10.0/rfc2898derivebytes-constructors.md) | Source incompatible | Preview 1 | +| Title | Type of change | Introduced version | +|----------------------------------------------------------------------------------------------------|---------------------|--------------------| +| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md index 5ba488aef8347..933e1bd5dc98c 100644 --- a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md +++ b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md @@ -23,7 +23,7 @@ The `Rfc2898DeriveBytes` constructors are obsolete with SYSLIB0060 diagnostic ID ## Type of breaking change -These obsoletions can affect [source compatibility](../../categories.md#source-compatibility). +This change can affect[source compatibility](../../categories.md#source-compatibility). ## Reason for change diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 8d352a3bdbe31..d8468d140cbd9 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -12,10 +12,10 @@ items: items: - name: API obsoletions with non-default diagnostic IDs href: core-libraries/10.0/obsolete-apis.md - - name: Cryptography + - name: Windows Forms items: - - name: RRfc2898DeriveBytes constructors are obsolete - href: cryptography/10.0/rfc2898derivebytes-constructors.md + - name: TreeView checkbox image truncation + href: windows-forms/10.0/treeview-text-location.md - name: .NET 9 items: - name: Overview @@ -1550,10 +1550,6 @@ items: href: corefx.md - name: Cryptography items: - - name: .NET 10 - items: - - name: Rfc2898DeriveBytes constructors are obsolete - href: cryptography/10.0/rfc2898derivedbytes-constructors.md - name: .NET 9 items: - name: SafeEvpPKeyHandle.DuplicateHandle up-refs the handle @@ -2054,6 +2050,10 @@ items: href: wcf-client/6.0/duplex-synchronization-context.md - name: Windows Forms items: + - name: .NET 10 + items: + - 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/treeview-text-location.md b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md new file mode 100644 index 0000000000000..458137299798b --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md @@ -0,0 +1,41 @@ +--- +title: "Breaking change: TreeView checkbox image truncation" +description: Learn about the .NET 10 Preview 1 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 TreeNode in the TreeView 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, an AppContext switch setting is added to solve the problem of checkbox truncation in these specific situations. + +The conditions under which the checkbox image is truncated are: +- `CheckBoxes` is set to `true` +- `DrawMode` is set to `OwnerDrawText` +- `DrawDefault` is set to `true` in the `OnDrawNode` event + +## Previous behavior + +When the TreeView control has `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event, the TreeNode checkbox images are 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 will be 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. + +## Affected APIs + +- \ No newline at end of file diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index b7ca9e2eef5c1..b356175c21142 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -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/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md new file mode 100644 index 0000000000000..1b96f44ef529e --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -0,0 +1,63 @@ +--- +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/01/2025 +f1_keywords: + - SYSLIB0060 +--- +# SYSLIB0060: Rfc2898DeriveBytes constructors are obsolete + +Starting in .NET 10, all of the constructors on are obsolete. Referencing this event 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). From 2771ee76050c40a7aa12d2894b69825da42d2c0d Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 21:47:50 +0000 Subject: [PATCH 04/24] linting --- .../10.0/rfc2898derivebytes-constructors.md | 53 ------------------- .../10.0/treeview-text-location.md | 3 +- 2 files changed, 2 insertions(+), 54 deletions(-) delete mode 100644 docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md diff --git a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md b/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md deleted file mode 100644 index 933e1bd5dc98c..0000000000000 --- a/docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Breaking change: Rfc2898DeriveBytes constructors are obsolete" -description: Learn about the .NET 10 breaking change in core .NET libraries where Rfc2898DeriveBytes constructors are obsolete. -ms.date: 01/30/2025 ---- -# Rfc2898DeriveBytes constructors are obsolete - -Starting in .NET 10, all of the constructors on `Rfc2898DeriveBytes` are obsolete. - -## Previous behavior - -The `Rfc2898DeriveBytes` had constructors that were not obsolete, or obsolete under a different diagnostic ID. - -## New behavior - -The `Rfc2898DeriveBytes` constructors are obsolete with SYSLIB0060 diagnostic ID and message: - -> The constructors on Rfc2898DeriveBytes are obsolete. Use the static Pbkdf2 method instead. - -## Version introduced - -.NET 10 Preview 1 - -## Type of breaking change - -This change can affect[source compatibility](../../categories.md#source-compatibility). - -## Reason for change - -The instance-based implementation of PBKDF2, which `Rfc2898DeriveBytes` 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 [`Rfc2898DeriveBytes.Pbkdf2`](https://learn.microsoft.com/dotnet/api/system.security.cryptography.rfc2898derivebytes.pbkdf2) and should be used instead of instantiating `Rfc2898DeriveBytes`. - -## Recommended action - -Change instances of `Rfc2898DeriveBytes` and calls to `GetBytes` to use the `Pkbdf2` 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); -``` - -## Affected APIs - -- (all overloads) 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 index 458137299798b..7eb7fe2148c74 100644 --- a/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md +++ b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md @@ -8,6 +8,7 @@ ms.date: 01/30/2025 The TreeNode in the TreeView 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, an AppContext switch setting is added to solve the problem of checkbox truncation in these specific situations. The conditions under which the checkbox image is truncated are: + - `CheckBoxes` is set to `true` - `DrawMode` is set to `OwnerDrawText` - `DrawDefault` is set to `true` in the `OnDrawNode` event @@ -38,4 +39,4 @@ Manually add `"System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": ## Affected APIs -- \ No newline at end of file +- From dbab525ac27dbe7984f2b5f1fb373cb77672669c Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 21:52:28 +0000 Subject: [PATCH 05/24] More 44500 --- docs/core/compatibility/core-libraries/10.0/obsolete-apis.md | 3 ++- docs/navigate/tools-diagnostics/toc.yml | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) 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..adc57ce5a72ed 100644 --- a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md +++ b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md @@ -17,10 +17,11 @@ The following table lists the custom diagnostic IDs and their corresponding warn | Diagnostic ID | Description | Severity | |---------------|-------------|----------| | [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 diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index bbf8858b1f20e..c214314a96a98 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1824,6 +1824,8 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0057.md - name: SYSLIB0059 href: ../../fundamentals/syslib-diagnostics/syslib0059.md + - name: SYSLIB0060 + href: ../../fundamentals/syslib-diagnostics/syslib0060.md - name: Experimental features items: - name: Overview From df3711452c9bde0b9ec435b10c0fb19fb956923b Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 21:55:49 +0000 Subject: [PATCH 06/24] xref --- docs/fundamentals/syslib-diagnostics/syslib0060.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md index 1b96f44ef529e..3067eac6b9b07 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0060.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -7,15 +7,15 @@ f1_keywords: --- # SYSLIB0060: Rfc2898DeriveBytes constructors are obsolete -Starting in .NET 10, all of the constructors on are obsolete. Referencing this event in code generates warning `SYSLIB0060` at compile time. +Starting in .NET 10, all of the constructors on are obsolete. Referencing this event 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 . +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. +Change instances of and calls to `GetBytes` to use the one-shot static method instead. For example, change: From d5e8dd9e0502e8732bc0d9214b70f221138a5d47 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 22:13:11 +0000 Subject: [PATCH 07/24] issue 44282 --- docs/core/compatibility/10.0.md | 7 ++- .../core-libraries/10.0/activity-sampling.md | 60 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ .../syslib-diagnostics/syslib0060.md | 2 +- 4 files changed, 69 insertions(+), 4 deletions(-) create mode 100644 docs/core/compatibility/core-libraries/10.0/activity-sampling.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 43ab96aeb6789..ab0ff7e2fdd01 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -17,9 +17,10 @@ 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 | ## Windows Forms 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..35d4993c889fb --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -0,0 +1,60 @@ +--- +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 +--- +# ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change + +The and APIs only return an `Activity` when there is a registered listener which 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 + +When creating an `Activity` as `PropagationData` with a parent marked as `Recorded`: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|PropagationData|Yes|True|False| + +## New behavior + +When creating an `Activity` as `PropagationData` with a parent marked as `Recorded`: + +|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 existing behavior does not follow the OpenTelemetry specification. + +## Recommended action + +Users who have implemented `ActivityListener.Sample` directly AND use `ActivitySamplingResult.PropagationData` should verify they are not reliant on the flawed behavior. `Activity.ActivityTraceFlags` may be set to `Recorded` after the `CreateActivity` or `StartActivity` call to restore the previous behavior. + +Users using OpenTelemetry .NET should verify their sampler configuration. The default OpenTelemetry .NET configuration uses a parent-based algorithm which is not impacted. Only users who have customized the sampler should verify the behavior. + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index d8468d140cbd9..6001ed2d17c46 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -12,6 +12,8 @@ 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: Windows Forms items: - name: TreeView checkbox image truncation @@ -1316,6 +1318,8 @@ 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: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags diff --git a/docs/fundamentals/syslib-diagnostics/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md index 3067eac6b9b07..5afd586452809 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0060.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -1,7 +1,7 @@ --- 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/01/2025 +ms.date: 01/30/2025 f1_keywords: - SYSLIB0060 --- From ac4aa253b410111b9e3e24ba3d2e04df993396b3 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 22:32:19 +0000 Subject: [PATCH 08/24] xref fix --- .../compatibility/core-libraries/10.0/activity-sampling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md index 35d4993c889fb..8d683ce660013 100644 --- a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -56,5 +56,5 @@ Users using OpenTelemetry .NET should verify their sampler configuration. The de ## Affected APIs -- -- +- +- From e52ff759adc05d7cd18016973d4cda7f2d7deab2 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 22:52:44 +0000 Subject: [PATCH 09/24] issue 43952 --- docs/core/compatibility/10.0.md | 1 + .../10.0/csharp-overload-resolution.md | 50 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 55 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index ab0ff7e2fdd01..bf7be9c63de94 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -21,6 +21,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af |----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| | [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](csharp-overload-resolution.md) | Behavioral change | Preview 1 | ## Windows Forms 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..4a840e912efa8 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md @@ -0,0 +1,50 @@ +--- +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 +--- +# C# 14 overload resolution with span parameters + +C# 14 introduces new [built-in span conversions and type inference rules](https://github.com/dotnet/csharplang/issues/7905) making overloads with span parameters applicable in more scenarios. + +## Previous behavior + +In C# 13 and earlier, an extension method taking a `ReadOnlySpan` or `Span` receiver is not applicable to a value of type `T[]`. Therefore, only non-span extension methods like the ones from the `System.Linq.Enumerable` class are 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 runtime 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 (e.g., one ReadOnlySpan extension method can apply to both spans and arrays). + +## Recommended action + +If you need to continue using Expression interpretation, you should make sure the non-span overloads are bound, e.g., by casting arguments to the exact types the method signature takes or calling the extension methods as explicit static invocations: + +```cs +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/toc.yml b/docs/core/compatibility/toc.yml index 6001ed2d17c46..40787e89acb90 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -14,6 +14,8 @@ items: 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: csharp-overload-resolution.md - name: Windows Forms items: - name: TreeView checkbox image truncation @@ -1320,6 +1322,8 @@ items: 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: csharp-overload-resolution.md - name: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags From f07146b0b8b3aa7cc6da5183cd51125ca35e8332 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:00:43 +0000 Subject: [PATCH 10/24] fix linting --- docs/core/compatibility/10.0.md | 2 +- docs/core/compatibility/toc.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index bf7be9c63de94..8ad8d1a6b16ec 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -21,7 +21,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af |----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| | [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](csharp-overload-resolution.md) | Behavioral change | Preview 1 | +| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 | ## Windows Forms diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 40787e89acb90..e2223f0303ad9 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -15,7 +15,7 @@ items: - 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: csharp-overload-resolution.md + href: core-libraries/10.0/csharp-overload-resolution.md - name: Windows Forms items: - name: TreeView checkbox image truncation @@ -1323,7 +1323,7 @@ items: - 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: csharp-overload-resolution.md + href: core-libraries/10.0/csharp-overload-resolution.md - name: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags From 65818cd08c093664f54da633d9392e5edfe896cf Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:11:45 +0000 Subject: [PATCH 11/24] issue 43885 --- docs/core/compatibility/10.0.md | 3 +- .../10.0/ldap-directorycontrol-parsing.md | 62 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 8ad8d1a6b16ec..776d25e644b48 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -21,7 +21,8 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af |----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| | [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 | +| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 | +| [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md) | Behavioral change | Preview 1 | ## Windows Forms 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..cd0e024c4d18f --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md @@ -0,0 +1,62 @@ +--- +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 +--- + +# 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; would use 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 which extended beyond the end of their parent sequence would return data outside the parent sequence. +- On earlier versions of Windows, a zero-length OCTET STRING would return `null` rather than an empty string. +- When reading the contents of a as a UTF8-encoded string, an invalid UTF8 sequence would 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 would always encode ASN.1 tags with a four-byte length while Linux would only use as many bytes for the tag length as it needed. Both representations were valid, but this behavioural difference between platforms is now gone; the Linux behaviour 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 STRINGs and SEQUENCEs is now checked. +- Zero-length OCTET STRINGs will now always return an empty string. +- If the server sends an invalid UTF8 byte sequence, the parsing logic will now throw an exception rather than silently substitute the invalid characters with a known value. + +We also validate errors more thoroughly when calling the VlvRequestControl constructor. Passing a string which cannot be encoded as a UTF8 value will now throw an EncoderFallbackException. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +RFC/spec. 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 below (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 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 which can't be encoded to valid UTF8 bytes. + +## Recommended action + +Servers should comply with the RFCs and specifications. Users should be aware of the need to handle an when calling the constructor. + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index e2223f0303ad9..b2482f6851454 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -16,6 +16,8 @@ items: 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: LDAP DirectoryControl parsing is now more stringent + href: core-libraries/10.0/ldap-directorycontrol-parsing.md - name: Windows Forms items: - name: TreeView checkbox image truncation @@ -1324,6 +1326,8 @@ items: 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: LDAP DirectoryControl parsing is now more stringent + href: core-libraries/10.0/ldap-directorycontrol-parsing.md - name: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags From 5703057698fc0cbc82a1d1a0e207d2cc9de76d35 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:25:30 +0000 Subject: [PATCH 12/24] issue 43828 --- docs/core/compatibility/10.0.md | 6 ++++ .../globalization/10.0/version-override.md | 32 +++++++++++++++++++ docs/core/compatibility/toc.yml | 8 +++++ 3 files changed, 46 insertions(+) create mode 100644 docs/core/compatibility/globalization/10.0/version-override.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 776d25e644b48..3ff7b10241ff5 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -24,6 +24,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 | | [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.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 | + ## Windows Forms | Title | Type of change | Introduced version | 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..943cc4dee38e2 --- /dev/null +++ b/docs/core/compatibility/globalization/10.0/version-override.md @@ -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. +ms.date: 01/30/2025 +--- +# Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + +.NET has previously supported a configuration switch environment variable called `CLR_ICU_VERSION_OVERRIDE`, which allows 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 is 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. + +## Recommended action + +Users running .NET 10 apps who previously used the `CLR_ICU_VERSION_OVERRIDE` environment variable will now need to use `DOTNET_ICU_VERSION_OVERRIDE` instead. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index b2482f6851454..f42c091f83245 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -18,6 +18,10 @@ items: href: core-libraries/10.0/csharp-overload-resolution.md - name: LDAP DirectoryControl parsing is now more stringent href: core-libraries/10.0/ldap-directorycontrol-parsing.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: TreeView checkbox image truncation @@ -1690,6 +1694,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 From ccff70b19680a9e9ebe6ab95aef616a7a04c0767 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:31:06 +0000 Subject: [PATCH 13/24] fix xref --- .../core-libraries/10.0/ldap-directorycontrol-parsing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index cd0e024c4d18f..fe5da0595e101 100644 --- a/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md +++ b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md @@ -57,6 +57,6 @@ Servers should comply with the RFCs and specifications. Users should be aware of ## Affected APIs -- -- -- +- +- +- From 871f31283b3ae8d3bb8a2fd40101ffd3a86afbf6 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:39:02 +0000 Subject: [PATCH 14/24] issue 43303 --- docs/core/compatibility/10.0.md | 1 + .../core-libraries/10.0/generic-math.md | 38 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 43 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/10.0/generic-math.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 3ff7b10241ff5..27471afe9163b 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -22,6 +22,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [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 | ## Globalization 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..203e601eff5e2 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/generic-math.md @@ -0,0 +1,38 @@ +--- +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 +--- +# Consistent shift behavior in generic math + +This document explains the breaking change in .NET 10 where 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 would appropriately mask the shift amount by `sizeof(T) - 1` and in other cases, it would do 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/toc.yml b/docs/core/compatibility/toc.yml index f42c091f83245..5cd6a05624b0b 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -16,6 +16,8 @@ items: 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: Globalization @@ -1330,6 +1332,8 @@ items: 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: .NET 9 From bb151c1608e8ae5ab518128d4d3cd50f9aecb562 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:51:57 +0000 Subject: [PATCH 15/24] issue 43284 --- docs/core/compatibility/10.0.md | 6 ++ .../10.0/x500distinguishedname-validation.md | 59 +++++++++++++++++++ docs/core/compatibility/toc.yml | 8 +++ 3 files changed, 73 insertions(+) create mode 100644 docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 27471afe9163b..33c23ea7ef27f 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -31,6 +31,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af |-------------------------------------------------------------------------------------------------------|-------------------|--------------------| | [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 | 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..3c8505bdcaca9 --- /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 core .NET libraries where X500DistinguishedName validation is stricter. +ms.date: 01/30/2025 +--- +# X500DistinguishedName validation is stricter + +Starting in .NET 10, the 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. + +## 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 flag would force components to use a UTF8String even if it was not 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 flag will only UTF-8 encode 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, so: + +```C# +new X500DistinguishedName("Phone=!!"); +``` + +This would throw an exception on Windows but was encoded as a UTF8String on non-Windows. Similarly, using would force UTF8String encoding even when not permitted: + +```C# +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: + +```C# +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/toc.yml b/docs/core/compatibility/toc.yml index 5cd6a05624b0b..ce79a022eff30 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -20,6 +20,10 @@ items: 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: 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 @@ -1570,6 +1574,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 From 85a79b06b9adf0a3fffed5441d78136d38ba164f Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Thu, 30 Jan 2025 23:56:36 +0000 Subject: [PATCH 16/24] lint --- .../cryptography/10.0/x500distinguishedname-validation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md index 3c8505bdcaca9..d5ac0e71b3753 100644 --- a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md +++ b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md @@ -56,4 +56,3 @@ X500DistinguishedName dn = builder.Build(); - - - From 5354c1d57f8f364ac0944d425f194412cdf3fd57 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 00:02:25 +0000 Subject: [PATCH 17/24] 43156 --- docs/core/compatibility/10.0.md | 1 + .../10.0/maccatalyst-version-normalization.md | 39 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 44 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 33c23ea7ef27f..d851c64ad6626 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -24,6 +24,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [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 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..83819b5f82add --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md @@ -0,0 +1,39 @@ +--- +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 +--- + +# 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 + +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/toc.yml b/docs/core/compatibility/toc.yml index ce79a022eff30..821521b491813 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -20,6 +20,8 @@ items: 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 @@ -1340,6 +1342,8 @@ items: 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 From bc0602462077c89a392e0eb23b8737312fcae27e Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 00:17:42 +0000 Subject: [PATCH 18/24] issue 42558 --- docs/core/compatibility/10.0.md | 7 ++- docs/core/compatibility/toc.yml | 4 ++ .../10.0/insertadjacentelement-orientation.md | 57 +++++++++++++++++++ 3 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index d851c64ad6626..0dfa5ff4a4ea8 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -40,6 +40,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af ## Windows Forms -| Title | Type of change | Introduced version | -|----------------------------------------------------------------------------------------------------|---------------------|--------------------| -| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 | +| 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/toc.yml b/docs/core/compatibility/toc.yml index 821521b491813..d512dd2bc91aa 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -32,6 +32,8 @@ items: 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 @@ -2088,6 +2090,8 @@ items: 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 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..840b3bd48c9f9 --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md @@ -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`. +ms.date: 01/30/2025 +--- + +# 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 + +Calls should be edited to have the new parameter name (`orientation`) or the parameter name should be removed: + +```csharp +element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +```csharp +element.InsertAdjacentElement(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 + +Calls should be edited to have the new parameter name or the parameter name should be removed: + +```csharp +element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +```csharp +element.InsertAdjacentElement(HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## Affected APIs + +- From 06ad8568d275a7b1f692a70ddfa680097c0a3304 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 00:38:49 +0000 Subject: [PATCH 19/24] issue 42027 --- .../core-libraries/10.0/obsolete-apis.md | 1 + .../syslib-diagnostics/syslib0058.md | 57 +++++++++++++++++++ docs/navigate/tools-diagnostics/toc.yml | 2 + 3 files changed, 60 insertions(+) create mode 100644 docs/fundamentals/syslib-diagnostics/syslib0058.md 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 adc57ce5a72ed..79e317c578953 100644 --- a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md +++ b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md @@ -16,6 +16,7 @@ The following table lists the custom diagnostic IDs and their corresponding warn | Diagnostic ID | Description | Severity | |---------------|-------------|----------| +| SYSLIB0058 | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | | [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 | diff --git a/docs/fundamentals/syslib-diagnostics/syslib0058.md b/docs/fundamentals/syslib-diagnostics/syslib0058.md new file mode 100644 index 0000000000000..3105534501b98 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0058.md @@ -0,0 +1,57 @@ +--- +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 +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/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index c214314a96a98..de24d0465b7f0 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1822,6 +1822,8 @@ 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 From f1d5720c369981b836bb1255b87b262d11645fdd Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 00:46:09 +0000 Subject: [PATCH 20/24] build fix --- docs/fundamentals/syslib-diagnostics/syslib0058.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0058.md b/docs/fundamentals/syslib-diagnostics/syslib0058.md index 3105534501b98..57a6661d78cbc 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0058.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0058.md @@ -12,11 +12,11 @@ The following properties of - - -- +- - - -, , and enums are obsolete since they were only used by the class. +, , and enums are obsolete since they were only used by the class. ## Reason for obsoletion From 17a4b32e6c752a6c6086ce5b0a7a87f0f9e43d63 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 12:58:27 -0600 Subject: [PATCH 21/24] Apply suggestions from code review. Thank you @gewarren! Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../10.0/x500distinguishedname-validation.md | 18 +++++++++--------- .../globalization/10.0/version-override.md | 6 +++--- .../10.0/insertadjacentelement-orientation.md | 2 +- .../syslib-diagnostics/syslib0060.md | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md index d5ac0e71b3753..c9d156b1a27b7 100644 --- a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md +++ b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md @@ -1,19 +1,19 @@ --- title: "Breaking change: X500DistinguishedName validation is stricter" -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. ms.date: 01/30/2025 --- # X500DistinguishedName validation is stricter -Starting in .NET 10, the 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 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 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 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 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 flag only UTF-8 encodes components when permissible. ## Version introduced @@ -25,15 +25,15 @@ 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, so: +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: -```C# +```csharp new X500DistinguishedName("Phone=!!"); ``` -This would throw an exception on Windows but was encoded as a UTF8String on non-Windows. Similarly, using would force UTF8String encoding even when not permitted: +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: -```C# +```csharp new X500DistinguishedName("Phone=000-555-1234", X500DistinguishedNameFlags.ForceUTF8Encoding); ``` @@ -43,7 +43,7 @@ This change ensures encoding aligns with specifications and Windows behavior. Generally, no action is needed unless compatibility with incorrect encoding is required. Use to create instances with desired encoding: -```C# +```csharp using System.Formats.Asn1; using System.Security.Cryptography.X509Certificates; diff --git a/docs/core/compatibility/globalization/10.0/version-override.md b/docs/core/compatibility/globalization/10.0/version-override.md index 943cc4dee38e2..3e8eb065e3677 100644 --- a/docs/core/compatibility/globalization/10.0/version-override.md +++ b/docs/core/compatibility/globalization/10.0/version-override.md @@ -1,6 +1,6 @@ --- 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. +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 --- # Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE @@ -9,7 +9,7 @@ ms.date: 01/30/2025 ## Previous behavior -The `CLR_ICU_VERSION_OVERRIDE` environment variable is used to specify the preferred ICU version to be loaded in the application. +The `CLR_ICU_VERSION_OVERRIDE` environment variable was used to specify the preferred ICU version to be loaded in the application. ## New behavior @@ -29,4 +29,4 @@ This change ensures the environment variable is consistent with the naming conve ## Recommended action -Users running .NET 10 apps who previously used the `CLR_ICU_VERSION_OVERRIDE` environment variable will now need to use `DOTNET_ICU_VERSION_OVERRIDE` instead. +If you have a .NET 10 app that previously used the `CLR_ICU_VERSION_OVERRIDE` environment variable, use `DOTNET_ICU_VERSION_OVERRIDE` instead. diff --git a/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md index 840b3bd48c9f9..74562e63e8a60 100644 --- a/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md +++ b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md @@ -1,6 +1,6 @@ --- 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`. +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 --- diff --git a/docs/fundamentals/syslib-diagnostics/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md index 5afd586452809..208c4364bb949 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0060.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -7,11 +7,11 @@ f1_keywords: --- # SYSLIB0060: Rfc2898DeriveBytes constructors are obsolete -Starting in .NET 10, all of the constructors on are obsolete. Referencing this event in code generates warning `SYSLIB0060` at compile time. +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 . +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 From 01f20daa95e5fb551ee14d7092b4f5ae8c103ed7 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 23:17:06 +0000 Subject: [PATCH 22/24] Apply all new suggestions and AI disclosure --- docs/core/compatibility/10.0.md | 1 + .../core-libraries/10.0/activity-sampling.md | 7 +++-- .../10.0/csharp-overload-resolution.md | 13 +++++---- .../core-libraries/10.0/generic-math.md | 7 +++-- .../10.0/ldap-directorycontrol-parsing.md | 29 ++++++++++--------- .../10.0/maccatalyst-version-normalization.md | 3 +- .../core-libraries/10.0/obsolete-apis.md | 20 ++++++++++++- .../10.0/x500distinguishedname-validation.md | 5 ++-- .../globalization/10.0/version-override.md | 9 ++++-- .../10.0/insertadjacentelement-orientation.md | 9 ++---- .../10.0/treeview-text-location.md | 20 +++++++++---- .../obsoletions-overview.md | 2 +- .../syslib-diagnostics/syslib0058.md | 1 + .../syslib-diagnostics/syslib0060.md | 1 + 14 files changed, 83 insertions(+), 44 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 0dfa5ff4a4ea8..3cfb3b62328eb 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -3,6 +3,7 @@ title: Breaking changes in .NET 10 titleSuffix: "" description: Navigate to the breaking changes in .NET 10. ms.date: 01/30/2025 +ai-usage: ai-assisted no-loc: [Blazor, Razor, Kestrel] --- # Breaking changes in .NET 10 diff --git a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md index 8d683ce660013..9c6da6ccc5e8b 100644 --- a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -2,10 +2,11 @@ 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 `Activity` when there is a registered listener which decides the instance should be created. This is generally known as sampling. +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. @@ -22,7 +23,7 @@ It is also possible to create an `Activity` with a parent. The parent could be i ## Previous behavior -When creating an `Activity` as `PropagationData` with a parent marked as `Recorded`: +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| |---|---|---|---| @@ -30,7 +31,7 @@ When creating an `Activity` as `PropagationData` with a parent marked as `Record ## New behavior -When creating an `Activity` as `PropagationData` with a parent marked as `Recorded`: +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| |---|---|---|---| 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 index 4a840e912efa8..5033409d99d93 100644 --- a/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md +++ b/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md @@ -2,18 +2,19 @@ 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 introduces new [built-in span conversions and type inference rules](https://github.com/dotnet/csharplang/issues/7905) making overloads with span parameters applicable in more scenarios. +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 is not applicable to a value of type `T[]`. Therefore, only non-span extension methods like the ones from the `System.Linq.Enumerable` class are usually bound inside Expression lambdas. +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 runtime exceptions when compiled with interpretation. +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 @@ -25,13 +26,13 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -The C# language feature allows simplified API design and usage (e.g., one ReadOnlySpan extension method can apply to both spans and arrays). +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, you should make sure the non-span overloads are bound, e.g., by casting arguments to the exact types the method signature takes or calling the extension methods as explicit static invocations: +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: -```cs +```csharp using System; using System.Collections.Generic; using System.Linq; diff --git a/docs/core/compatibility/core-libraries/10.0/generic-math.md b/docs/core/compatibility/core-libraries/10.0/generic-math.md index 203e601eff5e2..7d418a0d0678c 100644 --- a/docs/core/compatibility/core-libraries/10.0/generic-math.md +++ b/docs/core/compatibility/core-libraries/10.0/generic-math.md @@ -2,14 +2,15 @@ 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 -This document explains the breaking change in .NET 10 where shift operations in generic math now have consistent behavior across all built-in integer types. +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 would appropriately mask the shift amount by `sizeof(T) - 1` and in other cases, it would do no masking. This meant that "overshifting" (such as shifting a `byte` by 8) could result in different answers than expected. +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 @@ -35,4 +36,4 @@ Update any code that relies on the previous inconsistent behavior to ensure it w - `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. +- `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 index fe5da0595e101..ba4bf5d6e8030 100644 --- a/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md +++ b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md @@ -2,36 +2,37 @@ 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; would use the OS-specific BER parsing functionality. This parsing functionality is now implemented in managed code. +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. +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 which extended beyond the end of their parent sequence would return data outside the parent sequence. -- On earlier versions of Windows, a zero-length OCTET STRING would return `null` rather than an empty string. -- When reading the contents of a as a UTF8-encoded string, an invalid UTF8 sequence would not throw an exception. +- 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 would always encode ASN.1 tags with a four-byte length while Linux would only use as many bytes for the tag length as it needed. Both representations were valid, but this behavioural difference between platforms is now gone; the Linux behaviour now also appears on Windows. +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. +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 STRINGs and SEQUENCEs is now checked. -- Zero-length OCTET STRINGs will now always return an empty string. -- If the server sends an invalid UTF8 byte sequence, the parsing logic will now throw an exception rather than silently substitute the invalid characters with a known value. +- 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 VlvRequestControl constructor. Passing a string which cannot be encoded as a UTF8 value will now throw an EncoderFallbackException. +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 @@ -43,17 +44,17 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -RFC/spec. 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 below (from [RFC2891, section 1.2](https://datatracker.ietf.org/doc/html/rfc2891#section-1.2)): +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 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 which can't be encoded to valid UTF8 bytes. +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. Users should be aware of the need to handle an when calling the constructor. +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 index 83819b5f82add..bd0bc72aed39a 100644 --- a/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md +++ b/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md @@ -2,6 +2,7 @@ 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 @@ -26,7 +27,7 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -Prevent incorrect version checks and align MacCatalyst versioning with iOS, ensuring consistent version components. +This changed was made to prevent incorrect version checks and align MacCatalyst versioning with iOS, ensuring consistent version components. ## Recommended action 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 79e317c578953..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,7 +17,7 @@ The following table lists the custom diagnostic IDs and their corresponding warn | Diagnostic ID | Description | Severity | |---------------|-------------|----------| -| SYSLIB0058 | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | +| [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 | @@ -36,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 index c9d156b1a27b7..cdf11a1f78108 100644 --- a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md +++ b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md @@ -2,9 +2,10 @@ 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 invalid input (that would previously have been accepted) or encode it differently on non-Windows systems. This aligns with encoding specifications and Windows behavior. 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 @@ -12,7 +13,7 @@ Starting in .NET 10, 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. Starting in .NET 10, components that violate encoding rules throw a `CryptographicException` on non-Windows systems, matching Windows behavior. The flag only UTF-8 encodes components when permissible. ## Version introduced diff --git a/docs/core/compatibility/globalization/10.0/version-override.md b/docs/core/compatibility/globalization/10.0/version-override.md index 3e8eb065e3677..92fc35d6af962 100644 --- a/docs/core/compatibility/globalization/10.0/version-override.md +++ b/docs/core/compatibility/globalization/10.0/version-override.md @@ -2,9 +2,10 @@ 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. .NET has previously supported a configuration switch environment variable called `CLR_ICU_VERSION_OVERRIDE`, which allows 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 @@ -25,8 +26,12 @@ 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. +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 \ No newline at end of file diff --git a/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md index 74562e63e8a60..afb741bde02eb 100644 --- a/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md +++ b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md @@ -2,6 +2,7 @@ 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 @@ -18,16 +19,12 @@ element.InsertAdjacentElement(orient: HtmlElementInsertionOrientation.AfterEnd, ## New behavior -Calls should be edited to have the new parameter name (`orientation`) or the parameter name should be removed: +The new parameter name is `orientation`. ```csharp element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); ``` -```csharp -element.InsertAdjacentElement(HtmlElementInsertionOrientation.AfterEnd, newElement); -``` - ## Version introduced .NET 10 Preview 1 @@ -42,7 +39,7 @@ The parameter name was changed to provide a more descriptive name. ## Recommended action -Calls should be edited to have the new parameter name or the parameter name should be removed: +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); 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 index 7eb7fe2148c74..01307f712a5b8 100644 --- a/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md +++ b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md @@ -1,13 +1,13 @@ --- title: "Breaking change: TreeView checkbox image truncation" -description: Learn about the .NET 10 Preview 1 breaking change in Windows Forms where the TreeView checkbox image is truncated under certain conditions. +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 TreeNode in the TreeView 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, an AppContext switch setting is added to solve the problem of checkbox truncation in these specific situations. +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 conditions under which the checkbox image is truncated are: +The checkbox image is truncated when all of the following conditions are met: - `CheckBoxes` is set to `true` - `DrawMode` is set to `OwnerDrawText` @@ -15,11 +15,11 @@ The conditions under which the checkbox image is truncated are: ## Previous behavior -When the TreeView control has `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event, the TreeNode checkbox images are shown truncated on the right border. +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 will be displayed completely when the TreeView has `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event. +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 @@ -37,6 +37,16 @@ This change ensures that the checkbox of the node in the TreeView control can be 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 b356175c21142..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+ diff --git a/docs/fundamentals/syslib-diagnostics/syslib0058.md b/docs/fundamentals/syslib-diagnostics/syslib0058.md index 57a6661d78cbc..efb7a660f80c3 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0058.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0058.md @@ -2,6 +2,7 @@ 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 --- diff --git a/docs/fundamentals/syslib-diagnostics/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md index 208c4364bb949..eba580531f6ff 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0060.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -2,6 +2,7 @@ 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 --- From 9380df11817907a0942d93d4e1dc4f1c4fc8d24a Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 23:19:48 +0000 Subject: [PATCH 23/24] Missed a couple suggestions --- .../compatibility/core-libraries/10.0/activity-sampling.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md index 9c6da6ccc5e8b..66726a03f375a 100644 --- a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -47,13 +47,12 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -The existing behavior does not follow the OpenTelemetry specification. +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. -Users who have implemented `ActivityListener.Sample` directly AND use `ActivitySamplingResult.PropagationData` should verify they are not reliant on the flawed behavior. `Activity.ActivityTraceFlags` may be set to `Recorded` after the `CreateActivity` or `StartActivity` call to restore the previous behavior. - -Users using OpenTelemetry .NET should verify their sampler configuration. The default OpenTelemetry .NET configuration uses a parent-based algorithm which is not impacted. Only users who have customized the sampler should verify the behavior. +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 From 93156fa3781b8072fc9725c24b23de00923d63e0 Mon Sep 17 00:00:00 2001 From: Cam Soper Date: Fri, 31 Jan 2025 23:25:10 +0000 Subject: [PATCH 24/24] Fixed linting issues introduced by VSCode --- .../compatibility/core-libraries/10.0/activity-sampling.md | 1 + .../cryptography/10.0/x500distinguishedname-validation.md | 4 ++-- .../compatibility/globalization/10.0/version-override.md | 5 +++-- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md index 66726a03f375a..04c63c8246214 100644 --- a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -50,6 +50,7 @@ This change is a [behavioral change](../../categories.md#behavioral-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. diff --git a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md index cdf11a1f78108..150dd22b4fcdb 100644 --- a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md +++ b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md @@ -5,7 +5,7 @@ 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 invalid input (that would previously have been accepted) or encode it differently on non-Windows systems. This aligns with encoding specifications and Windows behavior. + 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 @@ -13,8 +13,8 @@ Starting in .NET 10, 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. -Starting in .NET 10, components that violate encoding rules throw a `CryptographicException` on non-Windows systems, matching Windows behavior. The flag only UTF-8 encodes components when permissible. ## Version introduced diff --git a/docs/core/compatibility/globalization/10.0/version-override.md b/docs/core/compatibility/globalization/10.0/version-override.md index 92fc35d6af962..fc1cc13e80a3b 100644 --- a/docs/core/compatibility/globalization/10.0/version-override.md +++ b/docs/core/compatibility/globalization/10.0/version-override.md @@ -4,9 +4,10 @@ description: Learn about the .NET 10 breaking change in globalization where the 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. -.NET has previously supported a configuration switch environment variable called `CLR_ICU_VERSION_OVERRIDE`, which allows 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 @@ -34,4 +35,4 @@ If you have a .NET 10 app that previously used the `CLR_ICU_VERSION_OVERRIDE` en ## Affected APIs -N/A \ No newline at end of file +N/A