Simple Is Not Easy

在開發 C# 專案時，我們經常使用 XML 文件註解 來為型別或成員寫說明，這類型的註解除了可以提高維護性外，也可以透過工具自動轉化成 API 文件。

但是註解也是需要維護的，在多載方法的註解經常面臨一個問題就是一群多載方法通常有著相似的註解，維護時需要一個一個修改其實很容易使得最後不同多載間的註解有著許多細微的不一致。另一方面這樣也讓維護註解變得更麻煩瑣碎。

XML 文件註解 官方文件很詳細，這篇文章不詳細說明這些內容，而會聚焦在重用註解的方式。

關於 EF Core 中的值轉換 (Value Conversion)，官方文件已經展示的非常詳細，但這樣的實作使得值轉換和 DbContext 高度相依，在中小型專案中這樣已經足夠，但在複雜的產品群中，如果需要基於 EF Core 建立內部共用的套件，就會難以將這些客製化的 ValueConverter 從套件中抽離，也難以讓應用程式自行擴充自己特殊的 ValueConverter，本文主要提供另外一個面向的實作來達到更低的耦合度與更高的可擴充性。

問題起始於一個情境如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

switch (cryptoType)
{
    case CryptoType.AesEncrypt:
        var key = "";
        var iv = "";
        break;
    case CryptoType.AesDecrypt:
        var key = "";
        var iv = "";
        break;
	// Others
    default:
        break;
}

這時候因為 case 之間的區域變數名字重複了所以編譯不會通過。

現實情境更複雜，CryptoType 可能有幾十個。

這邊要先聲明，理論上這種大量的 switch-case 有很多設計可以管理它，但實務上是一個老舊又缺乏架構的專案，甚至亂到重構後的檔案放哪都只會更亂的程度，而如果只是抽出方法，那一些簡單的情境就會因此被抽出大量小型方法，且都放在同一個類別中也不會比較好。

總之，這個例子只是拿來說明區域變數與其作用域和生命週期，不表示例子中的設計是恰當的。

在我以往的工作經驗中，處理過不少 WebAPI 的維護工作，普遍面臨的一個問題是回傳資料的不一致性。舉例來說，常見的幾種回傳格式包括：

1. 純值： true、100 等，會出現在回傳單一值的 API 中。
2. 物件： {"name": "Ron", "gender": "Male"}，會出現在回傳物件的 API 中。
3. 物件含狀態： {"status": "1001", "name": "Ron", "gender": "Male"}，會出現在呼叫端需要知道更多狀態細節時。
4. 其他變種：除了資料外還有各種狀態、錯誤、訊息等欄位，但格式與名稱不統一。

這個現象造成的問題就是明明是同一個站台對外提供服務，回傳的狀態訊息卻每個 API 都不一樣，不僅對使用者不友善，也會讓接手維護的人無所適從。

本篇文章會介紹並分析的幾種解決方案，所有方案都有高一致性與關注點分離的共同優點，但也有些不同的缺點。

.NET 編譯器平台 (Roslyn) 分析器 提供很多有用的程式碼分析規則讓我們更容易維持良好的程式碼品質，但有時候我們會需要自己定義一些規則來符合專案開發規範。官方以及其他網路文章其實已經提供了不少資訊，但因為步驟和說明真的很多，了解起來太花時間，於是想自己來整理一下讓需要的人可以快速走完所有步驟。

在資料庫操作時，面對多個操作的並行操作，為了避免資料不一致和衝突我們主要有兩種方法可以達成這個目標：樂觀鎖 (Optimistic Lock) 和悲觀鎖 (Pessimistic Lock)。但我們應該如何選擇適合的方法呢？

樂觀鎖和悲觀鎖的實作網路資源太多了，這篇不會特別提。

Dictionary<TKey, TValue> 是很常用的資料結構，我們可以使用索引子 (Indexer) 透過特定的 Key 來存取資料。 但使用時，我們要特別注意 Key 的型別，使用值型別作為 Key 通常不會有問題，但當使用參考型別作為 Key 時就不一定了。

在 C# 中，partial class 可以讓開發者把一個類別分散到多個檔案中。當程式編譯時，這些分散的部分會被合併成一個單一的類別。這篇會根據以往經驗來紀錄一下使用建議。

在開發過程中，我們經常需要透過 ORM　(我是使用 EF Core) 從資料庫中取得資訊，在查詢很複雜的時候我通常都會盡量透過一個查詢就把資料準備好，並轉換成巢狀的資料結構以便於應用程式進行操作，這樣可以避免多次查詢造成的效能風險。　　

但前陣子在開發過程檢查 ORM 產生的 SQL 時意外發現我的認知不一定是對的。

Reference Source 是一個非常方便的資源可以用來查看 .NET Framework 的程式碼，而這個網站是利用 SourceBrowser 所建立的。

對於我們自己開發的專案，雖然都有原始碼好像用不到這個工具，但很多時候想快速查看程式碼卻又不想耗費資源在執行 IDE 上的時候(尤其同時維護多專案的時候)，這個工具能提供一個不錯的介面來使用。

官方提供了基本的使用教學，但要開 Visual Studio 來編譯 SourceBrowser 專案，比較不方便，所以這邊會使用官方也有提供的 NuGet Package 來做，稍微紀錄一下過程，讓之後需要的時候能更快的使用。