ASP.NET Core 2.0 Web API项目升级到ASP.NET Core 3.0概要笔记

手头有个ASP.NET Core 2.0的项目，打算将里面的依赖包进行一个版本升级，鉴于该项目还是一年前开发的，使用的是.NET Core 2.0的版本，这次正好借着.NET Core 3.0在上个月刚刚发布的机会，干脆一起将该项目所使用的.NET Core版本从2.0升级到3.0，但这过程也并不是鼠标点点就能平滑完成的，因此，撰文一篇，简要介绍一下升级的几个关键点。由于不同的项目所依赖的第三方NuGet包并不相同，所以我只介绍我手上这个项目的升级过程，有些第三方的NuGet包或许还没有支持.NET Core 3.0的版本，这就需要到这些依赖项的官方主页或者Github项目上寻找解决方案了。

先决条件

.NET Core 3.0 SDK和Visual Studio 2019 16.3.0以上版本

升级目标框架（Target Framework）的版本

第一步非常简单，就是在项目上点击鼠标右键，选择Properties，在打开的项目属性页中，将Target framework从.NET Core 2.0改为.NET Core 3.0：

经过这一步操作，我们已经将项目的Target Framework由netcoreapp2.0改为netcoreapp3.0：

然后，不出意外地发现，在解决方案资源管理器中，所有的外部依赖都出现了黄色小叹号：

编译输出窗口也显示错误信息，告知Microsoft.AspNetCore.All这个依赖包无法支持.NET Core 3.0以及更高版本。在NuGet Package Manager中搜索，发现Microsoft.AspNetCore.All这个依赖包的确没有3.0的版本：

其实，从.NET Core 3.0开始，所有以“Microsoft.AspNetCore“作为命名开头的库，不再提供单独的NuGet包，这些包所包含的库文件（DLL）已经全都包含在Microsoft.AspNetCore.App这一公共框架中，而Microsoft.NET.Sdk.Web SDK已经隐式地引用了Microsoft.AspNetCore.App，因此，我们只需要编辑csproj文件，将多余的Microsoft.AspNetCore.XXXX的项目引用删掉即可（因为项目的SDK已经设置为了Microsoft.NET.Sdk.Web）。删掉多余的引用之后，保存项目文件，所有黄色小叹号消失，项目可以正常编译。

过时的IHostingEnvironment与IApplicationLifetime对象

从.NET Core 3.0开始，IHostingEnvironment与IApplicationLifetime已被标记为“过时（Obsolete）”，这意味着在后续的.NET版本中，将不再继续支持这两个接口。如果我们在Startup的Configure方法中使用了这两个对象，那么最好也将这两个接口分别替换为：IWebHostEnvironment和IHostApplicationLifetime。

Endpoint Routing与AddMvc中间件

ASP.NET Core 3.0默认使用Endpoint Routing，而启用了Endpoint Routing后，AddMvc中间件就不被支持了。因此，当一个ASP.NET Core项目从2.x升级到3.0的时候，原有的“app.AddMvc()”方法调用就会出现一个警告，即使忽略这个警告强行执行程序，也会得到一个异常：

根据提示，可以用以下代码来禁用Endpoint Routing，以便继续使用app.AddMvc()的方式：

services.AddMvc(options => options.EnableEndpointRouting = false);

也可以使用下面的代码来替换AddMvc的调用：

app.UseRouting();

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
});

Swashbuckle.AspNetCore

如果Web API项目使用了Swashbuckle提供的Swagger，建议升级到5.0.0-rc4，虽然是预览版本，但是对于.NET Core 3.0的支持是挺好的。其中有两个变化，第一个是在配置Swagger服务的时候，原来使用的是Swagger的Info类，现在改用Microsoft Open API的OpenApiInfo类；第二个就是需要显式添加Microsoft.Extensions.PlatformAbstractions包引用。

总结

在进行了以上这些部分的调整之后，我们的项目就可以正常运行在.NET Core 3.0上了：

总的来说，ASP.NET Core的版本升级还是非常简单容易的，有些细节方面有可能还是需要进一步的调整，就要根据项目本身的需要而定了。