最近專案的資料庫為 Oracle, 部份 table 是由客戶自行設計及管理, 並沒有什麼明確的文件可供參考, 不清楚 table 之間的關聯性.
經上網查詢, 發現 Oracle SQL Developer Data Modeler 可由現行資料庫的結構, 反轉為 ER 圖的功能, 可以看出 table 的關聯性, 故演練一下, 並作成筆記.
當然, table 之間必須要建立 Primary Key, Foreign Key 的關聯, 否則轉出的 ER 圖, 其效果不大.
由於最近 C: 磁碟機的空間所剩不多, 用 Windows 10 內建的磁碟清理, 它指出 %Temp% 資料夾佔了 19.7GB, 但實際清理, 卻永遠都清不掉.
查了一下黑暗執行縮的三篇文章 (連結如參考文件), 有提到一個 WizTree 的工具, 可用以分析一下磁碟的使用狀況.
結果嚇了一跳, 居然是 66.9GB, 遠比磁碟清理呈現的佔用空間值, 足足多了3倍. 實在不清楚原因. 最近沒安裝什麼軟體, 只有作了 Windows Update, 然後有更新失敗的狀況. 但剛剛去查更新記錄, 居然只有留下成功的, 失敗的記錄通通消失了. 真的很怪異.
按理應該要寫一支 C# 程式定期清理 %Temp% 資料夾下 1 個月前的檔案及資料夾, 但還是有點擔心誤刪. 先暫緩.
另外, 發現 %UserProfile%.nuget\packages 佔了 16.4GB, 有找到 How to change default Nuget packages folder on Windows 的文章, 就來實際演練一下吧.
由於工作上會用到 ASP.NET Core 8 Web API 存取 Oracle 資料庫. 目前查到的方式有 2 種:
1.. 利用 Dapper 作為中介, 直接下 SQL 指令.
2.. 利用 Entity Framework Core 作為中介, 由其將 Entity Framework 的物件內容, 轉為 SQL 指令.
筆者已習慣採用 Entity Framework Core + MSSQL, 所以這篇就來試試 Entity Framework Core + Oracle.
撰寫完成的 Web API 總是要測試, 本文採用 Swagger/OpenAPI 的相關套件及工具, 進行測試.
內容大綱如下:
一. 環境
二. 步驟
(一) 安裝 dotnet-ef 命令列工具 至最新版
(二) 建立 Web API 專案
(三) 加入 Microsoft.EntityFrameworkCore.Tools 套件
(四) 加入 Oracle.EntityFrameworkCore 套件
(五) 建立 Oracle 資料庫, 使用者及 Table
(六) 由 Oracle 資料庫產生 DbContext 及 Models
(七) 撰寫 Web API
(八) 將程式進行優化
(九) 利用 Swashbuckle.AspNetCore 套件產生 Web API 的說明頁面
(十) 利用 NSwag.AspNetCore 套件產生 Web API 的說明頁面
(十一) 利用 NSwagStudio 工具產生用戶端的程式碼
附錄一: Oracle.EntityFranewrokCore 安裝後的提示
附錄二: EF Core Power Tools 執行完成的提示
前一篇把背景服務整合至使用者登入後的 TrayIcon 應用程式, 且確認可在使用者登入後執行. 而 ASP.NET Core 8 Web API 其實也類似一個背景服務, 想說看看是否可以作到.
試想一個情境:
想在瀏覽器的 Javascript 存取使用者的本機資源, 例如: 讀卡機, 描描器, 印表機, 本機環境設定... 等, 受限瀏覽器安全性設計, 應該很難作到. 或許可以, 但筆者不是 Javascript 專家, 想說是否有其它的路可以走. 看到 (黑暗執行緒) 使用 .NET 6 開發 Windows Service 有人詢問瀏覽器存取本機資源的問題, 黑大回覆可以參考這篇 (Microsoft) 在 Windows 服務上裝載 ASP.NET Core.
架構設計如下圖, 但不是真的去讀 ICCard, 只是作一個小的 Web API 驗證可行性.
筆者的狀況是不一定要裝載在 Windows Service, 只要是登入後執行的 Windows Form App, 且自動縮小到系統匣(System Tray) 即可.
一. 建立 ASP.NET Core 8 Web API 應用程式
(一) 建立 ASP.NET Core 8 Web API 專案
(二) 加入範例 Web API
(三) 採用 Serilog 輸出至 Console 及 File
二. 發佈前述 ASP.NET Core 8 Web API 至單一執行檔
(一) 以 VS2022 進行發佈
(二) 以 Postman 測試發佈後的執行檔
三. 加入 TrayIcon 的功能
(一) 加入 icon 圖檔
(二) 建立一個 Windows Form App 作為修訂 Web API 專案的參考
(三) 修改 .csproj
(四) 修訂其它程式
四. 實際測試
(一) TrayIcon 模式
(二) Console 模式
五. 安全性議題
(一) AllowHosts 設置
(二) CORS 設置
(三) 調整後的 Program.cs
六. 注意事項
接續前一篇 "如何在 .NET 8 建立基於 BackgroundService 的 Windows Service 應用程式 (1)" 的內容.
思考以下情境, 如果該程式是在使用者登入時, 以 Console 模式執行, 那麼在 Windows 10 的工作列上, 是否就很容易被使用者看到, 而去把它關掉. 過程可參考 [附錄一].
因此, 筆者想到以前在 Windows Form 有一個叫作 TrayIcon 或 NotifyIcon 元件或類別, 可以將應用程式以圖示的方式, 存放在工作列(Task Bar) 的通知區(Notification Area) 或系統匣(System Tray).
本文將以前述程式碼為基礎, 添加 NotifyIcon 的功能, 以使整個程式, 得以同時支援 TrayIcon / Console / Windows Service 的使用方式.
一. 開發過程
二. 發行為單一執行檔
三. 以 TrayIcon 模式執行
四. 以 Console 模式執行
五. 以 Windows Service 模式執行
附錄一: 將 JokeWorkerService 放在登入時執行
這是一個參考 (Microsoft)(中文版) 使用 BackgroundService 建立 Windows 服務 所作的演練.
如同 (黑暗執行緒) 使用 .NET 6 開發 Windows Service 所提到的, 可以同時支援 Console 及 Service 這 2 種執行模式真的很不錯. 不然以往都要切 3 個 C# 專案: 核心 Library, Console, Windows Service.
以下為章節列表.
一. 開發過程
二. 採用 Serilog 輸出至 Console 及 File
三. 以 Console 模式執行
四. 以 Windows Service 模式執行
由於最近工作上會用到 Oracle, 想說以前用過 11g, 應該很容易入門才對; 但發現在第一關的建立使用者就踼到鐵板, 如下面指令及輸出結果.
CREATE USER JASPER IDENTIFIED BY Test1234;
-- 執行結果:
-- ORA-65096: common user or role name must start with prefix C##
查了一下, 才發現自 Oracle 12c 起導入了所謂的 Multitenant Environment 多租用戶環境觀念, 允許一個 Container Database (CDB) 承載多個 Pluggable Database (PDB).
章節如下:
一. 建立一個 Oracle 23c Free 的 Docker Container
二. 以 11g 的方式, 建立使用者失敗
三. 連入 CDB, 建立 Common User Account
四. 連入 PDB, 建立屬於該 PDB 的 Local User Account
五. 以前述建立的 Local User Account, 建立 Table
筆者在前兩篇有針對 "ASP.NET MVC 及 ASP.NET Core MVC 的錯誤處理" 作了描述. 對於錯誤處理(Error Handling) 作了以下定義: 係指錯誤取得 (Catch), 訊息規格 (Specification), 呈現 (Presentation), 及記錄 (Logging).
前兩篇涵蓋了 "錯誤取得" 及 "訊息規格", 尚餘 "呈現" 及 "記錄".
需視需求而定. 由於對前端不是很專長, 這裡就先藏拙不表.
本文主要著重於此. 由於很多人推薦 Serilog, 所以, 就以此作為演練的對象. 一般而言, 記錄會包含以下幾個面向:
本文將以前述 "ASP.NET Core MVC Error Handling 摘要版" 的程式為基底, 繼續往下增修內容.
章節內容如下:
一. 內建 Logger 的功能
二. 加入 Serilog 相關套件
三. 輸出至 Console 及 File 入門
四. 利用 UseSerilogRequestLogging middleware 記錄 Http Request 內容
五. 自訂輸出格式
六. 輸出至 Seq Logging 服務入門
七. 輸出至 MSSQL 資料庫入門
(一) 套件安裝
(二) 由 Serilog.Sinks.MSSqlServer 決定預設的欄位及資料型態 (by appsettings.json)
(三) Serilog.Sinks.MSSqlServer 欄位種類概述
(四) 自訂 Serilog.Sinks.MSSqlServer 的欄位及資料型態 (by Program.cs)
(五) 自訂 Serilog.Sinks.MSSqlServer 的欄位及資料型態 (for ProblemDetails by Program.cs)
(六) 改用自定義的統一輸出格式 (MyProblemDetails)
(七) 建立一層 LoggingService 打包 ILogger, 以利寫入資料庫欄位
八. 關於 Serilog 的增強器 (Enrichers)
範例存放於 GitHub, 有興趣的朋友, 可自行下載參考.
這篇係針對前一篇文章, 摘錄筆者認為在 ASP.NET Core 8 MVC 框架下的適宜作法.
這篇不作太多的文字說明, 主要是描述實作程序, 及相關程式碼.
有效的錯誤處理, 對於確保應用程式的穩定性和用戶體驗, 是非常重要的; 若系統沒有作好錯誤處理, 而呈現程式錯誤細節給使用者, 代表系統不穩定, 且用戶體驗會非常糟糕.
若您覺得這篇文章對您有幫助, 請不吝於在筆者的 GitHub Repository (可在 Repository 下載範例程式) 上按星星, 謝謝.
如果只關心 ASP.NET Core MVC 的實作程序及程式碼, 可以直接看筆者的另一篇文章: ASP.NET Core MVC Error Handling 摘要版 .
1.. 錯誤(Error): 係指框架 (ASP.NET 或 ASP.NET Core), 或應用程式自定義的例外 (Exception). 本文會說明如何將未通過資料檢核的錯誤, 包裝為自定義用戶端例外拋出. 以提供一致性的錯誤訊息規格.
2.. 錯誤處理(Error Handling): 係指錯誤取得 (Catch), 訊息規格 (Specification), 呈現 (Presentation), 及記錄 (Logging). 本文主要著重在錯誤取得及一致性錯誤訊息規格制訂.
ASP.NET Core 提供了中介軟體 (Middleware) 的機制, 讓開發人員可以在整個 HTTP Request / Response 的過程中, 進行例外的攔截.
MVC 框架本身 (含 ASP.NET MVC 及 ASP.NET Core MVC) 提供了例外過濾器 (Exception Filter) 的機制, 讓開發人員在 HTTP 訊息進入 MVC 的生命週後, 進行例外的攔截.
理解 (Microsoft Learn) Filters in ASP.NET Core 的 2 張圖, 對開發人員而言, 是非常重要的.
若要完全處理整個 Web 應用程式的例外, 實作方面的相關配套如下:
1.. ASP.NET MVC: 要搭配 Web.config 或 Global.asax + 自定義的 ErrorController.
2.. ASP.NET Core MVC: 可以自行撰寫 ASP.NET Core 的例外處理中介軟體 (Middleware).
說明: Middleware 是屬於 ASP.NET Core, 不是 ASP.NET Core MVC; ASP.NET Core MVC 是建置在 ASP.NET Core 上的一個框架.
3.. ASP.NET Core 8 以後提供了實作 IExceptionHandler 介面的方式, 簡化例外處理 Middleware 的撰寫, 內建的 app.UseExceptionHandler(), 其實也是一佪 Middleware, 會使用前述的類別, 攔截例外. 只是筆者能力有限, 目前遇到無法取得 routeData (ex: controller, action 名稱) 的問題, 雖然本文還是有提供範例, 但暫不推薦此方式.
回傳一致性的錯誤訊息, 對於系統的開發及對用戶體驗, 是非常有幫助的.
1.. ASP.NET MVC: 只能自定義錯誤訊息類別.
2.. ASP.NET Core MVC: 可採用自定義錯誤訊息類別, 或內建的 ProblemDetails 類別.
說明: ASP.NET Core 2.1 起, 有一個依 IETF >RFC7807 規範 設計的 ProblemDetails 類別, 用以統一回傳結果. 但也可視需求, 自行定義統一的回傳類別.
說明: 本文採自定義的 ErrorViewModel 類別作為回傳格式, 作為說明之用. 但最後仍補上採用 ProblemDetails 類別的範例.
伺服端程式必須進行資料檢核, 才能去存取資料庫. 若資料檢核發現有誤, 代表用戶端沒有作好資料檢核的工作, 或者被瀏覽器的 F12 破解, 因此屬於用戶端的問題 (HTTP 4XX).
這類的錯誤, 需設計繼承自 Exception 類別的自定義例外類別, 當發生未通過檢核時, 打包為自訂例外拋出, 由前述的 Middleware 或 Exception Filter 攔截及處理.
上述的文字內容的思路, 可參考結論的流程圖.
本文將探討 ASP.NET MVC 及 ASP.NET Core MVC 中一些錯誤處理實作技巧.
一. 預設的錯誤處理方式
二. 自定義統一的回傳的錯誤訊息規格
三. 自定義 Middleware, 用以產生貫穿 Request 軌跡的 TraceId
四. 撰寫 自定義例外 (Custom Exception), 供後續 Middleware 或 Filter 使用
五. 自定義 Middleware 攔截例外 (ASP.NET Core)
六. 建立 Exception Filter (ASP.NET MVC or ASP.NET Core MVC)
七. 實作 IExceptionHandler (ASP.NET Core 8 and later)
八. 建立另一個 MVC 專案, 參考前述的例外處理專案
目前 GitHub 上的範例版本為最後一版, 請下載參考. 輸出結果, 若發現回傳值有 JSON 欄位名稱字首大小寫的差異 (例如: TraceId vs. traceId), 或者有增加欄位 (例如: ControllerName, ActionName), 請再自行參酌程式碼. 前者是因為在輸出 JSON 時, 有對 System.Text.Json 作了一些選項的設定; 後者是因為要寫 Log 時, 需要該欄位.
How to write Custom Attribute with DI in ASP.NET Core 6 MVC
由於 ASP.NET Core 6 MVC 專案採用 DI (Dependency Injection) 的方式, 有一些相關的 自訂屬性 (Custom Attribute) 也想採用 DI.
原本程式碼是在 MyLogAttribute 裡面自行 new Logger(), 在套用屬性時, 是用 [MyLogAttribute]; 改採 DI 後, 變成建構子要傳入 ILogger 的參數, 在 HomeController 的 Index() method, 要改成以下的方式, 但編譯會出現 CS0181 及 CS0120 的編譯錯誤.
[MyLogAttribute(_logger)]
public IActionResult Index() {
return View();
}
參考文件1.. 為 CS0181 的說明, 它提到自訂屬性傳入的參數, 不可以是物件變數, 必須為常數值.
本文主要採 參考文件2.. 的方法2 (ServiceFilter) 進行演練及實作.
Unit Test for void method (Serilog package) in ASP.NET Core 6 MVC
接續前一篇 樂透開獎(含日期限制)(含主辦人宣佈啟動開獎) 的例子, 假設有一個新的需求: "需要將開獎的各次號碼及結果寫入Log記錄檔, 以供後續稽核".
雖然 ASP.NET Core 有提供一個 ILogger 的實作, 但功能有限. (參考文件4..)
一般會採用 Serilog 套件, 但其相關的 Log method (例如: LogTrace, LogDebug ... 等), 都沒有回傳值 (void), 無法以回傳值模擬其結果, 那應該要如何建立測試呢?
關於 Serilog 的部份, 主要採 參考文件1..及2.. 方式進行演練及實作.
Unit Test for Static Elements (System.IO.File.ReadAllText) in ASP.NET Core 6 MVC
接續前一篇 樂透開獎(含日期限制) 的例子, 假設有一個新的需求: "樂透開奬有一個前置作業, 必須由主辦人員按下[開始]按鈕, 才能開獎".
本文假設主辦人員按下[開始]按鈕, 會在主機端產生一個檔案 (Extras/startup.txt), 內含主辦人員的姓名.
因此, 程式要增加一個讀取檔案內容的動作.
這裡很單純的想法, 是用 File.ReadAllText() 的方法, 因為是 static class + static method, 應該要如何建立測試呢?
以下係採 參考文件1..及2.. 方式進行演練及實作.
Unit Test for Static Elements (DateTime.Now) in ASP.NET Core 6 MVC
接續前一篇 樂透開獎 的例子, 假設有一個新的需求: "樂透開奬不是每天開, 而是固定每個月的 5 日才會開獎".
因此, 程式要加一個當前日期時間的判斷.
以下係採 參考文件2.. "An interface that wraps the DateTime.Now" 方式進行演練及實作.
Unit Test for Non-Deterministic Elements (Random class) in ASP.NET Core 6 MVC
非決定性元素 (Non-Deterministic Elements) 是指在軟體開發中, 其行為或輸出無法預先確定或不會每次都產生相同結果的元素.
這種不確定性通常是由於外部因素, 隨機性, 系統狀態或執行環境的變化所引起.
非決定性元素在測試時可能帶來挑戰, 因為相同的輸入不一定導致相同的輸出.
以下是一些常見的非決定性元素範例:
在單元測試中處理非決定性元素時, 一個常用的策略是通過封裝 (Wrapping) 這些元素於可控的介面後, 使用模擬或替身物件 (Test Doubles) 來提供可預測的輸出. 這樣可以減少測試的不確定性, 並提高測試的可靠性和重複性.
以下茲以一個 ASP.NET Core 6 MVC 的專案, 以 Random 類別為例, 進行演練.