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的版本升級還是非常簡單容易的，有些細節方面有可能還是需要進一步的調整，就要根據專案本身的需要而定了。