MSBuild项目构建中路径括号导致的ItemGroup异常问题分析

问题背景

在.NET 10和MSBuild构建系统中，开发人员发现了一个与项目路径相关的特殊问题：当项目所在目录包含圆括号（特别是"("和")"）时，会导致ItemGroup中的某些元数据（Metadata）无法正确传递。这个问题最初在Android项目迁移到.NET 10时被发现，表现为FrameworkReference的RuntimePackLabels元数据丢失。

问题现象

具体表现为：

1. 在普通路径下，FrameworkReference能正确获取RuntimePackLabels="Mono"元数据
2. 在包含圆括号的路径下（如CheckSignApk(True,True)），RuntimePackLabels元数据会丢失
3. 该问题不仅影响Update操作，也影响普通的Include操作

技术分析

经过深入调查，发现问题的根源在于MSBuild的LazyItemEvaluator内部实现：

1. 路径规范化问题：MSBuild在处理项目路径时，会将路径存入字典，但存入的是未规范化的路径（包含URL编码的括号如"%28"），而后续查询时使用的是规范化后的路径（包含原始括号"("）

2. 字典查询失败：由于存入和查询使用的路径格式不一致，导致无法从字典中正确检索到对应的ItemGroup操作

3. 静默失败：整个过程没有抛出任何异常，只是默默地无法找到对应的ItemGroup操作，使得构建过程继续但结果不正确

影响范围

该问题：

• 不是.NET 10特有的回归问题，而是一个长期存在的bug
• 在.NET 9.0.100 SDK中可以正常工作
• 从.NET 9.0.200 SDK开始重现
• 在.NET 10 Preview 2中已修复

解决方案

微软团队已经修复了这个问题，主要改动是确保路径在存入字典和查询时使用一致的规范化格式。修复将包含在：

1. .NET 10 Preview 2及后续版本
2. .NET 9.0.300及后续版本

临时解决方案

对于受影响的用户，可以采取以下临时措施：

1. 避免在项目路径中使用圆括号
2. 对于必须使用特殊字符的场景，可以考虑使用URL编码后的字符
3. 降级到.NET 9.0.100 SDK（如果不影响其他功能）

技术启示

这个问题给我们几个重要的技术启示：

1. 路径处理一致性：在构建系统中处理文件路径时，必须确保所有阶段的路径格式一致
2. 静默失败的危险性：系统应该对这类问题给出明确警告，而不是静默继续
3. 特殊字符测试：在项目路径中使用各种特殊字符应该成为构建系统测试的一部分

这个问题虽然看似简单，但揭示了构建系统中一个深层次的设计问题，也提醒开发者在项目组织时要注意路径命名的规范性。