NSwag项目升级至.NET 8时遇到的类型加载问题解析

在将项目从.NET升级到.NET 8并同时将NSwag从13版本升级到14版本后，开发者可能会遇到类型加载失败的问题。本文将详细分析这个问题的原因及解决方案。

问题现象

当开发者执行NSwag.MSBuild任务时，控制台会报出类似以下的错误信息：

System.TypeLoadException: Could not load type 'NJsonSchema.Annotations.JsonSchemaAttribute' from assembly 'NJsonSchema, Version=11.0.0.0, Culture=neutral, PublicKeyToken=c2f9c3bdfae56102'

或者

System.TypeLoadException: Could not load type 'NJsonSchema.Converters.JsonInheritanceConverter' from assembly 'NJsonSchema, Version=11.0.0.0, Culture=neutral, PublicKeyToken=c2f9c3bdfae56102'

问题根源

这个问题的根本原因是NSwag 14版本对NJsonSchema库进行了模块化重构，将部分功能拆分到了独立的NuGet包中：

1. JsonSchemaAttribute等注解类被移到了新的NJsonSchema.Annotations包中
2. JsonInheritanceConverter等Newtonsoft.Json相关的转换器被移到了NJsonSchema.NewtonsoftJson包中

解决方案

要解决这个问题，开发者需要确保项目中正确引用了所有必要的依赖包：

1. 对于JsonSchemaAttribute缺失的问题：

   • 添加NJsonSchema.Annotations包的引用
   • 确保版本与NJsonSchema主包一致（如11.0.0）

2. 对于JsonInheritanceConverter缺失的问题：

   • 添加NJsonSchema.NewtonsoftJson包的引用
   • 同样保持版本一致

最佳实践

在进行NSwag大版本升级时，建议：

1. 仔细阅读官方升级说明，了解破坏性变更
2. 使用NuGet包管理器统一更新所有NSwag相关包
3. 检查项目中的所有直接和间接依赖，确保没有遗漏
4. 在CI/CD环境中，清理构建缓存后再进行测试

总结

NSwag 14版本的模块化设计虽然带来了更清晰的依赖关系，但也可能导致升级时的兼容性问题。通过正确添加新的依赖包，开发者可以顺利解决这些类型加载失败的问题，享受新版本带来的改进和功能增强。