摘要：接下来发生的，就是把警告当成提醒来处理的全过程记录。警告的意思不复杂：项目里那套老旧的 WebClient/WebRequest 在被逐步边缘化了，编译器在提醒你别再指望它们会一直存在。用着也能跑，不会立刻挂掉，但这是平台在明说——将来可能直接删掉，早点把替换
迁移到 .NET 9 后，编译器抛出了一个警告：warning SYSLIB0014，提示
接下来发生的，就是把警告当成提醒来处理的全过程记录。警告的意思不复杂：项目里那套老旧的 WebClient/WebRequest 在被逐步边缘化了，编译器在提醒你别再指望它们会一直存在。用着也能跑，不会立刻挂掉，但这是平台在明说——将来可能直接删掉，早点把替换工作做了，别等到真要用到时才手忙脚乱。
这次迁移本来是常规操作，把项目从 .NET Framework 挪到 net9。按微软的路线图，HttpClient 从很早就被推荐了，后来在 .NET Core 里，老的 API 就慢慢被弱化，到了现在这一步，警告变成了“废弃标记”。对我们来说，这不是一句可有可无的提醒，而是要开始落地执行的信号。
我把这次迁移当成一次小型演练，记录下关键点。项目后端用的是 FastEndpoints，这个框架对小团队挺友好的：上手快，里边自带的事件总线和任务队列能省不少事，性能也不错。我做了些基准测试，和 Asp.Net Core Minimal 相差不多，响应速度比传统的 MVC 要好些。短期内继续用它没问题，但如果要扩成多人多模块的大项目，建议考虑 ABP 这种偏企业级的框架，管理和扩展性更合适，避免以后拆分和治理时麻烦越堆越多。
说说我对 WebClient 的印象：差不多十年前用过一次，场景挺简单——做 ActiveX 插件，一口气把一堆图片下下来。WebClient 包了 WebRequest，写起来省事，样板少，适合那种快速实现的场景。问题是，现在的关注点变了，性能、连接复用、超时策略、异步稳定性这些更重要。HttpClient 在这些方面更灵活，也更利于统一管理连接池，长期看更靠谱。
搬代码的时候碰到的技术要点比较具体，不是仅仅换个类名就完事，得琢磨下面这些细节：
- 先在代码库开个迁移分支，把目标框架改成 net9，跑一次编译，把所有警告和错误清单拿出来。SYSLIB0014 是最突出的一条，定位到创建 WebClient 的地方，把调用先包一层适配器。适配器里引入 IHttpClientFactory，由工厂管 HttpClient 的生命周期，统一配置超时、重试策略和连接相关参数。把修改集中，可以降低回滚风险，也方便逐步验证。
- 别光改类型名。HttpClient 的默认行为和旧 API 不一样，错误处理、超时设置和重试逻辑都需要重新考虑。以前同步调用习惯写 try/catch 的地方，改成异步后，有的异常类型会变，有的超时表现也不同。把这些逻辑拆开，单独写测试覆盖，别抱着“应该差不多”的心态直接上线。
- 项目里如果有大量同步旧代码，改成 HttpClient 的异步调用后，调用链要理清。忘记 await 的坑很常见，会导致任务未完成就继续往下走。为了避免 thread pool 被耗光，注意使用 IHttpClientFactory 并发控制，像需要并发下载的任务，加入 SemaphoreSlim 来限制并发度，不然一发多线程并发就把自己或目标服务器干垮了。
- 测试要跟着走。单元测试中关于超时、重试和网络异常的断言需要重写。集成测试里多模拟网络波动、慢响应或断连场景，确认事件总线和任务队列在异常情况下不会把错误往外抛成灾。FastEndpoints 自带的 JobQueue 在这里有用，把会阻塞 IO 的长耗时任务放到队列里，保证请求层不被拖垮。
- 把改动通知到相关团队。这种替换看起来是内部细微改动，但会影响接口调用模式和异常类型，其他服务拿到新版本后要做兼容测试。我们在代码审查流程里新增了一个检查点：凡是涉及网络调用的更改，都必须有人复核测试过。多人把关能把上线风险降下来。
迁移的具体做法我这样安排：先把能集中改的地方抽成适配层，适配层内部用 IHttpClientFactory，并定义统一的配置方式（超时、重试策略、连接池设置等）。然后逐模块替换原有逻辑，改完一部分就跑一轮完整的单元和集成测试。遇到复杂场景（比如并发下载且需要控制速率），我会用 SemaphoreSlim 控制并发，用 Polly 或自定义逻辑实现重试和退避。最后上线前在 staging 环境把网络异常的场景大力跑几遍，确认 JobQueue 在异常情况下能把任务妥善重试或记录失败，而不是整个服务崩溃。
还有一点要注意的团队协作细节：替换后异常类型会发生变化，日志要写清楚，提示信息要被其他服务能识别。为此我们在改动里顺手改了几条监控告警阈值，避免上线初期被大量新异常刷屏，影响运维判断。
顺便提一句，.NET 10 的正式版据说会在下个月中旬发布，听说会带来一波 JIT 性能优化。对正在做迁移的人来说，这既是动力也是压力。平台在往更现代、更高效的方向走，旧的东西要赶紧换掉，留着反而是隐患。时间节点上可以计划把这次迁移当成两步走：先把代码迁到 net9 并替换废弃 API，稳定后再评估是否要上 net10 的新特性或做进一步性能调优。
如果你手上也有类似的迁移任务，遇到不确定的点可以私信我。我能分享一些具体替换策略、测试注意点和实践中的小坑，虽然对复杂架构问题帮得有限，但日常层面的经验交流还是能省些弯路。觉得这篇有用的，点个赞或者关注一下，方便以后一起交流。
来源：小宇科技每日一讲
