C# Indexers — NullReference Ambush in String-Indexed Stores

Most C# developers discover indexers the moment they start digging into how List<T> or Dictionary<TKey, TValue> actually work under the hood. You use myList[0] every day without a second thought — but that bracket notation isn't some built-in language primitive reserved for arrays. It's a feature you can implement yourself on any class you write. That's what makes indexers genuinely powerful.

Before indexers existed, if you wanted your custom collection or data-wrapper class to support element access, you'd be stuck writing verbose GetItem(int index) and SetItem(int index, T value) methods. Users of your class would have to learn a bespoke API instead of reaching for the intuitive bracket syntax they already know. Indexers solve this by letting you define exactly what obj[key] means for your type — whether the key is an integer, a string, an enum, or anything else.

By the end of this article you'll understand not just how to declare an indexer, but when it's the right design choice, how to build multi-parameter and overloaded indexers, and the subtle bugs that catch even experienced developers off guard. You'll walk away ready to write cleaner APIs and answer indexer questions confidently in a technical interview.

What an Indexer Actually Is (and Why It Beats a Plain Method)

An indexer is a special kind of property that accepts one or more parameters — the index values inside the square brackets. Like a regular property it has a get accessor and an optional set accessor, but instead of using the property name as the access point, callers use bracket notation on the object itself.

The key design motivation is expressiveness. Compare these two lines:

string city = addressBook.GetEntry("Alice"); string city = addressBook["Alice"];

The second line is immediately obvious to anyone who has used a dictionary or array. The first forces the caller to learn your method name. When your class semantically represents a collection or a keyed store of data, an indexer makes your API feel native to the language.

Indexers are declared using the this keyword followed by the parameter list in square brackets — think of this as saying 'when someone indexes into me, here is what to do'. They live on the class just like properties, and they fully support access modifiers, readonly patterns (get-only), and even expression-bodied syntax for simple cases.

String-Keyed Indexers — Modeling a Real Configuration Store

Indexers don't have to use integers. Any type can be an index — and string-keyed indexers are especially common in the real world. ASP.NET's IConfiguration, HttpContext.Items, and ViewData all use string indexers. If you've ever written config["ConnectionStrings:Default"] you've used one.

A string indexer is ideal when your class wraps a keyed data store and you want callers to access values by name rather than position. It communicates intent clearly: this isn't a list, it's a lookup.

The example below models a lightweight application settings store. Notice how we return null for missing keys in the getter rather than throwing — this mirrors the design of Dictionary<TKey, TValue>.TryGetValue and prevents callers from wrapping every access in a try-catch. That's a deliberate API design choice, not an accident.

Overloaded and Multi-Parameter Indexers — When One Index Isn't Enough

C# lets you overload indexers just like methods — the same class can have multiple indexers as long as their parameter signatures differ. This is genuinely useful when your type can be meaningfully accessed by more than one kind of key.

You can also define indexers that take multiple parameters, separated by commas inside the brackets. This fits naturally for two-dimensional or grid-based data structures where obj[row, col] is far more readable than obj.GetCell(row, col).

The example below models a spreadsheet grid. It exposes both a two-integer indexer for positional access and a string indexer that parses Excel-style cell addresses like "B3". Both indexers share the same underlying storage. This gives callers the flexibility to use whichever style fits their context — and the class looks and feels like a first-class citizen of the language.

Read-Only Indexers and Interface Contracts — The Pattern You'll See in Real Codebases

Not every indexer should allow writes. A read-only indexer (get accessor only) is the right choice when your class exposes data that callers should query but never mutate directly — think of a compiled lookup table, a cached result set, or an immutable view over some underlying data.

Indexers can also be declared in interfaces, which is the key to writing testable, mockable code. When ASP.NET Core defines IHeaderDictionary with a string indexer, any class that implements that interface must provide that indexer. Your own interfaces can do exactly the same thing.

The example below shows a read-only country code lookup paired with an interface. Notice that the interface declares only a getter — implementing classes can add a setter internally if they need it, but callers holding a reference to the interface can't write through it. That's the encapsulation story indexers tell best.

Indexer Performance and Thread Safety — What Senior Engineers Watch For

Indexers are methods under the hood. The JIT can inline simple getters and setters, so for trivial cases they have zero overhead compared to a manually written method. But when you add validation, exception handling, or delegation to another method, the inlining budget shrinks.

More importantly, indexers are NOT inherently thread-safe. If two threads write and read through the same indexer concurrently, you get torn reads, corrupted state, or stale data. A common mistake: assuming that because you're using a collection as backing store, the indexer is safe. Dictionary<TKey,TValue> has internal locks only for some operations, but even then, concurrent indexer calls can cause exceptions or data loss.

This section shows a thread-safe indexer using a ReaderWriterLockSlim for a scenarios where reads are frequent and writes are rare. For high-throughput scenarios, consider using ConcurrentDictionary<TKey,TValue> and exposing its indexer directly.

Frequently Asked Questions