Dictionary<TKey, TValue> 是 .NET 最常用的泛型關聯式集合，提供 O(1) 平均查找效能。本文以 Dictionary<int, string> 為例，系統整理建立、新增、查詢、遍歷、移除等 7 種核心操作，並補充效能與執行緒安全考量。
using System.Collections.Generic;
var dict = new Dictionary<int, string>();dict.Add(1, "C#");
dict.Add(2, "C++");
dict.Add(3, "ASP.NET Core");
dict.Add(4, "Blazor");注意：Key 不可重複，重複呼叫 Add 會拋出 ArgumentException。若不確定 Key 是否存在，建議用 TryAdd (.NET 6+) 或先檢查 ContainsKey。
// 直接存取：Key 不存在會拋 KeyNotFoundException
string lang = dict[1];
// 安全取值：推薦用法
if (dict.TryGetValue(1, out string value))
Console.WriteLine($"Key=1, Value={value}");
// 僅檢查存在性
bool exists = dict.ContainsKey(1);foreach (KeyValuePair<int, string> kvp in dict)
Console.WriteLine($"Key = {kvp.Key}, Value = {kvp.Value}");foreach (int key in dict.Keys)
Console.WriteLine($"Key = {key}");foreach (string val in dict.Values)
Console.WriteLine($"Value = {val}");dict.Remove(1); // 回傳 bool 表示是否成功移除
// 移除後再查詢
if (!dict.ContainsKey(1))
Console.WriteLine("Key 1 已不存在");dict.Clear(); // 移除所有項目，Count 歸零，容量不變| 成員 | 說明 |
|---|---|
Count | 目前鍵值對數量 |
Keys / Values | 取得鍵/值集合（動態視圖） |
this[key] | 索引器：讀寫指定鍵的值 |
Add(key, value) | 新增，鍵重複拋例外 |
TryAdd(key, value) | .NET 6+，鍵不存在才新增，回傳 bool |
Remove(key) | 移除指定鍵，回傳 bool |
ContainsKey(key) | 檢查鍵是否存在 |
ContainsValue(value) | 檢查值是否存在（O(n)） |
TryGetValue(key, out value) | 嘗試取值，不拋例外，效能最佳 |
GetEnumerator() | 傳回列舉器，支援 foreach |
預設使用 EqualityComparer<TKey>.Default（參考相等或實作 IEquatable<T>）。若需忽略大小寫字串鍵：
var ciDict = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);capacity 避免多次擴容：new Dictionary<int, string>(10000)。FrozenDictionary (.NET 8+) 唯讀高效能查找。Dictionary 非執行緒安全。多執行緒讀寫請改用：
ConcurrentDictionary<TKey, TValue>（無鎖高併發）lock / ReaderWriterLockSlim 保護JSON 序列化時，Dictionary 會輸出為物件 `{ "1": "C#", "2": "C++" }`，Key 會轉為字串。若需保留型別，請自行轉為 List<KeyValuePair<TKey, TValue>>。
熟練掌握上述 7 大核心操作與進階技巧，即能在高效能、型別安全的前提下，靈活運用 Dictionary 解決各類鍵值對應場景。
