升级项目至.NET Core 3.1报错无法加载MvcJsonOptions类型咨询

问题现象 #

升级项目至.NET Core 3.1版本时抛出如下异常：

Could not load type 'Microsoft.AspNetCore.Mvc.MvcJsonOptions' from assembly 'Microsoft.AspNetCore.Mvc.Formatters.Json, Version=3.1.25.0'

已尝试以下操作均未解决问题：

• 将Swashbuckle.AspNetCore升级至5.0.0版本，异常仍然存在
• 手动移除.NET Core 3.1不再支持的Microsoft.AspNetCore.Mvc.Formatters.Json DLL，异常仍然存在
• 异常触发点为CreateHostBuilder(args).Build().Run()执行阶段，具体在调用Build()方法时抛出

根本原因 #

.NET Core 3.0开始，ASP.NET Core默认JSON序列化组件从Newtonsoft.Json切换为内置的System.Text.Json，MvcJsonOptions是仅存在于旧版Newtonsoft.Json格式化器中的类型，.NET Core 3.1内置的JSON格式化程序集不包含该类型。
之前的操作未生效的核心原因是：

1. Swashbuckle.AspNetCore 5.0.0为大版本迭代初期版本，存在.NET Core 3.1兼容缺陷
2. 手动删除DLL没有解决依赖绑定问题，项目中仍有第三方组件或旧配置逻辑在引用MvcJsonOptions类型

解决步骤 #

1. 清理旧版无效包引用
   右键项目选择「编辑项目文件」，删除所有针对Microsoft.AspNetCore.Mvc.Formatters.Json的独立包引用节点，该包仅适用于.NET Core 2.2及更早版本，3.0+版本无需单独引用。
2. 配置Newtonsoft.Json兼容支持（如果项目需要保留Newtonsoft.Json序列化逻辑）
   安装官方适配.NET Core 3.1的Newtonsoft.Json Mvc包，在包管理器控制台执行命令：

   Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 3.1.25
   

   修改Startup.cs中的服务注册代码，将原有MVC/控制器注册逻辑追加AddNewtonsoftJson配置，原MvcJsonOptions中的序列化配置全部迁移到该方法的配置委托中：

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllers()
               .AddNewtonsoftJson(options =>
               {
                   // 原有MvcJsonOptions中的配置迁移到此处，例如自定义命名策略、转换器等
                   options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";
               });
   }
   

3. 升级Swashbuckle相关包到稳定兼容版本
   将Swashbuckle相关的三个包版本统一升级到5.5.0及以上的3.1兼容稳定版，避免子包版本不一致导致的依赖冲突：
   • Swashbuckle.AspNetCore.Swagger
   • Swashbuckle.AspNetCore.SwaggerGen
   • Swashbuckle.AspNetCore.SwaggerUI
4. 清理编译缓存重新生成
   关闭Visual Studio，删除解决方案根目录及各项目目录下的bin、obj文件夹，重新打开项目执行包还原、全量编译后再运行即可解决问题。

内容的提问来源于stack exchange，提问作者Nikhil Chaudhary