frozendictionary 在 .net 8+ 中真实存在，但必须满足三个硬性条件：目标框架 ≥ net8.0、显式引用 system.collections.frozen 包、且命名空间 using system.collections.frozen; 不可省略。
FrozenDictionary 在 .NET 8+ 中真实存在，但必须满足三个硬性条件：目标框架 ≥ net8.0、显式引用 System.Collections.Frozen 包、且命名空间 using System.Collections.Frozen; 不可省略。缺一即报 “type not found” 错误，这不是配置问题，而是环境不达标。
为什么编译报错 “The type or namespace name 'FrozenDictionary' could not be found”
这个错误几乎总是由以下任一原因导致：
- 项目
<targetframework></targetframework>仍是net6.0或net7.0—— 必须升级到net8.0或更高（如net9.0） - 未安装
System.Collections.FrozenNuGet 包：.NET 8 SDK 默认包含该包，但旧项目迁移时可能缺失；检查.csproj是否有<packagereference include="System.Collections.Frozen" version="8.0.1"></packagereference> - 只写了
using System.Collections;或漏写命名空间——必须完整写using System.Collections.Frozen; - 试图从
ImmutableDictionary调用.ToFrozenDictionary()—— 它没有这个扩展方法；FrozenDictionary是独立类型，不与Immutable*体系互通
创建 FrozenDictionary 的三种方式及性能差异
它没有公共构造函数，所有初始化都必须通过静态工厂或扩展方法完成。不同方式影响构建阶段的 CPU 和内存开销：
-
FrozenDictionary.Create<string int>(new[] { new KeyValuePair<string int>("a", 1), new KeyValuePair<string int>("b", 2) })</string></string></string>：最快。跳过排序和去重逻辑，直接构建哈希表；适用于已知键唯一、顺序无关的预定义数据（如枚举映射数组） -
dict.ToFrozenDictionary()（dict是Dictionary<string int></string>或任意IEnumerable<keyvaluepair ...>></keyvaluepair>）：自动去重（保留最后一次出现的值）、按键排序后再建表；适合从配置源动态加载后冻结的场景 -
var b = FrozenDictionary.CreateBuilder<string int>(); b.Add("x", 10); b.Add("y", 20); var frozen = b.ToFrozenDictionary();</string>：支持运行时条件判断填充，但 builder 内部仍为可变结构；仅推荐用于初始化逻辑复杂、无法一次性构造IEnumerable的情况
FrozenDictionary 查找时的常见陷阱
它实现了 IDictionary<tkey tvalue></tkey>，但语义和行为与普通字典有关键区别：
- 支持
dict["key"]索引访问，平均 O(1)，底层是紧凑哈希表，无虚调用、无装箱 - **不支持
dict.ContainsKey("key")的非泛型重载** —— 即IDictionary.Contains(object)显式实现会抛NotSupportedException；必须改用dict.TryGetValue("key", out var v)或dict.ContainsKey<string>("key")</string>（泛型版本） - 所有修改操作（
Add、Remove、索引器赋值、Clear）均抛NotSupportedException，这是设计使然，不是 bug - 重复键处理策略是“保留最后一次”，而非抛异常；若你依赖“首次出现优先”，需在传入前自行去重
比 ImmutableDictionary 快在哪？关键看内存布局
性能优势不是抽象概念，而是三点具体落地：
-
零写时复制：
ImmutableDictionary每次SetItem都返回新实例，产生 GC 压力；FrozenDictionary根本不提供修改 API，哈希表一次构建、永久固化 - 紧凑内存布局：无树节点/trie 分支指针，只有键数组、值数组、哈希桶索引三块连续内存；缓存局部性好，CPU 预取效率高
-
内联查找路径：JIT 可将
dict["key"]编译为近乎原生数组访问的指令序列，跳过接口虚分发和防御性拷贝
真正容易被忽略的是：FrozenDictionary 的高性能只在「构建后永不修改」的前提下成立。一旦你试图绕过限制（比如反射写字段、unsafe 指针篡改），不仅破坏线程安全，还会让所有优化失效 —— 它不是靠运行时防护，而是靠编译期和设计期的不可变契约。
