[Breaking change] MSBuild Custom Culture Resource Handling (#45527)

Fixes #45501

Author: Cam Soper

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: 03/25/2025
+ms.date: 03/26/2025
 ai-usage: ai-assisted
 no-loc: [Blazor, Razor, Kestrel]
 ---
@@ -47,12 +47,13 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md)     | Behavioral/source incompatible change | Preview 3          |
 | [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change                     | Preview 1          |
 
-## SDK
+## SDK and MSBuild
 
 | Title                                                                                                                | Type of change      | Introduced version |
 |----------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
 | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change   | Preview 2          |
 | [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md)                        | Behavioral change   | Preview 1          |
+| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md)                                       | Behavioral change   | Preview 1          |
 | [NU1510 is raised for direct references pruned by NuGet](sdk/10.0/nu1510-pruned-references.md)                       | Source incompatible | Preview 1          |
 
 ## Windows Forms

docs/core/compatibility/9.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 9
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 9.
-ms.date: 12/19/2024
+ms.date: 03/26/2025
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # Breaking changes in .NET 9
@@ -106,6 +106,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 | [`dotnet watch` incompatible with Hot Reload for old frameworks](sdk/9.0/dotnet-watch.md) | Behavioral change   | RC 1               |
 | [`dotnet workload` commands output change](sdk/9.0/dotnet-workload-output.md)             | Behavioral change   | Preview 1          |
 | [`installer` repo version no longer documented](sdk/9.0/productcommits-versions.md)       | Behavioral change   | Preview 5          |
+| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md)            | Behavioral change   | 9.0.200/9.0.300    |
 | [New default RID used when targeting .NET Framework](sdk/9.0/default-rid.md)              | Source incompatible | GA                 |
 | [Terminal logger is default](sdk/9.0/terminal-logger.md)                                  | Behavioral change   | Preview 1          |
 | [Version requirements for .NET 9 SDK](sdk/9.0/version-requirements.md)                    | Source incompatible | GA                 |

docs/core/compatibility/sdk/10.0/msbuild-custom-culture.md

@@ -0,0 +1,47 @@
+---
+title: "Breaking change - MSBuild custom culture resource handling"
+description: "Learn about the breaking change in MSBuild 17.14 where custom culture resource handling now requires explicit opt-in."
+ms.date: 3/26/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/45501
+---
+
+# MSBuild custom culture resource handling
+
+Starting in MSBuild 17.14, custom culture resource handling is no longer enabled by default. Users must explicitly opt in to enable this feature. This change prevents unintended behavior caused by automatic detection of directories resembling culture codes.
+
+## Version introduced
+
+MSBuild 17.14
+
+> [!NOTE]
+> As this change affects the behavior of MSBuild, it affects two supported versions of .NET: .NET 10 Preview 1 and .NET 9.0.2. The transparent support for custom culture change was introduced in .NET SDK 9.0.200 and the change making it opt-in is in .NET SDK 9.0.300.
+
+## Previous behavior
+
+MSBuild previously treated directories with names resembling culture codes (for example, `en-US`, `fr-FR`) as culture-specific resource directories by default. This behavior sometimes included unrelated directories, such as those with hash-based or technical names, leading to unintended resource assemblies in the build process.
+
+## New behavior
+
+- Custom culture resource handling is disabled by default.
+- To enable this feature, set the project property `EnableCustomCulture` to `true`.
+- Use the `CustomCultureExcludeDirectories` property to specify a semicolon-delimited list of directory names to exclude from custom culture processing.
+
+## Type of breaking change
+
+This is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The automatic detection of culture-specific resource directories caused unpredictable build behavior when directory names coincidentally matched culture codes. Requiring explicit opt-in ensures more predictable builds and gives users greater control over resource handling.
+
+## Recommended action
+
+If your build process relies on custom culture resource handling:
+
+1. Set the project property `EnableCustomCulture` to `true`.
+2. Optionally use the `CustomCultureExcludeDirectories` property to exclude specific directories from being treated as culture resources.
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -46,6 +46,8 @@ items:
                 href: sdk/10.0/default-workload-config.md
               - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
                 href: sdk/10.0/custom-build-event-warning.md
+              - name: MSBuild custom culture resource handling
+                href: sdk/10.0/msbuild-custom-culture.md
               - name: NU1510 is raised for direct references pruned by NuGet
                 href: sdk/10.0/nu1510-pruned-references.md
           - name: Windows Forms
@@ -174,6 +176,8 @@ items:
                 href: sdk/9.0/dotnet-workload-output.md
               - name: "`installer` repo version no longer documented"
                 href: sdk/9.0/productcommits-versions.md
+              - name: MSBuild custom culture resource handling
+                href: sdk/10.0/msbuild-custom-culture.md
               - name: New default RID used when targeting .NET Framework
                 href: sdk/9.0/default-rid.md
               - name: Terminal logger is default
@@ -1910,6 +1914,8 @@ items:
                 href: sdk/10.0/default-workload-config.md
               - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
                 href: sdk/10.0/custom-build-event-warning.md
+              - name: MSBuild custom culture resource handling
+                href: sdk/10.0/msbuild-custom-culture.md
               - name: NU1510 is raised for direct references pruned by NuGet
                 href: sdk/10.0/nu1510-pruned-references.md
           - name: .NET 9
@@ -1924,6 +1930,8 @@ items:
                 href: sdk/9.0/dotnet-workload-output.md
               - name: "`installer` repo version no longer documented"
                 href: sdk/9.0/productcommits-versions.md
+              - name: MSBuild custom culture resource handling
+                href: sdk/10.0/msbuild-custom-culture.md
               - name: New default RID used when targeting .NET Framework
                 href: sdk/9.0/default-rid.md
               - name: Terminal logger is default