ASP.NET Core 3.1 升級 5.0 - 行前準備
2 | 5,995 |
.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 還輕鬆,但還是整理一下重點:
- Visual Studio 2019 需升級到 16.8+,並安裝 .NET 5 SDK
- global.json
sdk 要由 3.1.200 改為 5.0.100 - 更新 csproj TFM (Target Framework Moniker)
TargetFramework 由 netcoreapp3.1 改為 net5.0 - 仍在發展初期的 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 移除基本樣式及自訂樣式以外的設定
- wwwroot/index.html 及 Pages/_Host.cshtml 要新增
- 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 註冊寫法做了修改
- Blazor WebAssembly App 如有整合 Azure Active Directory (ADD) 及 AAD BC2,有些程式寫法需要調整
- 升級調整完建議 dotnet nuget locals --clear all 並 Rebuild 專案以清除舊版殘留
- Blazor Progressive Web Application (PWA) 專案更新
新增 wwwroot\service-worker.js - Razor Class Library (RCL) 更新
TargetFramework 由 netstandard2.1 改為 net5.0,移除 RazorLangVersion 設定,NuGet 套件更新到最新版 - 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 - Docker Image 建置由 docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1 改為 docker pull mcr.microsoft.com/dotnet/aspnet:5.0
- 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 取代,要沿用需額外參考
- 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.
Comments
# by ChrisTorng
非 Blazor 專案很簡單,只有 netcoreapp3.1 改為 net5.0,NuGet 套件全部升版,頂多 UseDatabaseErrorPage 改掉...(然後 DateTime 注意一下) 然後就升級完成了!
# by Jeffrey
to ChrisTorng,我這次的經驗沒升級 NuGet 套件,VS 執行 OK 但 Publish 不行,清 NuGet Cache 後就一切OK了。