EventsThreadShutdown obsoletion (#44287)

gewarren · web-flow · commit 042ad29ce177 · 2025-01-16T16:25:58.000-08:00
diff --git a/docs/core/compatibility/10.0.md 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
@@ -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) | <xref:Microsoft.Win32.SystemEvents.EventsThreadShutdown?displayProperty=nameWithType> callbacks aren't run before the process exits. Use <xref:System.AppDomain.ProcessExit?displayProperty=nameWithType> 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
+
+- <xref:Microsoft.Win32.SystemEvents.EventsThreadShutdown?displayProperty=fullName>
+
+## 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
@@ -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
@@ -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
@@ -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
@@ -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 <xref:System.Net.Security.SslStream> are obsolete. Use <xref:System.Net.Security.SslStream.NegotiatedCipherSuite> instead. |
+| [SYSLIB0059](syslib0059.md) | Warning | <xref:Microsoft.Win32.SystemEvents.EventsThreadShutdown?displayProperty=nameWithType> callbacks aren't run before the process exits. Use <xref:System.AppDomain.ProcessExit?displayProperty=nameWithType> instead. |
 
 ## Suppress warnings
 
diff --git a/docs/fundamentals/syslib-diagnostics/syslib0059.md 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 <xref:Microsoft.Win32.SystemEvents.EventsThreadShutdown?displayProperty=nameWithType> 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 <xref:Microsoft.Win32.SystemEvents> could block the finalizer thread during app shutdown. To avoid blocking the finalizer thread, <xref:Microsoft.Win32.SystemEvents> no longer has shutdown handling, which means that the <xref:Microsoft.Win32.SystemEvents.EventsThreadShutdown?displayProperty=nameWithType> event is no longer called. To surface this behavior change, the event was marked obsolete.
+
+## Workaround
+
+Use <xref:System.AppDomain.ProcessExit?displayProperty=nameWithType> 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 `<NoWarn>` property to your project file.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+   ...
+   <NoWarn>$(NoWarn);SYSLIB0059</NoWarn>
+  </PropertyGroup>
+</Project>
+```
+
+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
@@ -1818,14 +1818,15 @@ 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
             displayName: syslib, experimental
             href: ../../fundamentals/syslib-diagnostics/experimental-overview.md
           - name: SYSLIB5003
             href: ../../fundamentals/syslib-diagnostics/syslib5003.md
-            displayProperty: syslib5003          
       - name: Source-generated code
         items:
           - name: Overview
