我们在日常产品维护时往往会遇到底层基础框架需要升级的情况尤其是当底层框架升级到一个新的大版本时可能会带来一些不兼容的变更这时候我们就需要做好充分的准备工作以确保升级过程顺利进行。从本文开始我们将详细讲解如何将我们的产品从 .NET 8 升级到 .NET 10 。在正式升级之前我们需要对项目的依赖关系进行全面梳理包括第三方库的版本兼容性、NuGet 包的升级情况以及项目中使用的一些已废弃的 API 是否在新版本中被移除。与此同时我们还需要制定一份详细的升级计划明确升级的步骤、时间节点以及回滚方案以便在升级过程中出现问题时能够快速恢复到原有状态。只有做好这些准备工作才能最大程度地降低升级风险确保项目在升级后能够正常运行。一、确认环境在升级之前首先需要确认当前的开发环境是否满足 .NET 10 的要求。我们需要检查以下几个方面操作系统确保开发环境的操作系统版本支持 .NET 10以下是最低操作系统版本和推荐操作系统版本。平台最低支持版本推荐版本WindowsWindows 10 (1607) / Server 2016Windows 11 / Server 2022macOSmacOS 12 (Monterey)macOS 15 (Sequoia)LinuxUbuntu 20.04 / RHEL 8.10 / Debian 11最新 LTS 版本 (如 Ubuntu 24.04)开发工具确保使用的开发工具已经更新到支持 .NET 10 的版本。建议使用最新版本的 Visual Studio 2022 或更高版本以获得最佳的开发体验和兼容性。.NET SDK安装 .NET 10 SDK并确保环境变量配置正确。可以通过命令行运行dotnet --version来验证安装是否成功。安装 dotnet-outdated-tool这是一个非常有用的工具可以帮助我们检查项目中使用的 NuGet 包是否有更新版本是否存在过时的包特别是那些可能不兼容 .NET 10 的包。安装命令如下dotnet toolinstall--globaldotnet-outdated-tool以上这些环境确认步骤是升级前必须做的基础准备工作确保开发环境与 .NET 10 的要求相匹配可以避免在升级过程中遇到不必要的环境兼容性问题。二、升级步骤在这一小节我们将详细讲解升级步骤为后续的升级做准备。2.1 基础框架升级框架升级涉及到 10个.csproj10个Dockerfile文件的修改以及一些基础设施相关的配置文件的调整。我们需要将所有项目的目标框架Target Framework从net8.0修改为net10.0并且升级所有相关的 NuGet 包到支持 .NET 10 的版本。在这个过程中我们可能会遇到一些破坏性变更Breaking Changes需要仔细阅读 .NET 10 的发布说明了解哪些 API 已经被废弃或移除并且根据需要修改代码以适应新的框架版本。下面这个检查列表可以帮助我们系统地完成升级将所有.csproj中TargetFrameworknet8.0/TargetFramework改为net10.010 个服务可并行修改更新所有Dockerfile基础镜像mcr.microsoft.com/dotnet/sdk:8.0→mcr.microsoft.com/dotnet/sdk:10.0mcr.microsoft.com/dotnet/aspnet:8.0→mcr.microsoft.com/dotnet/aspnet:10.0移除SP.Common/SP.Common.csproj中严重过时的Microsoft.AspNetCore.Http.Abstractions 2.2.02018 年 ASP.NET Core 2.2 遗留包.NET 10 框架已内置从各服务.csproj中移除以下在net10.0框架内已内置的包System.Text.Json出现在 SP.Common 等多个服务System.Text.Encodings.Web出现在 IdentityService、FinanceService、ConfigService、NotificationService、ReportService 服务中2.2 微软官方包批量升级这是一个低风险步骤我们只需要将下表中包的版本升级到支持 .NET 10 的最新版本即可。可以使用dotnet-outdated工具来自动检查和升级这些包确保它们与 .NET 10 兼容。包名当前版本目标版本涉及服务数Microsoft.EntityFrameworkCore.*所有子包8.0.810.0.x8 个Microsoft.AspNetCore.Identity.EntityFrameworkCore8.0.810.0.x6 个Microsoft.AspNetCore.Authentication.JwtBearer8.0.810.0.xConfigService、IdentityServiceMicrosoft.Extensions.*所有 Abstractions8.0.x10.0.xSP.CommonSystem.Formats.Asn18.0.110.0.x 或移除SP.GatewayMicrosoft.VisualStudio.Web.CodeGeneration.Design8.0.710.0.x6 个开发工具Microsoft.Build17.8.43对齐 SDK 版本6 个开发工具同样列出检查列表批量执行包版本升级Microsoft.EntityFrameworkCore.*所有子包Microsoft.AspNetCore.Identity.EntityFrameworkCoreMicrosoft.AspNetCore.Authentication.JwtBearerMicrosoft.Extensions.*所有 AbstractionsSystem.Formats.Asn1升级到支持 .NET 10 的版本或根据 .NET 10 的更新情况考虑移除Microsoft.VisualStudio.Web.CodeGeneration.Design升级到支持 .NET 10 的版本Microsoft.Build升级到与 .NET 10 SDK 版本对齐的版本2.3 EF Core Pomelo MySQL这一步属于中风险操作我们要做的是将Pomelo.EntityFrameworkCore.MySql 8.0.3包升级到 10.0.x 版本以确保它与 EF Core 10 和 .NET 10 兼容这个操作一共涉及八个微服务。在升级完后我们还需要验证每个微服务的EF Core 的迁移历史是否能够正常应用到 MySQL 数据库中确保数据访问层在升级后能够正常工作。以下是检查列表EF Core 官方包随 Phase 2 一同升到10.0.xPomelo.EntityFrameworkCore.MySql 8.0.3→ 升到10.0.xPomelo 版本号跟随 EF Core 而非 MySQL Server 版本在 NuGet 上确认10.0.x可用涉及 8 个服务验证各服务 EF Core 迁移历史EF 8 → 10 的迁移文件本身通常无需修改TipPomelo 版本号跟随 EF Core 的版本号而非 MySQL Server 版本号2.4 认证与安全包这一步也是中风险操作我们需要升级 OpenIddict 包到支持 .NET 10 的版本以确保认证和授权功能在升级后能够正常工作。OpenIddict 是我们项目中用于实现身份认证和授权的核心组件升级过程中需要特别注意它与 ASP.NET Core 10 的兼容性以及可能引入的破坏性变更。以下是检查列表OpenIddict 7.0.0→ 升级到最新版确认net10.0TFM 支持涉及 4 个包出现在 SP.Gateway 和 SP.IdentityService包名出现位置OpenIddict.AspNetCoreIdentityServiceOpenIddict.EntityFrameworkCoreIdentityServiceOpenIddict.Validation.AspNetCoreGateway、IdentityServiceOpenIddict.Validation.ServerIntegrationGatewaySystem.IdentityModel.Tokens.Jwt 8.12.1→ 升到最新版确认与新版 OpenIddict 兼容SP.CommonAzure.Identity 1.11.4→ 升到最新版SP.Gateway2.5 API 文档迁移 — Swashbuckle → OpenAPI Scalar这一步的风险不大但是工作量巨大。我们需要将所有微服务中使用的 Swashbuckle 包替换为 OpenAPI 和 Scalar 相关的包以适应 .NET 10 的新特性和最佳实践。这个操作涉及到 API 文档生成和维护的核心部分需要确保在替换过程中 API 文档能够正确生成并且与现有的 API 定义保持一致。1. 所有服务这里是针对八个服务都需要升级的包我们需要将以下 Swashbuckle 包替换为 OpenAPI 和 Scalar 相关的包并且修改Program.cs中的 API 文档配置代码以适应新的包和 .NET 10 的特性。以下是检查列表每个服务.csproj移除Swashbuckle.AspNetCore 6.6.2添加Scalar.AspNetCoreNuGet 包每个服务Program.cs移除AddSwaggerGen(c { ... })整个配置块含 XML 注释、Bearer 安全配置移除app.UseSwagger()和app.UseSwaggerUI()添加基于 .NET 10 OpenAPI 的新配置// 注册 OpenAPI含 JWT Bearer 安全方案builder.Services.AddOpenApi(options{options.AddDocumentTransformer((document,context,ct){document.Infonew(){Title服务名称 API,Versionv1};returnTask.CompletedTask;});options.AddOperationTransformer((operation,context,ct){// JWT Bearer 安全配置operation.Security[newOpenApiSecurityRequirement{[newOpenApiSecurityScheme{ReferencenewOpenApiReference{TypeReferenceType.SecurityScheme,IdBearer}}][]}];returnTask.CompletedTask;});});// 仅 Development/Local 环境暴露文档 UIif(app.Environment.IsDevelopment()||app.Environment.EnvironmentNameLocal){app.MapOpenApi();app.MapScalarApiReference();// 访问路径/scalar/v1}IdentityService 额外注意SwaggerTokenRequestFilter的逻辑需评估是否迁移为IOpenApiOperationTransformer2. SP.Gateway网关服务中有些包需要单独的升级并且 API 文档的聚合方案需要重新设计。由于我们之前使用 Swashbuckle 和 SwaggerForOcelot 来实现 API 文档的聚合展示现在需要评估新的方案来替代它们以适应 .NET 10 的新特性和最佳实践。以下是检查列表.csproj移除Swashbuckle.AspNetCore 6.6.2和MMLib.SwaggerForOcelot 8.3.2添加Scalar.AspNetCoreProgram.cs移除AddSwaggerGen()AddSwaggerForOcelot()及其 UI 配置块移除app.UseSwaggerForOcelotUI(...)调用Gateway 层文档聚合方案二选一方案说明方案 A推荐各下游服务通过 Ocelot 路由暴露自身/openapi/v1.jsonGateway Scalar UI 配置多端点分服务展示方案 B评估是否有支持 OpenAPI 的 SwaggerForOcelot 替代库同步清理 Nacos 中的SwaggerConfigDataId 配置2.6 API 网关 Ocelot 升级这是一个高风险的步骤我们需要将 Ocelot 包升级到支持 .NET 10 的版本以确保 API 网关能够正常工作。Ocelot 是我们项目中用于实现 API 网关功能的核心组件升级过程中需要特别注意它与 ASP.NET Core 10 的兼容性以及可能引入的破坏性变更。以下是检查列表Ocelot 24.0.1在 NuGet 确认支持net10.0或net9.0的最新版本若最新版仅有net9.0TFM.NET 10 可向下兼容引用需验证功能正常升级后检查ocelot.json路由配置是否有破坏性变更2.7 Baidu.AI OCR 替换 为 DeepSeek OCR 或其他 OCR 方案进行这一步的目的是由于Baidu.AI OCR SDK 目前不支持 .NET10因此我们需要将其替换为 DeepSeek OCR 以确保智能账单录入功能能够在升级后继续正常工作。1. 移除 Baidu.AI首先我们要移除 Baidu.AI OCR SDK 相关的代码和配置这包括.csproj中移除Baidu.AI 4.15.16删除或重命名BaiduOCROptions.cs→DeepSeekOCROptions.cs移除OCRConsumerService中的Ocr _clientBaidu.Aip.Ocr.Ocr字段及初始化逻辑移除 Nacos/appsettings 中的BaiduOCR配置节2. 新增 DeepSeek OCR 实现新建DeepSeekOCROptionspublicclassDeepSeekOCROptions{publicstringApiKey{get;set;};publicstringEndpoint{get;set;}https://api.deepseek.com;publicstringModel{get;set;}deepseek-chat;// 需支持视觉的模型}修改OCRServiceExtensions.cspublicstaticIServiceCollectionAddOCRService(thisIServiceCollectionservices,IConfigurationconfiguration,stringsectionNameDeepSeekOCR){services.ConfigureDeepSeekOCROptions(configuration.GetSection(sectionName));services.AddScopedIOCRService,DeepSeekOCRServiceImpl();// 接口实现类无需改动returnservices;}IOCRService接口和BaiduOCRServiceImpl仅负责发 RabbitMQ 消息无需改动修改OCRConsumerService.cs构造函数注入IHttpClientFactory替换Ocr _client替换 Baidu API 调用代码块为 DeepSeek Vision API 调用// 图片字节 → base64stringbase64ImageConvert.ToBase64String(image);stringmimeTypeimage/jpeg;// 根据实际 ContentType 确定// 构造 DeepSeek Vision 请求varrequestBodynew{model_options.Model,messagesnew[]{new{roleuser,contentnewobject[]{new{typeimage_url,image_urlnew{url$data:{mimeType};base64,{base64Image}}},new{typetext,text请识别图片中的所有文字只输出文字内容不要添加任何解释。}}}}};varresponseawaithttpClient.PostAsJsonAsync(/chat/completions,requestBody,stoppingToken);response.EnsureSuccessStatusCode();varresultawaitresponse.Content.ReadFromJsonAsyncJsonElement(cancellationToken:stoppingToken);stringrecognizedTextresult.GetProperty(choices)[0].GetProperty(message).GetProperty(content).GetString()??;更新 appsettings 添加DeepSeekOCR配置节DeepSeekOCR:{ApiKey:,Endpoint:https://api.deepseek.com,Model:deepseek-chat}2.8 SP.MLService 服务中的 Microsoft.ML 升级到 .NET 10这是一个高风险的步骤我们需要将 SP.MLService 服务中使用的 Microsoft.ML 包升级到支持 .NET 10 的版本以确保机器学习相关功能能够在升级后继续正常工作。Microsoft.ML 是我们项目中用于实现机器学习功能的核心组件升级过程中需要特别注意它与 .NET 10 的兼容性以及可能引入的破坏性变更。它被MLContext、LightGbmRankingTrainer、Text Featurization Pipeline 使用核心文件是CategoryMatcher.cs。以下是检查列表确认 NuGet 上Microsoft.ML和Microsoft.ML.LightGbm是否有支持net10.0或net9.0的版本若有 → 直接升级在 DockerLinux和 Windows 两个平台测试原生库LightGBM native binaries加载若仅net9.0→ 以兼容方式引用.NET 10 向下兼容net9包升级Microsoft.ML和Microsoft.ML.LightGbm到对应最新版升级MongoDB.Driver 3.5.0到最新版FeedbackStorage 依赖运行CategoryMatcher功能验证训练 → 预测确认排名结果正确2.9 其余第三方包最后我们需要对项目中使用的其他第三方包进行升级以确保它们与 .NET 10 兼容。这些包可能不如前面提到的核心包那样关键但同样需要升级以避免潜在的兼容性问题但是这一步属于低风险操作。以下是升级列表包当前版本风险说明Serilog4.2.0 低多 TFM升最新版Serilog.AspNetCore8.0.1 低升最新版Serilog.Sinks.Grafana.Loki8.3.0 低升最新版AutoMapper14.0.0 低多 TFMQuartz3.14.0 低确认 net10 TFMQuartz.AspNetCore3.14.0 低同上RabbitMQ.Client7.1.2 低netstandard兼容StackExchange.Redis2.7.33 低netstandard兼容Refit8.0.0 中确认最新版 TFMRefit.HttpClientFactory8.0.0 中同上SixLabors.ImageSharp3.1.11 低多 TFMSixLabors.Fonts2.1.3 低多 TFMSixLabors.ImageSharp.Drawing2.0.2 低多 TFMMongoDB.Driver3.5.0 低多 TFMRestSharp112.1.0 低多 TFMMinio6.0.4 中确认最新版 net10 支持Twilio7.13.0 低多 TFMMicrosoft.Data.SqlClient5.1.3 低升最新版2.10 破坏性变更代码审查在完成上述升级步骤后我们需要进行一次全面的代码审查重点关注可能存在的破坏性变更。这包括但不限于以下几个方面EF Core 8 升级 10 Breaking Changes查阅官方文档重点关注查询行为、Owned Entity、JSON 列映射变化逐一核对各服务 DbContext 和 LINQ 查询写法ASP.NET Core Breaking Changes查阅 .NET 9 迁移文档查阅 .NET 10 迁移文档重点关注中间件管道、路由、Minimal API 变更OpenIddict 配置 API 变更对照新版 OpenIddict Changelog 检查SP.IdentityService/Program.cs和SP.Gateway/Program.cs中的AddOpenIddict()配置链SwaggerTokenRequestFilter迁移评估文件SP.IdentityService/SwaggerTokenRequestFilter.cs评估其 Token 请求逻辑是否需要迁移为IOpenApiOperationTransformer.NET 10 OpenAPI 扩展点2.11 验证升级完成后我们需要进行全面的验证确保项目在升级后能够正常运行并且性能没有明显下降。这包括dotnet build每个项目确认零错误顺序SP.Common→ 其余 8 个服务 →SP.Gatewaydotnet ef migrations list验证各有迁移的服务历史状态完整Docker Compose 启动验证所有服务健康检查通过访问各服务/scalar/v1确认 Scalar UI 正常加载且 JWT Bearer 认证操作可用完整 AuthN 流程Token 申请 → 刷新 → JwtBearer 验证OCR 端对端测试上传图片 → RabbitMQ 触发 → DeepSeek 识别 → DB 写入 → 查询识别结果SP.MLService 分类预测模型加载/训练 → 预测接口返回正确结果服务间 Refit HTTP 调用链联调测试2.12 风险汇总在这里我们总结一下升级过程中可能遇到的风险点在升级的过程中要格外注意风险等级包 / 领域说明 高已决策Swashbuckle MMLib.SwaggerForOcelot迁移到 OpenAPI Scalar需修改所有服务 Program.cs 高已决策Baidu.AI替换为 DeepSeek Vision APIOCRConsumerService 需重写 高随主线Microsoft.ML / LightGbm原生库 .NET 10 兼容性需验证LightGBM native binaries 需测试 中OpenIddict版本升级后配置 API 可能有变化 中Ocelot需确认 net10 或 net9 版本可用 中Pomelo EFCore MySQLEF Core 10 对应版本需确认 NuGet 可用 中Refit需确认最新版 TFM 支持 低Microsoft.* 官方包版本号随 .NET 升级低风险 低Serilog / AutoMapper / Quartz 等多 TFM 库向下兼容三、总结本篇文章我们详细介绍了将项目从 .NET 8 升级到 .NET 10 的准备工作和升级步骤。升级过程中我们需要对项目的依赖关系进行全面梳理制定详细的升级计划并且按照步骤逐一完成基础框架升级、核心包升级、API 文档迁移、API 网关升级以及 OCR 方案替换等关键操作。在升级过程中我们还需要特别注意可能存在的破坏性变更并且在升级完成后进行全面的验证确保项目能够正常运行并且性能没有明显下降。通过这次升级我们不仅能够享受到 .NET 10 带来的性能优化和新特性还能够为后续的 AI 智能化改造打下坚实的基础。