Agile.NET的名称混淆会修改程序集中的命名空间、类型、方法、属性和字段等元数据名称，使反编译后的代码更难理解。对普通内部逻辑来说，这类改名通常不会影响执行；但序列化、反射、依赖注入以及按名称读取成员的框架并不完全依靠静态引用，一旦运行时仍在寻找原来的名称，就可能在混淆后出现数据字段缺失、反序列化失败等现象。因此，名称混淆真正需要控制的是“哪些名称可以安全修改，哪些名称必须保持稳定”。Agile.NET官方也明确指出，反射调用是符号重命名后容易发生兼容问题的典型场景。

　　一、Agile.NET怎么设置名称混淆规则

　　1、先确定程序集之间的保护范围

　　新建Agile.NET项目后，应先把应用本身以及参与调用的自研程序集放入同一个保护项目，而不是只添加主程序。

　　①点击【Add】加入EXE和相关DLL，检查需要一起发布的程序集是否完整。

　　②设置保护后的【输出目录】，不要直接覆盖尚未验证的原始文件。

　　③如果多个自研程序集之间存在类型、方法或属性引用，需要结合实际情况使用【Cross Assembly Obfuscation】。

　　④程序集带有强名称签名时，同时配置对应签名文件，保证保护后的程序集能够重新签名。

　　Agile.NET建议把组成软件的程序集都加入项目。启用跨程序集混淆后，一个程序集中的类型被重命名时，其他受保护程序集中指向它的外部引用也会同步更新。

　　2、开启名称混淆后，不要默认所有成员都适合改名

　　Agile.NET的Entity Renaming可以处理类、字段、方法、属性以及参数等元数据名称。保护强度虽然会上升，但项目中依赖名称工作的成员需要单独识别。

　　进入名称混淆相关配置后，可以按照下面的思路划分：

　　①普通内部实现类、私有方法以及不参与外部数据交换的成员，可以正常使用【名称混淆】。

　　②供外部程序调用的公共API，要先确认调用方是否同时参与混淆；无法同步修改外部调用方时，不宜直接重命名接口名称。

　　③被反射、插件发现机制或配置文件按字符串名称调用的类型和成员，应加入【Renaming Exclusions】。

　　④参与序列化的数据模型，不要仅根据访问修饰符判断是否安全，需要先确认所用序列化框架如何取得类型名、属性名或字段名。

　　这里的原则不是“public全部排除、private全部混淆”，而是判断运行时是否仍有人依赖这个名称。

　　3、把特殊成员做成明确的排除规则

　　项目较小时可以在保护配置中维护【Renaming Exclusions】；如果某个类本身就具有明确的兼容性要求，也可以通过.NET提供的ObfuscationAttribute在源代码层表达不应被重命名的对象。

　　Agile.NET官方支持Microsoft的声明式混淆属性，目的之一就是处理反射等情况下“调用处仍使用原名称，而目标成员已经改名”的问题。

　　实际项目中更适合排除的是：

　　序列化模型中必须保持名称稳定的类型或成员；

　　通过反射字符串查找的方法、属性和类型；

　　插件入口及外部框架要求固定名称的对象；

　　配置文件、脚本或其他程序集通过名称访问的公共接口。

　　这样可以保留核心业务代码的混淆强度，而不是因为少数兼容问题直接关闭整个程序集的名称保护。

　　二、Agile.NET名称混淆后序列化功能异常如何解决

　　名称混淆前数据读写正常，保护后出现JSON字段变化、对象属性为空或旧数据无法恢复时，首先要确认序列化过程是否依赖被修改的元数据名称。

　　1、先比较混淆前后的序列化结果

　　最直接的办法不是先改混淆参数，而是对同一个对象分别运行保护前和保护后的程序。

　　①保存一份混淆前产生的JSON、XML或其他序列化结果。

　　②使用保护后的程序集生成同样的数据，再比较字段名、类型信息和层级结构。

　　③如果原来的业务字段名称被替换成混淆后的名称，说明序列化器读取了已经被重命名的成员。

　　④如果输出正常而反序列化失败，再检查输入数据中是否保存了类型名、成员名等旧信息。

　　这样很快就能把问题限定到“名称变化”，而不是误以为代码加密、控制流混淆破坏了序列化逻辑。

　　2、名称就是数据协议的一部分时，应固定名称

　　JSON、XML、缓存文件、数据库持久化对象或者跨进程消息一旦已经对外使用，其中的字段名称实际上已经成为数据协议。

　　这种情况下有两种处理思路。

　　如果序列化框架支持显式指定外部字段名称，可以给关键成员设置固定的序列化名称，使外部数据格式不再跟CLR成员名称一起变化。

　　如果当前序列化方式直接依赖CLR成员名称，则把相关类型、属性或字段加入【名称排除】，保持这些符号不被重命名。

　　不要为了保住几个字段，把整个程序集的【名称混淆】关闭。把序列化边界控制在少量DTO、配置模型或持久化模型上，通常更容易兼顾保护效果和兼容性。

　　3、旧数据打不开，要检查类型信息是否也被保存

　　部分序列化方案除了保存成员值，还可能保存类型或程序集相关信息。这时即使字段名称没有明显变化，类型被重命名之后，历史数据仍可能无法重新构造原对象。

　　①确认异常只发生在旧数据，还是新旧数据都无法读取。

　　②如果只有保护前生成的数据失败，重点检查其中是否带有原始【类型名称】。

　　③对必须兼容历史数据的模型，保持相关类型名称稳定，或者为数据格式设计明确的版本迁移方式。

　　④修改排除规则后，用真实历史数据重新测试，不能只验证新生成的数据。

　　4、序列化正常后仍报错，再查反射链路

　　有些问题表面发生在序列化阶段，实际是序列化框架之后又通过反射寻找属性、构造函数或处理方法。

　　Agile.NET官方特别提醒，反射API按原名称调用成员时，目标方法一旦经过重命名，运行时调用就可能失败。

　　遇到这种情况，应沿异常堆栈找到真正找不到的类型或成员，再把必要对象加入【Renaming Exclusions】，而不是不断扩大整个模型的排除范围。

　　三、名称混淆规则调整后怎么确认没有过度排除

　　规则修改后，既要确认序列化恢复，也要看看保护范围是否被无意中削弱。

　　①使用保护后的正式程序集完成一次序列化和反序列化闭环，覆盖空值、集合、嵌套对象以及历史数据。

　　②再检查反射调用、插件加载和配置绑定等同样依赖名称的功能，防止解决一个模型后还有其他入口遗漏。

　　③反编译保护后的程序集，抽查普通业务类是否仍然进行了名称重命名，确认排除规则没有覆盖过大的命名空间。

　　④保存本次保护生成的【Obfuscation Map】。Agile.NET会在启用符号重命名时生成映射文件，用于把混淆后的类型和方法重新对应到开发阶段的原名称，后续排查生产环境异常时非常有用。

　　如果软件需要在后续版本中保持稳定的名称映射，还可以结合Agile.NET的增量混淆能力保存并继续使用已有映射关系。

　　总结

　　Agile.NET名称混淆与序列化发生冲突，通常不是混淆算法破坏了程序逻辑，而是某些名称本身已经成为运行时查找或数据交换的一部分。处理这类问题时，应把需要稳定名称的边界准确找出来，让序列化模型、反射入口和外部接口保持兼容，同时继续保护真正不需要暴露名称的内部实现。这样比大范围关闭名称混淆更容易兼顾运行稳定性和代码保护效果。如需进一步了解Agile.NET名称混淆规则设置、序列化异常排查及混淆排除范围配置方法，欢迎联系咨询。