ASP.NET Core 3.1 升級 5.0 - 行前準備

.NET Core 3.1 的下一個版本 - .NET 5，已隨 .NET Conf 2020 正式釋出，我自己的盤算是等 .NET 6 LTS 再大規模應用在工作專案，但自己的 Side-Project 會先玩，於是我的 Blog 又成為首選。動手前先做功課，了解 ASP.NET Core 3.1 升級 ASP.NET Core 5 步驟及不相容變更(Breaking Changes)。

題外話，.NET Core 3.1 的下個版本是 .NET 5，那 ASP.NET Core 3.1 的下個版本是？ASP.NET Core 5! 不是 ASP.NET 5，ASP.NET 5 在 2015 就用掉了，噗。

MSDocs 有篇從 3.1 升級 5.0 指南，絕大部分修改調整都集中在 Blazor 上，ASP.NET Core 除了改版號幾乎什麼都不用調，比上回 2.2 升 3.1 還輕鬆，但還是整理一下重點：

1. Visual Studio 2019 需升級到 16.8+，並安裝 .NET 5 SDK
2. global.json
   sdk 要由 3.1.200 改為 5.0.100
3. 更新 csproj TFM (Target Framework Moniker)
   TargetFramework 由 netcoreapp3.1 改為 net5.0
4. 仍在發展初期的 Blazor WebAssembly 及 Blazor Server 專案，異動項目比較多
   • wwwroot/index.html 及 Pages/_Host.cshtml 要新增 <link href="{ASSEMBLY NAME}.styles.css" rel="stylesheet" />
   • _Imports.razor 新增 using Microsoft.AspNetCore.Components.Web.Virtualization.
   • Shared/MainLayout.razor MainLayout 元件加上 class="page"
   • Shared 資料夾新增 MainLayout.razor.css、NavMenu.razor.css
   • wwwroot/css/app.css 或 wwwroot/css/site.css 移除基本樣式及自訂樣式以外的設定
5. Blazor WebAssembly 專案更新
   修改 csproj：
   • Sdk 由 Microsoft.NET.Sdk.Web 改為 Microsoft.NET.Sdk.BlazorWebAssembly
   • TargetFramework 由 netstandard2.1 改為 net5.0
   • 移除 RazorLangVersion 設定
   • 移除 Microsoft.AspNetCore.Components.WebAssembly.Build 參照
   • NuGet 套件更新到最新版
     wwwroot/index.html 的 <app> 改為 <div id="app">Loading...</div>
     Program.cs 配合上述修改，builder 註冊寫法做了修改
6. Blazor WebAssembly App 如有整合 Azure Active Directory (ADD) 及 AAD BC2，有些程式寫法需要調整
7. 升級調整完建議 dotnet nuget locals --clear all 並 Rebuild 專案以清除舊版殘留
8. Blazor Progressive Web Application (PWA) 專案更新
   新增 wwwroot\service-worker.js
9. Razor Class Library (RCL) 更新
   TargetFramework 由 netstandard2.1 改為 net5.0，移除 RazorLangVersion 設定，NuGet 套件更新到最新版
10. ASP.NET Core 專案參照調整
    Microsoft.AspNetCore.JsonPatch、Microsoft.EntityFrameworkCore.Tools、Microsoft.Extensions.Caching.Abstractions 由 3.1.6 升到 5.0.5
    System.Net.Http.Json 由 3.2.1 升到 5.0.0
11. Docker Image 建置由 docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1 改為 docker pull mcr.microsoft.com/dotnet/aspnet:5.0
12. ASP.NET Core MVC 及 Razor Pages Model Binding 變更
    • 過去，來自伺服器的 DateTime 值會採本地時區，JSON 輸入的 DateTime 或 DateTimeOffset 則採 UTC 時區。5.0 改為統一採用 UTC 時區。如要沿續舊規則，可在 Startup.ConfigureServices 將 DateTimeModelBinderProvider 移除
    • 為支援 C# 9 Record 型別，ComplexTypeModelBinderProvider、ComplexTypeModelBinder 被標為過時，改以 ComplexObjectModelBinderProvider 及 ComplexObjectModelBinder 取代，要沿用需額外參考
13. UseDatabaseErrorPage 被標為過時，被 AddDatabaseDeveloperPageExceptionFilter 及 UseMigrationsEndPoint 取代，如有使用要改 Startup.ConfigureServices

還有很多瑣碎 .NET 5 不相容修改，照慣例 MSDocs 整理了完整清單，並依 ASP.NET Core、Code Analysis、核心程式庫、加密程式庫、EF Core、全球化、Interop、MSBuild、Networking、安全、序列化、Windows Form、WPF 分門別類，.NET 文件整理之用心實在沒話說。由於項目蠻多的，基本上就是等編譯出錯或遇到再查，多半會有明確的訊息提示，現在先不花時間。下一篇再來記錄這次升級經驗。

Keypoints of upgrading from ASP.NET Core 3.1 to 5.0.