csharp-language-featureslisted

# C# Framework Context 與語言特性 ## Framework Awareness 修改 C# 程式碼前先判斷目標框架與語言版本： - **Legacy .NET Framework**：若為 .NET Framework，例如 v4.7.2，語法上限為 C# 7.3，不使用 C# 8.0 以上特性，例如 `using var`、`switch` 運算式、Records 與 Nullable Reference Types。 - **Modern .NET**：Core、5+ 或更新版本可使用相容的現代 C# 特性。依賴注入使用傳統建構函式，不使用 Primary Constructors。 ## Async / Await - 非同步方法回傳 `Task` 或 `Task<T>`，`async void` 僅用於事件處理函式。 - Library 專��的非同步呼叫加上 `.ConfigureAwait(false)`。 - 避免 Sync-over-Async。同步介面必須呼叫非同步邏輯時，視情況使用 `.GetAwaiter().GetResult()`，不使用 `.Result` 或 `.Wait()`。 - 方法只轉發另一個 Task 結果時，直接回傳該 Task，例如 `return DoSomethingAsync();`，不增加多餘的 `async` / `await` 狀態機。 - 回傳 Task 且未宣告 `async` 的方法，以 `Task.FromException()` 傳遞例外，不使用 `throw`。 ## Object Creation 與 Var - 只在 C# 版本支援時使用 Target-typed `new`，例如 `Type x = new();`。 - `var` 使用以 `.editorconfig` 為準。沒有相關設定時原則上禁用，只在匿名型別或極度複雜的巢狀泛型中使用。 ## Types 與 Memory - 字串比較明確指定比較規則，例如 `StringComparison.OrdinalIgnoreCase`。 - 時間型別遵循專案既有慣例。專案統一使用 `DateTime` 時維持該型別，統一使用 `DateTimeOffset` 時維持該型別。新建程式碼沒有既有慣例時優先使用 `DateTimeOffset`。 - 同一專案內的 `DateTime` 不混用 `Local`、`Utc` 與 `Unspecified`。 - 空字串使用空字串文字，不使用 `string.Empty`。 ## Collection Type Selection 依語意選擇最窄的集合介面，不預設使用 `List<T>`： | 介面 | 能力 | 適用情境 | | --- | --- | --- | | `IEnumerable<T>` | 迭代 | 方法參數、只需走訪的回傳值 | | `IReadOnlyCollection<T>` | 迭代 + Count | 需要數量但無需索引存取 | | `IReadOnlyList<T>` | 迭代 + Count + 索引 | DTO 屬性、唯讀回傳值 | | `ICollection<T>` | 迭代 + Count + Add/Remove | 可修改但不需索引的集合 | | `IList<T>` | 迭代 + Count + 索引 + Add/Remove | 可修改且需索引的集合 | | `List<T>` | 具