Collection Expressions & Frozen Collections in C# .NET

Imagine you're building a high-traffic e-commerce API that serves product categories to thousands of clients per second. Every request reads a static list of categories. If you recreate that list on every request, you waste CPU and memory. Worse, if the list is accidentally modified, you might serve inconsistent data. This is where collection expressions and frozen collections shine. Collection expressions let you write cleaner, more expressive code when creating collections. Frozen collections take immutability to the next level: they are read-only and optimized for lightning-fast lookups. In this article, you'll learn how to use both features effectively, avoid common pitfalls, and apply them in production scenarios. We'll start with the basics, then dive into real-world examples, debugging techniques, and even a production incident story that highlights the cost of ignoring immutability.

What Are Collection Expressions?

Collection expressions are a new syntax introduced in C# 12 that allow you to create and initialize collections in a more concise and readable way. Instead of using constructors or Add methods, you can use square brackets [] to define the elements. For example, a list of integers can be created as List<int> numbers = [1, 2, 3];. This syntax works for arrays, spans, lists, and other collection types. It also supports spread operator .. to combine collections: int[] combined = [.. first, .. second];. This reduces boilerplate and makes code more declarative. Under the hood, the compiler translates these expressions into efficient code, often using collection initializers or array literals. Collection expressions are especially useful when you need to create a collection inline, such as passing arguments to a method or defining a constant set of values.

using System;
using System.Collections.Generic;

var list = new List<int> { 1, 2, 3 }; // old way
List<int> list2 = [1, 2, 3]; // collection expression

int[] array = [1, 2, 3];
Span<int> span = [1, 2, 3];

// Spread operator
int[] more = [.. array, 4, 5];
Console.WriteLine(string.Join(", ", more)); // 1, 2, 3, 4, 5

// Inline usage
ProcessIds([10, 20, 30]);

static void ProcessIds(List<int> ids) { /* ... */ }

Understanding Frozen Collections

Frozen collections, introduced in .NET 8, are immutable collections that are optimized for fast read operations. They are part of the System.Collections.Frozen namespace. The two main types are FrozenSet<T> and FrozenDictionary<TKey, TValue>. Once created, you cannot add, remove, or modify elements. The 'frozen' name implies that the internal data structure is optimized for lookup, often using hash tables or other structures that are built once and never changed. This makes them ideal for scenarios where you have a fixed set of data that is read frequently, such as configuration settings, lookup tables, or static caches. Creating a frozen collection is done via extension methods .ToFrozenSet() or .ToFrozenDictionary() on existing collections. The creation process can be expensive (O(n) time and memory), but subsequent lookups are extremely fast (O(1) average). Frozen collections are also thread-safe because they are immutable.

using System;
using System.Collections.Frozen;
using System.Collections.Generic;

var set = new HashSet<int> { 1, 2, 3 };
FrozenSet<int> frozenSet = set.ToFrozenSet();

var dict = new Dictionary<string, int> { { "one", 1 }, { "two", 2 } };
FrozenDictionary<string, int> frozenDict = dict.ToFrozenDictionary();

// Lookups are fast
Console.WriteLine(frozenSet.Contains(2)); // True
Console.WriteLine(frozenDict["one"]); // 1

// The original collection can still be modified; frozen copy is independent
set.Add(4);
Console.WriteLine(frozenSet.Count); // 3 (unchanged)

Combining Collection Expressions with Frozen Collections

You can combine collection expressions with frozen collections to write clean, efficient code. For example, you can create a frozen set directly using a collection expression and then call ToFrozenSet(). This is especially useful when you have a small, fixed set of values. The syntax is concise: FrozenSet<int> frozen = [1, 2, 3].ToFrozenSet();. Similarly for dictionaries, you can use collection expressions with key-value pairs: FrozenDictionary<string, int> frozen = new Dictionary<string, int> { ["a"] = 1, ["b"] = 2 }.ToFrozenDictionary();. Note that collection expressions for dictionaries require a dictionary initializer. This combination reduces boilerplate and ensures immutability from the start. It's a best practice for defining constants or configuration that should never change.

using System;
using System.Collections.Frozen;
using System.Collections.Generic;

// Create a frozen set from a collection expression
FrozenSet<string> validStatuses = ["Active", "Inactive", "Pending"].ToFrozenSet();

// Create a frozen dictionary from a collection expression
FrozenDictionary<string, int> statusCodes = new Dictionary<string, int>
{
    ["Active"] = 200,
    ["Inactive"] = 404,
    ["Pending"] = 202
}.ToFrozenDictionary();

// Usage
string status = "Active";
if (validStatuses.Contains(status))
{
    Console.WriteLine($"Status code: {statusCodes[status]}");
}

Performance Considerations and Benchmarks

Frozen collections are optimized for read performance, but they come with a creation cost. In scenarios where you create the collection once and read many times, frozen collections outperform regular collections. For example, a FrozenSet lookup is typically faster than a HashSet lookup because the internal structure is optimized after freezing. However, if you only read a few times, the creation overhead may not be justified. Collection expressions themselves have negligible performance impact; they are compiled to efficient code. When benchmarking, consider the following: creation time, lookup time, and memory usage. Frozen collections often use less memory than mutable counterparts because they can discard unused capacity. Use BenchmarkDotNet to measure your specific scenario. As a rule of thumb, if you have a collection that is read more than 10 times after creation, freezing is beneficial.

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using System.Collections.Frozen;
using System.Collections.Generic;

public class FrozenVsHashSet
{
    private HashSet<int> _hashSet;
    private FrozenSet<int> _frozenSet;

    [GlobalSetup]
    public void Setup()
    {
        var items = new int[1000];
        for (int i = 0; i < 1000; i++) items[i] = i;
        _hashSet = new HashSet<int>(items);
        _frozenSet = _hashSet.ToFrozenSet();
    }

    [Benchmark]
    public bool HashSetLookup() => _hashSet.Contains(500);

    [Benchmark]
    public bool FrozenSetLookup() => _frozenSet.Contains(500);
}

// Run with: BenchmarkRunner.Run<FrozenVsHashSet>();

Real-World Use Case: Configuration Caching

A common use case for frozen collections is caching configuration data. For example, an application might read a list of allowed IP addresses from a config file at startup. This list rarely changes, but is checked on every request. Using a FrozenSet<string> ensures fast lookups and prevents accidental modification. Similarly, a mapping of error codes to messages can be stored in a FrozenDictionary<int, string>. The following example demonstrates loading configuration from a JSON file and freezing it. Note that the frozen collection is created once and reused across requests, typically registered as a singleton in dependency injection.

using System.Collections.Frozen;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;

public class ConfigService
{
    public FrozenDictionary<string, string> Settings { get; }

    public ConfigService(string configPath)
    {
        var json = File.ReadAllText(configPath);
        var dict = JsonSerializer.Deserialize<Dictionary<string, string>>(json);
        Settings = dict.ToFrozenDictionary();
    }

    public string GetSetting(string key) => Settings.TryGetValue(key, out var value) ? value : null;
}

// Usage in startup:
// services.AddSingleton(new ConfigService("appsettings.json"));

Common Mistakes and How to Avoid Them

One common mistake is assuming that a readonly collection is immutable. readonly only prevents reassignment of the reference, not modification of the collection's contents. Another mistake is using frozen collections in scenarios where the data changes frequently; freezing is a one-time operation. Also, developers sometimes forget that ToFrozenSet() creates a copy, so modifying the original collection after freezing does not affect the frozen copy. This can lead to stale data if not handled properly. Finally, avoid using collection expressions inside loops that create many collections; this can cause excessive allocations. Instead, create the collection once outside the loop.

// Mistake 1: readonly does not prevent modification
readonly List<int> list = [1, 2, 3];
list.Add(4); // This compiles and runs, modifying the list

// Mistake 2: Freezing then modifying original
var mutableSet = new HashSet<int> { 1, 2 };
var frozen = mutableSet.ToFrozenSet();
mutableSet.Add(3); // frozen still has only 1,2

// Mistake 3: Creating frozen collection per request
for (int i = 0; i < 1000; i++)
{
    var frozen = new[] { i }.ToFrozenSet(); // Bad: recreating
}

// Correct: create once
var frozenOnce = Enumerable.Range(0, 1000).ToFrozenSet();