When working with immutable collections in .NET, you’ve got to think differently than you do with mutable types. And trust me—this one can bite you hard if you’re not paying attention.

Let me set the stage…

In normal (mutable) collection types, Add() is a void method. It mutates the collection, and you move on. Life is simple.

But immutable collection types play by a different set of rules. They never mutate. Every “add” creates a new instance. That means if you write code like this:

var dictionary = ImmutableDictionary<string, Person>.Empty;

foreach (var item in people)
{
    dictionary.Add(item.Key, item.Value);
}

It looks innocent… but it does nothing.

Why?

Because Add() returns a new ImmutableDictionary—but you’re ignoring it. The original dictionary never changes. You’ve just written the most polite no-op loop imaginable.

The Correct Way?

Always capture the returned dictionary:

dictionary = dictionary.Add(item.Key, item.Value);

Now the additions actually happen… but here’s the bad news:

Benchmark Reality Check: This Pattern Is an Anti-Pattern

Updating immutable collections inside a loop this way is:

• 2.26× slower
• Allocates dramatically more memory
• Becomes a drag on performance as the collection size grows
• A silent productivity killer—because everything looks correct

The Solution: Use a Builder

Immutable collections include builders, designed specifically for scenarios where you need to construct a collection item-by-item.

Builders:

• Are insanely faster
• Avoid repeated allocation churn
• Provide near-mutable performance
• Still gives you an immutable result when finished

Example:

var builder = ImmutableDictionary.CreateBuilder<string, Person>();

foreach (var item in people)
{
    builder.Add(item.Key, item.Value);
}

var dictionary = builder.ToImmutable();

This is the pattern used by pros, by high-performance teams, and by anyone who doesn’t want their CPU crying in a corner.

Bottom Line

If you’re building an immutable collection in a loop, never chain Add() calls directly.

That’s an anti-pattern that costs you time, memory, and money—especially in cloud environments where performance = dollars.

Pick up any books by David McCarter by going to Amazon.com: http://bit.ly/RockYourCodeBooks

If you liked this article, please buy David a cup of Coffee by going here: https://www.buymeacoffee.com/dotnetdave

© The information in this article is copywritten and cannot be preproduced in any way without express permission from David McCarter.