diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md new file mode 100644 index 0000000000000..91ded5b8daec0 --- /dev/null +++ b/docs/core/compatibility/10.0.md @@ -0,0 +1,22 @@ +--- +title: Breaking changes in .NET 10 +titleSuffix: "" +description: Navigate to the breaking changes in .NET 10. +ms.date: 12/19/2024 +no-loc: [Blazor, Razor, Kestrel] +--- +# Breaking changes in .NET 10 + +If you're migrating an app to .NET 10, the breaking changes listed here might affect you. Changes are grouped by technology area, such as ASP.NET Core or Windows Forms. + +[!INCLUDE [binary-source-behavioral](includes/binary-source-behavioral.md)] + +> [!NOTE] +> +> This article is a work in progress. It's not a complete list of breaking changes in .NET 10. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet/docs%20or%20repo:aspnet/Announcements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%2010%22%20or%20label:10.0.0)%20sort:created-desc). + +## 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 | diff --git a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md new file mode 100644 index 0000000000000..2a5e9c98f4344 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md @@ -0,0 +1,45 @@ +--- +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 +--- +# API obsoletions with non-default diagnostic IDs (.NET 10) + +Some APIs have been marked as obsolete, starting in .NET 10. This breaking change is specific to APIs that have been marked as obsolete *with a custom diagnostic ID*. Suppressing the default obsoletion diagnostic ID, which is [CS0618](../../../../csharp/language-reference/compiler-messages/cs0618.md) for the C# compiler, does not suppress the warnings that the compiler generates when these APIs are used. + +## Change description + +In previous .NET versions, these APIs can be used without any build warning. In .NET 10 and later versions, use of these APIs produces a compile-time warning or error with a custom diagnostic ID. The use of custom diagnostic IDs allows you to suppress the obsoletion warnings individually instead of blanket-suppressing all obsoletion warnings. + +The following table lists the custom diagnostic IDs and their corresponding warning messages for obsoleted APIs. + +| Diagnostic ID | Description | Severity | +|---------------|-------------|----------| +| [SYSLIB0059](../../../../fundamentals/syslib-diagnostics/syslib0059.md) | callbacks aren't run before the process exits. Use instead. | Warning | + +## Version introduced + +.NET 9 + +## Type of breaking change + +These obsoletions can affect [source compatibility](../../categories.md#source-compatibility). + +## Recommended action + +- Follow the specific guidance provided for the each diagnostic ID using the URL link provided on the warning. + +- Warnings or errors for these obsoletions can't be suppressed using the standard diagnostic ID for obsolete types or members; use the custom `SYSLIBxxxx` diagnostic ID value instead. + +## Affected APIs + +### SYSLIB0059 + +- + +## See also + +- [API obsoletions with non-default diagnostic IDs (.NET 9)](../9.0/obsolete-apis-with-custom-diagnostics.md) +- [API obsoletions with non-default diagnostic IDs (.NET 8)](../8.0/obsolete-apis-with-custom-diagnostics.md) +- [Obsolete features in .NET 5+](../../../../fundamentals/syslib-diagnostics/obsoletions-overview.md) diff --git a/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md b/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md index dc47cff662dc2..5ae18b896ee94 100644 --- a/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md +++ b/docs/core/compatibility/core-libraries/8.0/obsolete-apis-with-custom-diagnostics.md @@ -562,6 +562,8 @@ The `SYSLIB0051` API obsoletions are organized here by namespace. ## See also +- [API obsoletions with non-default diagnostic IDs (.NET 10)](../10.0/obsolete-apis.md) +- [API obsoletions with non-default diagnostic IDs (.NET 9)](../9.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 7)](../7.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 6)](../6.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 5)](../5.0/obsolete-apis-with-custom-diagnostics.md) diff --git a/docs/core/compatibility/core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md b/docs/core/compatibility/core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md index 2c3e57cf1946c..d8f2e54b3d1ef 100644 --- a/docs/core/compatibility/core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md +++ b/docs/core/compatibility/core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md @@ -106,6 +106,7 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c ## See also +- [API obsoletions with non-default diagnostic IDs (.NET 10)](../10.0/obsolete-apis.md) - [API obsoletions with non-default diagnostic IDs (.NET 8)](../8.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 7)](../7.0/obsolete-apis-with-custom-diagnostics.md) - [API obsoletions with non-default diagnostic IDs (.NET 6)](../6.0/obsolete-apis-with-custom-diagnostics.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 3d804e24526e5..6b4e9d80db1f6 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -4,6 +4,14 @@ items: - name: Breaking changes by version expanded: true items: + - name: .NET 10 + items: + - name: Overview + href: 10.0.md + - name: Core .NET libraries + items: + - name: API obsoletions with non-default diagnostic IDs + href: core-libraries/10.0/obsolete-apis.md - name: .NET 9 items: - name: Overview @@ -1302,6 +1310,10 @@ items: href: https://github.com/dotnet/dotnet-docker/discussions/3699 - name: Core .NET libraries items: + - name: .NET 10 + items: + - name: API obsoletions with non-default diagnostic IDs + href: core-libraries/10.0/obsolete-apis.md - name: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index 4b6eef5a77a24..b7ca9e2eef5c1 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -2,7 +2,7 @@ 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: 08/07/2024 +ms.date: 01/14/2025 --- # Obsolete features in .NET 5+ @@ -78,6 +78,8 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+ | [SYSLIB0055](syslib0055.md) | Warning | `AdvSimd.ShiftRightLogicalRoundedNarrowingSaturate*` methods with signed parameters are obsolete. Use the unsigned overloads instead. | | [SYSLIB0056](syslib0056.md) | Warning | `Assembly.LoadFrom` with a custom `AssemblyHashAlgorithm` is obsolete. Use overloads without an `AssemblyHashAlgorithm`. | | [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. | ## Suppress warnings diff --git a/docs/fundamentals/syslib-diagnostics/syslib0059.md b/docs/fundamentals/syslib-diagnostics/syslib0059.md new file mode 100644 index 0000000000000..a0aa4cb0af9a1 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0059.md @@ -0,0 +1,48 @@ +--- +title: SYSLIB0059 warning - SystemEvents.EventsThreadShutdown callbacks aren't run before the process exits +description: Learn about the obsoletion of SystemEvents.EventsThreadShutdown that generates compile-time warning SYSLIB0059. +ms.date: 08/01/2024 +f1_keywords: + - SYSLIB0059 +--- +# SYSLIB0059: SystemEvents.EventsThreadShutdown callbacks aren't run before the process exits + +The event is obsolete, starting in .NET 10. Referencing this event in code generates warning `SYSLIB0059` at compile time. + +## Reason for obsoletion + +The previous shutdown handling in could block the finalizer thread during app shutdown. To avoid blocking the finalizer thread, no longer has shutdown handling, which means that the event is no longer called. To surface this behavior change, the event was marked obsolete. + +## 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 SYSLIB0059 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0059 +``` + +To suppress all the `SYSLIB0059` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0059 + + +``` + +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 33f7ed0c9aa30..b3b10250b4b72 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1816,6 +1816,8 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0056.md - name: SYSLIB0057 href: ../../fundamentals/syslib-diagnostics/syslib0057.md + - name: SYSLIB0059 + href: ../../fundamentals/syslib-diagnostics/syslib0059.md - name: Experimental features items: - name: Overview @@ -1823,7 +1825,6 @@ items: href: ../../fundamentals/syslib-diagnostics/experimental-overview.md - name: SYSLIB5003 href: ../../fundamentals/syslib-diagnostics/syslib5003.md - displayProperty: syslib5003 - name: Source-generated code items: - name: Overview