C# 12 introduced collection expressions, a new, simplified syntax for initializing collections:
This syntax works great with built-in collection types, but what about your own custom collections?
That's where CollectionBuilderAttribute comes in, allowing you to extend this modern syntax to your own types.
Custom Collections left behind
Imagine you've built a custom immutable collection type:
Before CollectionBuilderAttribute, you couldn't use the new collection expression syntax with this type. You'd be stuck with the old way:
Not exactly elegant compared to the modern syntax.
Enter CollectionBuilderAttribute
The CollectionBuilderAttribute bridges this gap by telling the compiler how to construct your collection from a collection expression. Here's an example:
Now you can write:
Beautiful! The compiler automatically calls your Create method with the items.
How it works
The attribute takes two parameters:
- Builder Type: A type containing the factory method (
typeof(ImmutableStackBuilder)) - Method Name: The name of the static method that creates instances (
"Create")
The builder method must:
- Be
static - Accept either
ReadOnlySpan<T>(preferred) orT[] - Return an instance of your collection type
- Have generic type parameters matching your collection
Remark: it is also necessary that the collection is an "iteration type", i.e. it should have a GetEnumerator() method that returns an IEnumerator (or IEnumerator<T>). The typical way to achieve this is by implementing the IEnumerable or IEnumerable<T> interface.
When all these things are in place, the compiler can generate the necessary code to construct your collection in the most efficient way.
More information
Collection expressions (Collection literals) - C# reference | Microsoft Learn
Adding support for collection expressions to yor own types
CollectionBuilderAttribute Class (System.Runtime.CompilerServices) | Microsoft Learn