使用旧版本Agile.NET时工程能够正常保护，但升级到新版本后，可能会出现报错、配置项失去作用、输出的程序集运行不正常等情况，这类问题其实经常遇到。对于Agile.NET升级版本后配置为何不兼容，以及旧工程迁移时应该先检查哪些内容，需要仔细分析，而不应该立刻重新打开所有保护选项。按照官方文档的描述，Agile.NET项目能够把软件程序集和保护设置保存下来，并输出为XML格式的项目文件，还可以通过命令行工具来执行。这就表明，在迁移旧工程时，项目文件、程序集路径、保护项以及构建脚本等因素，都会对最终结果产生影响。

　　一、Agile.NET升级版本后配置为什么不兼容

　　升级之后配置出现不兼容，一般不是由于某一个按钮失效造成的，它往往与旧版本的项目文件、保护项名称、预设规则、程序集依赖以及构建环境等多种变化有关。如果先将这些差异点分开来看，定位问题就会变得更简单。

　　1、旧项目文件格式有差异

　　Agile.NET的项目文件里面，存放着程序集、输出目录、签名文件以及各项保护设置。当软件升级到新版本后，原来的XML项目文件或许还能顺利打开，只不过里面部分选项的解析方式已经发生了改变。这样一来，虽然界面上看着一切正常，可实际构建出来的结果却可能会出现不一致。

　　2、保护项默认行为改变

　　Agile.NET里面可以配置多种保护方式，像代码虚拟化、代码加密、符号重命名、方法调用混淆、字符串加密、资源加密、程序集合并、控制流混淆，还有声明式混淆等等。如果新版本悄悄修改了某些保护项的默认强度，而旧工程又直接套用了原来的配置，就很有可能会影响到动态调用、数据串行化、插件加载这些功能的正常运作。

　　3、程序集依赖没有一起加入

　　按照官方文档的推荐做法，应当把软件中用到的所有程序集都添加到项目里面，哪怕有些程序集你并不打算保护，Agile.NET也还是会将它们复制到输出目录中去。迁移旧工程的时候，要是只加入了主程序，而忽略了公共库、插件库或者第三方依赖，虽然构建过程能够完成，但运行时就可能出现缺少文件或类型解析出错的情况。

　　4、签名和输出路径变化

　　要是原始程序采用了强名称签名，那么在Agile.NET构建时，也需要用同样的强名称密钥再进行一次签名。升级以后，如果文件路径发生了变化、密钥文件找不到，或者输出目录被更换，就很容易导致新生成的程序集与旧的部署包对应不上。

　　二、Agile.NET旧工程迁移时该先检查什么

　　在没有确认之前，不要一上来就把以前的配置直接导入进去然后点构建。比较可靠的方式是，先把现存的配置整体梳理一遍，然后按照从低强度保护到高强度保护的顺序，一步步去验证。

　　1、先备份旧工程和输出包

　　在正式开始迁移之前，最好将旧版Agile.NET的项目文件、保护后输出的程序集、未加保护的原始程序集，还有构建脚本和部署包全都备份下来。这样如果后面新版本的结果出了差错，就可以拿来对照排查，看看究竟是保护配置变动了，还是应用程序的代码本身就有了变化。

　　2、检查程序集清单

　　把主程序、业务类库、插件类库、公共模型层、配置类库以及第三方依赖逐个核对一遍，确保没有遗漏。需要特别留意那些涉及动态调用、Json数据模型、服务接口、组件互操作、插件入口之类的地方，确认这些名称是不是需要排除在重命名范围之外。

　　3、检查保护项开关

　　可以先把基础的重命名功能，或者其他风险程度比较低的保护项打开，完成构建以后跑一遍主流程。等到确认没有出现问题，再一步一步地把控制流混淆、字符串加密、资源加密、虚拟化或者代码加密这些加进去。官方文档里头，也是把保护过程划分成了不同的操作配置，所以在迁移的时候并不适合一口气全部启用。

　　4、检查构建脚本路径

　　要是旧工程以前是通过命令行或者持续集成流水线来构建的，那就需要重新检查一下Agile.NET的安装位置、项目文件的存放路径、输入程序集的路径、输出目录以及签名文件的路径。在图形界面上能够成功构建，并不能保证在自动化流水线上也能顺利通过。

　　三、Agile.NET迁移后怎么确认配置可用

　　迁移工作完成之后，不能光看到构建成功了就认为万事大吉。根据Agile.NET官方文档里关于构建流程的说明，配好保护措施后点击构建，等到构建结束，就可以打开并运行被保护的程序集来检验。真正起决定性作用的，是最后的运行验证环节。

　　1、做功能冒烟测试

　　可以先测试登录、主界面显示、配置文件读取、接口调用、数据库访问、文件导入导出等这些主要业务流程。一旦发现这些流程中有哪个地方出了毛病，就别急着再往上添加更高强度的保护设置。

　　2、重点测动态调用和数据转换

　　经过混淆处理之后，最容易出问题的环节往往集中在Json字段、配置绑定、枚举字符串、接口数据传输对象、插件发现，还有通过名称动态创建对象这些地方。所以在迁移的时候，应当提前准备好固定的测试样例，一项一项地去确认字段名称和数据类型是否仍然能够匹配得上。

　　3、对比新旧输出结果

　　把旧版本保护后的发布包和新版本的保护包，放到同一个测试环境下面进行对比；可以检查文件数量的变化、程序集名称有没有改动、签名状态是否一致，还有配置文件、资源文件以及运行日志等等。差异点发现得越早，将来需要回滚所付出的代价就越低。

　　4、保留迁移记录

　　把这次用到的Agile.NET版本号、新旧两个版本的项目文件、排除重命名的规则、各个保护项的开关状态、签名文件信息、测试结论以及剩余未解决的问题全都记录下来。以后再碰到升级的时候，这份记录的价值比临时去翻看配置要高得多。

　　总结

　　Agile.NET升级版本以后配置出现不兼容，比较常见的原因主要就出在旧项目文件、保护项的默认行为、程序集依赖、签名路径以及构建脚本的这些变化上面。对于旧工程的迁移，应该首先检查项目文件、程序集清单、排除规则、签名文件和流水线参数，然后再逐步打开保护项，去做一轮回归验证。迁移这件事情，并不是把旧的配置原封不动地搬过去就行了，而是要重新确认清楚，哪些部分可以被保护，哪些外部约定必须被保留下来。