C#中Frozen Dictionary的用法_C# .NET 8高性能只读字典教程【最新】-C#.Net教程-PHP中文网

frozendictionary 是 .net 8 引入的高性能只读字典，需目标框架 ≥.net 8、引用 system.collections.frozen 命名空间，仅能通过 tofrozendictionary() 创建；支持 o(1) 索引查找与线程安全读取，但所有修改操作抛 notsupportedexception，且不支持 idictionary.contains(object) 等非泛型方法。

c#中frozen dictionary的用法_c# .net 8高性能只读字典教程【最新】

FrozenDictionary 是 .NET 8 中正式引入的高性能只读字典类型，位于 System.Collections.Frozen 命名空间，不是第三方封装，也不是误传的 ImmutableDictionary.ToImmutable()。它专为构建后永不修改、内存布局固化、零分配查找设计，比 ImmutableDictionary 查找快约 30–50%，GC 压力几乎为零。

如何正确引用和创建 `FrozenDictionary`

必须确保项目目标框架为 .NET 8 或更高（如 .NET 9），且已安装 System.Collections.Frozen 包（.NET 8 SDK 默认包含，但旧项目可能需显式添加）：

若使用 dotnet new 创建的 .NET 8+ 项目，无需额外 NuGet 引用；否则在 .csproj 中确认存在：
```
<packagereference include="System.Collections.Frozen" version="8.0.0"></packagereference>
```
命名空间必须显式引入：using System.Collections.Frozen;
不能直接 new FrozenDictionary<string int>()</string> —— 它没有公共构造函数，只能通过静态工厂方法创建
推荐方式是调用扩展方法 ToFrozenDictionary()，它接受任意 IEnumerable<keyvaluepair tvalue>></keyvaluepair>

示例：

var dict = new Dictionary<string int>
{
    ["apple"] = 1,
    ["banana"] = 2,
    ["cherry"] = 3
}.ToFrozenDictionary(); // ✅ 正确</string>

错误写法（编译失败）：

var bad = new FrozenDictionary<string int>(); // ❌ no public ctor
var alsoBad = dict.ToImmutable(); // ❌ 返回的是 ImmutableDictionary，不是 FrozenDictionary</string>

`FrozenDictionary` 的查找行为与常见陷阱

它实现了 IDictionary<tkey tvalue></tkey>，但所有修改方法（Add、Remove、索引器赋值等）都会抛出 NotSupportedException，这是设计使然，不是 bug。

支持 dict["key"] 直接索引访问，O(1) 平均时间复杂度（底层是优化哈希表，非二分）
不支持 dict.ContainsKey("key") 的 IDictionary.Contains(object) 重载 —— 因为该方法签名要求 object，而 FrozenDictionary 显式实现该接口时会 throw NotSupportedException；应改用泛型安全的 dict.TryGetValue("key", out var v)
重复键处理：若源数据含重复 Key，ToFrozenDictionary() 会保留序列中**最后一次出现的值**（不同于 ToDictionary() 抛异常）
线程安全：读操作完全无锁，可被任意数量线程并发访问，无需额外同步

典型误用：

"避开 C# 常见错误——空陷阱、异步陷阱、LINQ 陷阱及资源泄漏。"

下载

if (dict.Contains("apple")) { ... } // ❌ 编译通过但运行时 NotSupportedException
if (dict.ContainsKey("apple")) { ... } // ❌ 同上（IDictionary.ContainsKey 是 object 版本）
if (dict.TryGetValue("apple", out int val)) { ... } // ✅ 正确且高效

性能关键：何时用 `FrozenDictionary`，何时换方案？

它不是万能替代品。适用场景非常明确：**一次性构建 + 高频只读查找 + 键集稳定**（如配置映射、HTTP 状态码描述、枚举名称缓存）。但要注意以下边界：

初始化开销略高：构建过程会做哈希表预分配 + 冲突探测优化，10 万条目耗时约 0.5–2ms，远高于 Dictionary 构造，但只发生一次
内存占用比 Dictionary 高约 10–15%，但比 ImmutableDictionary 低 30%+；底层无树节点/链表指针，纯数组 + 开放寻址
不支持自定义 IEqualityComparer<tkey></tkey> 的运行时传入（ToFrozenDictionary(..., comparer) 是允许的，但一旦冻结，comparer 即固化，无法后期替换）
若键类型是自定义 class 且未重写 GetHashCode/Equals，或使用引用相等语义，务必传入对应 IEqualityComparer，否则行为不可控
极小集合（ReadOnlySpan> + 线性查找反而更快，FrozenDictionary 的哈希开销反而成负优化

一句话判断：如果你正在写 private static readonly 字典字段，且初始化后从不修改，FrozenDictionary 就是当前 .NET 8+ 下最优解。

兼容性与版本依赖必须看清

FrozenDictionary 不是 .NET Standard 兼容类型，它**仅存在于 .NET 8 及以上原生运行时**。这意味着：

目标框架为 net6.0 或 net7.0 的项目无法使用 —— 即使手动引用 System.Collections.Frozen 8.x 包，运行时也会因类型缺失而报 TypeLoadException
net8.0-windows、net8.0-android 等具体 TFM 均支持，无平台限制
ASP.NET Core 8+、MAUI 8+、Blazor WebAssembly 8+ 均可直接用，但需确认发布时未降级目标框架
不要在共享库（如 netstandard2.0）中暴露 FrozenDictionary 类型，否则下游 .NET 6 项目引用即崩