Building Custom Collection Types in C#: IEnumerable, Indexers, and Domain Logic

Building your own collection type sounds intimidating, but it’s often the cleanest way to create a focused API. Instead of exposing a raw List<T> and hoping consumers use it correctly, you can build something that encapsulates business logic and provides exactly the interface you need.

Why Build Custom Collections?

You’ll often want to control how data is accessed or add domain-specific behavior. A ProductCatalog that filters discontinued items automatically is cleaner than scattering .Where(p => p.IsActive) throughout your codebase.

Here’s a practical example, a MonthlyReportCollection that wraps monthly data with smart indexing:

public class MonthlyReportCollection : IEnumerable<MonthlyReport>
{
    private readonly MonthlyReport[] _reports = new MonthlyReport[12];

    public MonthlyReportCollection(IEnumerable<MonthlyReport> reports)
    {
        foreach (var report in reports)
        {
            _reports[report.Month - 1] = report; // Month 1-12 -> Index 0-11
        }
    }

    // Indexer for month-based access
    public MonthlyReport? this[int month]
    {
        get => month is >= 1 and <= 12 ? _reports[month - 1] : null;
        set
        {
            if (month is >= 1 and <= 12 && value is not null)
                _reports[month - 1] = value;
        }
    }

    // Range/Index support for modern C#
    public MonthlyReport?[] this[Range range] => _reports[range];

    // IEnumerable implementation using yield return
    public IEnumerator<MonthlyReport> GetEnumerator()
    {
        foreach (var report in _reports)
        {
            if (report is not null) // Only yield non-null reports
                yield return report;
        }
    }

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();

    // Bonus: domain-specific methods
    public MonthlyReport? GetQuarterEnd(int quarter) => quarter switch
    {
        1 => this[3],   // March
        2 => this[6],   // June  
        3 => this[9],   // September
        4 => this[12],  // December
        _ => null
    };
}

Usage feels natural and expressive:

var reports = new MonthlyReportCollection(monthlyData);

// Index access - clean and readable
var januaryReport = reports[1];
var lastQuarter = reports[10..12]; // Oct-Dec using Range

// Works with foreach
foreach (var report in reports)
{
    Console.WriteLine($"Month {report.Month}: ${report.Revenue}");
}

// LINQ works automatically
var profitableMonths = reports.Where(r => r.Revenue > 10000).ToList();

// Domain-specific API
var q4Report = reports.GetQuarterEnd(4);

Key Implementation Details

The yield return approach in GetEnumerator() is cleaner than manually implementing IEnumerator<T>. It generates the state machine for you and handles disposal automatically.

Notice how the indexer uses month is >= 1 and <= 12 for bounds checking, this prevents array index exceptions while keeping the API month-based rather than zero-based.

Range support (this[Range range]) gives you slicing syntax for free, making reports[1..4] work naturally.

Collection Capabilities Comparison

Common Pitfalls

Watch out for exposing internal collections directly. If your indexer returns a reference type, consumers can modify it. Consider returning defensive copies or immutable wrappers when needed.

Null safety matters, decide whether your collection allows null items and handle it consistently in both the enumerator and indexer.

Performance can be different from List<T>. The yield return approach creates an enumerator object per iteration, which might matter in tight loops.

When to Build Your Own

Build custom collections when you need domain-specific behavior, want to hide implementation details, or need to enforce business rules during access.

Stick with List<T> or Array when you just need basic storage without special logic. The overhead isn’t worth it for simple scenarios.

Custom collections shine when they make your API clearer and prevent misuse. A well-designed collection type can eliminate entire classes of bugs by making invalid operations impossible.

FAQ

Related Posts

• Encapsulation and Information Hiding in C#: Best Practices and Real-World Examples
• What Are the Risks of Exposing Public Fields or Collections in C#?
• Encapsulation Best Practices in C#: Controlled Setters vs Backing Fields
• When Inheritance Still Makes Sense in C#: Polymorphism Without Swapping
• Guard Clauses in C#: Cleaner Validation and Fail-Fast Code