Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Collection Expression: Syntax and Examples

Learn how C# 12 collection expressions initialize arrays, lists, spans, and more with concise syntax and clear examples.

~4 min readC#
#C# 12#Collection Expressions#Arrays#Lists
Illustration of C# collection expression syntax showing multiple collection types being initialized.

C# collection expressions, introduced in C# 12, offer a consistent way to initialize many collection types without relying on type-specific syntax. Instead of using new int[] { ... } or new List<int> { ... }, you can write [1, 2, 3] and let the compiler determine the target type from context. This reduces verbosity and makes collection initialization more uniform across arrays, spans, lists, and custom collection types.

Basic Syntax and Target Typing

The core syntax is a comma-separated list of elements inside square brackets. The target type is determined by the variable declaration, method parameter, or property assignment. For example:

csharp
int[] numbers = [1, 2, 3]; List<string> names = ["Alice", "Bob"]; Span<int> span = [4, 5, 6];

In each case, the compiler constructs the appropriate collection type. This works because collection expressions can be translated through the target type's normal construction behavior: known array and span handling, an applicable Add method, or a collection builder Create method.

Creating Different Collection Types

Collection expressions can target arrays, List<T>, Span<T>, ReadOnlySpan<T>, ImmutableArray<T>, and other types that support the required construction pattern. Types such as HashSet<T> also work through the same Add-based construction used by collection initializers.

For example, to initialize an ImmutableArray<int>:

csharp
ImmutableArray<int> values = [10, 20, 30];

This is possible because ImmutableArray<T> exposes a collection builder that the compiler can use. As of C# 12, dictionary types such as Dictionary<K, V> are not direct targets for collection expressions; use a collection initializer such as new Dictionary<string, int> { ["key"] = 1 } instead.

Using the Spread Element (..)

The spread element .. lets you include elements from another collection or any enumerable. This is useful when you need to combine existing data with new elements. For instance:

csharp
int[] first = [1, 2]; int[] second = [.. first, 3, 4]; // [1, 2, 3, 4]

The spread element can appear anywhere in the list, and you can spread multiple collections. The compiler generates code to copy the referenced elements; for compile-time-known sources it can often optimize this, while dynamic sources are copied at runtime.

Empty Collection Expressions

An empty collection expression is simply []. It creates an empty collection of the target type. This can be cleaner than calling Array.Empty<T>() or new List<T>(). For example:

csharp
List<int> emptyList = []; int[] emptyArray = [];

Depending on the target type, [] can also avoid allocating a fresh collection every time, as when the compiler can target a shared empty array.

Performance and Allocation Considerations

The performance characteristics of collection expressions depend on the target type. When targeting a Span<T> or ReadOnlySpan<T>, the compiler can often use stack or static data, avoiding heap allocation. For arrays and lists, the behavior is similar to traditional initializers, but the compiler may optimize the construction.

For example, a collection expression targeting a ReadOnlySpan<int> can sometimes be compiled to a static data reference, which means no runtime allocation. This can be useful in hot paths where you need to pass a fixed set of values to a method.

However, if you spread a collection that is not known at compile time, the compiler must generate code to copy elements at runtime, which involves iteration and may allocate depending on the target type.

Compatibility and Language Version Requirements

Collection expressions are a C# 12 language feature. To use them, you need a compiler that supports C# 12 (Visual Studio 17.8 or later, or the .NET 8 SDK). The runtime does not need to be .NET 8 specifically; the collection expression syntax is compiled away. However, some target types, like ImmutableArray<T>, require the System.Collections.Immutable package, which is available in .NET Core and .NET 5+.

If you are working with C# 11 or earlier, collection expressions are not available, so fall back to traditional initializers.

Common Pitfalls and Edge Cases

One common mistake is assuming that collection expressions always allocate a new collection. For span targets, the expression may be stack-allocated, so you cannot return it from a method as a stack-backed span. Also, when using the spread element with a collection that implements IEnumerable<T>, the compiler may need to iterate it at runtime, which can affect performance if the source is large.

Another edge case is target type inference. If the target type is not clear, the compiler raises an error. For example, using var with a collection expression is not allowed because there is no natural type:

csharp
var invalid = [1, 2]; // error CS9176: There is no target type for the collection expression

Instead, declare the type explicitly:

csharp
int[] valid = [1, 2];

Collection expressions also work with custom types if you implement the collection builder pattern. That requires defining a Create method with the appropriate signature and annotating the collection type with the [CollectionBuilder] attribute so the compiler can find it. This advanced usage lets you bring the same concise syntax to domain-specific collection types, but it adds complexity that is unnecessary for most applications.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.