C# Reference ยท Collections
FrozenDictionary and FrozenSet
Reference for C# FrozenDictionary and FrozenSet: build once with ToFrozenDictionary or ToFrozenSet, then enjoy faster lookups. Rules, costs and when to use them.
FrozenDictionary<TKey,TValue> and FrozenSet<T> (namespace System.Collections.Frozen, added in .NET 8) are immutable collections tuned for one pattern: build them once, usually at startup, then read them many times. When you create one, the runtime studies your keys and picks a specialised lookup strategy, which makes TryGetValue, ContainsKey and Contains faster than the same call on a Dictionary or HashSet.
The price is paid at creation: building a frozen collection is slower and allocates more than copying into a normal one. Use them for lookup tables, reserved-word sets, configuration maps and caches that never change.
using System.Collections.Frozen; FrozenSet<string> days = new[] { "Sat", "Sun" }.ToFrozenSet(); bool weekend = days.Contains("Sun"); // true
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public static FrozenDictionary<TKey, TValue> ToFrozenDictionary<TKey, TValue>( this IEnumerable<KeyValuePair<TKey, TValue>> source, IEqualityComparer<TKey>? comparer = null) where TKey : notnull; public static FrozenDictionary<TKey, TValue> ToFrozenDictionary<TSource, TKey, TValue>( this IEnumerable<TSource> source, Func<TSource, TKey> keySelector, Func<TSource, TValue> elementSelector, IEqualityComparer<TKey>? comparer = null) where TKey : notnull; public static FrozenSet<T> ToFrozenSet<T>( this IEnumerable<T> source, IEqualityComparer<T>? comparer = null);
| Name | Description |
|---|---|
source |
The data to copy into the frozen collection. |
keySelector, elementSelector |
Select the key and value from each source item. |
comparer |
Equality comparer for keys. StringComparer.OrdinalIgnoreCase is a common choice; the best optimisations apply to string keys with an ordinal comparer. |
Returns: a FrozenDictionary<TKey,TValue> or FrozenSet<T>. FrozenDictionary.Empty and FrozenSet<T>.Empty provide shared empty instances. Reading members include Count, Keys, Values, ContainsKey, TryGetValue, the indexer, Contains, and GetAlternateLookup for span-based string lookup in recent .NET versions.
Errors: a KeyNotFoundException for a missing key in the indexer. Writing through IDictionary, ICollection<T> or ISet<T> throws NotSupportedException. Null keys are not allowed.
Usage notes
- Build once. Creating a frozen collection costs noticeably more than a
Dictionary, so converting inside a hot loop is a mistake. Store the result in astatic readonlyfield. - Faster reads, not faster everything. The gain is usually modest for small collections and larger for big ones or string keys; measure with a benchmark before deciding it matters.
- Duplicates:
ToFrozenDictionarywith aKeyValuePairsource keeps the last value for a repeated key, while the overload with key and element selectors throwsArgumentException(both shown above). - Enumeration order is unspecified. Do not rely on the order of keys; sort when you need a stable result.
- Immutable, but not a snapshot of values. If the values are mutable objects, they can still change.
- Different from immutable collections.
ImmutableDictionaryis built for cheap "modified copies"; frozen ones cannot produce modified copies at all, they only optimise reads. - Availability: .NET 8 or later.