Skip to content
Tutorials Center
My learning

Topics

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.

C#
using System.Collections.Frozen;

FrozenSet<string> days = new[] { "Sat", "Sun" }.ToFrozenSet();
bool weekend = days.Contains("Sun");   // true

Try it

C# A read-only lookup table

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.

C# Sets and custom comparers

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

C#
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 a static readonly field.
  • 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: ToFrozenDictionary with a KeyValuePair source keeps the last value for a repeated key, while the overload with key and element selectors throws ArgumentException (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. ImmutableDictionary is built for cheap "modified copies"; frozen ones cannot produce modified copies at all, they only optimise reads.
  • Availability: .NET 8 or later.