[Breaking change] MSBuild Custom Culture Resource Handling

[YuliiaKovalova]

Description

Custom culture resource handling in MSBuild will change from being enabled by default to requiring explicit opt-in. This affects the behavior introduced in dotnet/msbuild#11000 where MSBuild automatically treats directories with names that look like culture codes as culture-specific resource directories.

Version

MSBuild 17.14

Previous behavior

MSBuild automatically identified directories with names resembling culture codes as culture-specific resource directories. This could cause unexpected behavior in build processes when directories with coincidental matches (e.g., hash-based directories or directories with short technical names) were unintentionally treated as culture resources, creating unwanted resource assemblies.

New behavior

• Custom culture resource handling is disabled by default
• To enable the feature, users must explicitly set project property EnableCustomCulture to true
• A new MSBuild property CustomCultureExcludeDirectories allows specifying a semicolon-delimited list of directory names to exclude from custom culture processing.

Type of breaking change

• Behavioral change: Existing projects that relied on the automatic custom culture resource handling will need to opt-in to maintain current behavior.

Reason for change

The automatic detection of culture-specific resource directories could lead to unexpected build outcomes when directory names coincidentally matched culture codes. Making this feature opt-in provides more predictable build behavior and gives users explicit control over resource handling.

Recommended action

If your build process requires custom culture resource handling:

1. Set the project property EnableCustomCulture to true
2. Optionally use the CustomCultureExcludeDirectories property to exclude specific directories that should not be treated as culture resources

Feature area

Visual Studio

Affected APIs

No direct API changes, but affects MSBuild's behavior regarding resource directory processing.

Associated work item: dotnet/msbuild#11446

---

Associated WorkItem - 410918

[rainersigwald]

@baronfel for awareness

[CamSoper]

@YuliiaKovalova It looks like all the previous MSBuild breaking changes have been tied to a .NET release. Which would be appropriate here? .NET 10 Preview 1?