.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.


Comments

# by ChrisTorng

非 Blazor 專案很簡單,只有 netcoreapp3.1 改為 net5.0,NuGet 套件全部升版,頂多 UseDatabaseErrorPage 改掉...(然後 DateTime 注意一下) 然後就升級完成了!

# by Jeffrey

to ChrisTorng,我這次的經驗沒升級 NuGet 套件,VS 執行 OK 但 Publish 不行,清 NuGet Cache 後就一切OK了。

Post a comment


38 - 1 =