MSBUILDCUSTOMBUILDEVENTWARNING breaking change (#45006)

* initial commit

* lint

* tweaks

Author: Cam Soper

docs/core/compatibility/10.0.md

@@ -41,6 +41,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md)      | Behavioral change | Preview 1          |
 | [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md)   | Behavioral change | Preview 1          |
 
+## SDK
+
+| Title                                                                                         | Type of change    | Introduced version |
+|-----------------------------------------------------------------------------------------------|-------------------|--------------------|
+| [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1          |
+
 ## Windows Forms
 
 | Title                                                                                                             | Type of change      | Introduced version |

docs/core/compatibility/sdk/10.0/custom-build-event-warning.md

@@ -0,0 +1,44 @@
+---
+title: "Breaking change - MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed"
+description: "Learn about the breaking change where the MSBUILDCUSTOMBUILDEVENTWARNING environment variable is no longer supported."
+ms.date: 2/25/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/44998
+---
+
+# MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
+
+The `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable, which previously allowed custom build events derived from <xref:Microsoft.Build.Framework.BuildEventArgs>, is no longer supported.
+
+## Version introduced
+
+.NET 10 Preview 1
+
+## Previous behavior
+
+Users could set the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable to enable processing of custom build events.
+
+## New behavior
+
+The value of the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable is not respected anymore.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The escape hatch mechanism provided by the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable was a temporary workaround. For more information, see the [original breaking change](../8.0/custombuildeventargs.md).
+
+## Recommended action
+
+Use one of the following newly introduced, built-in events for extensibility instead of your custom derived build event:
+
+- <xref:Microsoft.Build.Framework.ExtendedCustomBuildEventArgs>
+- <xref:Microsoft.Build.Framework.ExtendedBuildErrorEventArgs>
+- <xref:Microsoft.Build.Framework.ExtendedBuildMessageEventArgs>
+- <xref:Microsoft.Build.Framework.ExtendedBuildWarningEventArgs>
+
+## Affected APIs
+
+- <xref:Microsoft.Build.Framework.CustomBuildEventArgs?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -34,6 +34,10 @@ items:
             items:
               - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE
                 href: globalization/10.0/version-override.md
+          - name: SDK and MSBuild
+            items:
+              - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
+                href: sdk/10.0/custom-build-event-warning.md
           - name: Windows Forms
             items:
               - name: Renamed parameter in HtmlElement.InsertAdjacentElement
@@ -1872,6 +1876,10 @@ items:
                 href: reflection/8.0/function-pointer-reflection.md
       - name: SDK and MSBuild
         items:
+          - name: .NET 10
+            items:
+              - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
+                href: sdk/10.0/custom-build-event-warning.md
           - name: .NET 9
             items:
               - name: "`dotnet restore` audits transitive packages"