Skip to content

C# Collections and Queries: Build, Slice and Query Data

This page covers the C# features you use to build collections, take pieces of them, produce sequences lazily, and query them. It follows the life of data in a typical service: create a collection concisely (collection expressions and their arguments), address and slice it (^ and ..), stream it without materializing everything (iterators), and query it (lambdas, anonymous types, LINQ query syntax), finishing with the difference between in-memory and provider-translated queries (IEnumerable<T> and IQueryable<T>).

All samples use one invented OrdersPortal domain: customers, orders, SKUs and order status history. Every complete sample is a file-based program: save it as sample.cs and run dotnet run sample.cs with the .NET 10 SDK (C# 14). The output shown was produced with SDK 10.0.115. The C# 15 sample needs the .NET 11 SDK and is marked as not compiled here.

Feature Version Use it when
Collection expressions C# 12 Creating or combining arrays, lists, spans and sets.
Collection expression arguments C# 15 A collection expression also needs a capacity or comparer.
Index operator C# 8 You address elements from the end.
Range operator C# 8 You take a slice of an array, string or span.
Iterators and yield C# 2 A sequence should be produced lazily, item by item.
Lambda expressions C# 3 Passing a filter, projection or key selector to LINQ.
Anonymous types C# 3 A query needs a temporary shape with named fields.
LINQ query expressions C# 3 Joins, groupings and let read better as a query.
IEnumerable and IQueryable C# 3 (.NET Framework 3.5) Deciding where a query runs: in memory or in a database.

Introduced in C# 12 (.NET 8). A collection expression is a bracketed list, [a, b, c], that the compiler converts to whatever collection type the context asks for: arrays, List<T>, HashSet<T>, Span<T> and ReadOnlySpan<T>, the common collection interfaces, immutable collections, and any type with a CollectionBuilder attribute. The spread element ..source copies all elements of another collection into the new one, and [] is a typed empty collection.

The syntax is the same for every target, so changing a field from string[] to List<string> or ImmutableArray<string> does not change its initializer. The compiler also picks an efficient strategy: [] for a read-only target can become Array.Empty<T>(), and a span target can use stack storage instead of a heap array.

string[] defaultSkus = ["PEN-01", "PAD-02"];
List<string> promoSkus = ["MUG-09"];
// Spread (..) copies the elements of each source into the new collection.
List<string> catalog = [.. defaultSkus, .. promoSkus, "BAG-04"];
ReadOnlySpan<int> quantities = [3, 1, 2, 1]; // no heap array needed for a span target
HashSet<string> featured = []; // empty collection, type from the target
featured.Add("MUG-09");
Console.WriteLine(string.Join(", ", catalog));
Console.WriteLine($"Lines: {quantities.Length}, featured: {featured.Count}");
Console.WriteLine(Describe(["SO-1001", "SO-1002"])); // works as an argument too
static string Describe(IReadOnlyList<string> orderNumbers) =>
$"{orderNumbers.Count} orders, first {orderNumbers[0]}";

Output:

PEN-01, PAD-02, MUG-09, BAG-04
Lines: 4, featured: 1
2 orders, first SO-1001

Pitfalls:

  • A collection expression needs a target type: var skus = ["PEN-01"]; does not compile, because there is no natural type yet.
  • It always materializes every element, even when the target is IEnumerable<T>; spreading a large lazy query copies it in full.

Introduced in C# 15 (.NET 11). A with(...) element placed first in a collection expression passes arguments to the target collection’s constructor, or to the Create method of a CollectionBuilder type, before the elements are added. This closes the main gap of C# 12 collection expressions: you can now set a capacity or an equality comparer without falling back to new HashSet<string>(comparer) { ... }.

The with(...) arguments are evaluated first, then the elements, left to right. For IList<T> and ICollection<T> targets, with(capacity) creates a List<T> with that capacity; IEnumerable<T>, IReadOnlyCollection<T> and IReadOnlyList<T> accept only an empty with(). Not compiled here (needs .NET 11 SDK); the sample follows the Microsoft Learn reference for C# 15.

string[] importedSkus = ["pen-01", "PEN-01", "pad-02"];
// Capacity for a list that will grow after import.
List<string> pickList = [with(capacity: importedSkus.Length * 2), .. importedSkus];
// Comparer for SKUs that arrive in mixed case.
HashSet<string> uniqueSkus = [with(StringComparer.OrdinalIgnoreCase), .. importedSkus];
Console.WriteLine($"Pick list: {pickList.Count}, unique SKUs: {uniqueSkus.Count}");

Expected output, per the documented semantics:

Pick list: 3, unique SKUs: 2

Pitfalls:

  • with(...) is not supported for arrays, Span<T> or ReadOnlySpan<T>, and it must be the first element.
  • Its arguments do not take part in choosing an overload: Print([with(StringComparer.OrdinalIgnoreCase), "a"]) is ambiguous (CS0121) when Print has List<string> and HashSet<string> overloads. Assign to a typed variable first.

Introduced in C# 8 (.NET Core 3.0). The hat operator ^n means “n from the end”: ^1 is the last element and ^2 the one before it. It produces a System.Index value, which you can store and pass around, and Index.GetOffset(length) converts it to an ordinary position. Arrays, strings and spans support it directly. Any type with an accessible int indexer and a Length or Count property gets it for free, which is why it works on List<T>; the compiler rewrites list[^1] to list[list.Count - 1].

Use ^ whenever the code really means “from the end”. It removes the Length - 1 arithmetic that causes off-by-one bugs, and it reads as intent.

string[] statusHistory = ["Draft", "Submitted", "Paid", "Packed", "Shipped"];
Console.WriteLine($"Current: {statusHistory[^1]}"); // last element
Console.WriteLine($"Previous: {statusHistory[^2]}");
Index current = ^1; // System.Index is a value you can store
Console.WriteLine($"Index {current} -> offset {current.GetOffset(statusHistory.Length)}");
List<decimal> orderTotals = [120.00m, 80.00m, 45.50m];
Console.WriteLine($"Latest order total: {orderTotals[^1]}"); // List<T> works through Count + int indexer
try
{
Console.WriteLine(statusHistory[^0]); // ^0 is one past the end
}
catch (IndexOutOfRangeException)
{
Console.WriteLine("^0 is past the end");
}

Output:

Current: Shipped
Previous: Packed
Index ^1 -> offset 4
Latest order total: 45.50
^0 is past the end

Pitfalls:

  • ^0 is one past the end, so reading items[^0] always throws; it is only useful as the exclusive end of a range.
  • ^1 on an empty collection throws just like [Length - 1]; check for empty first.

Introduced in C# 8 (.NET Core 3.0). The range operator start..end selects a slice with an inclusive start and an exclusive end. Either side can be omitted (..3, 2.., ..) and either side can use ^, so [1..^1] drops the first and last items. It produces a System.Range value.

What a slice costs depends on the type. On arrays it allocates a new array (a copy), on strings a new string (like Substring), and on Span<T> and ReadOnlySpan<T> it returns a view over the same memory with no copy. A type opts in by having a Slice(int, int) method plus Length or Count. Current .NET gives List<T> such a method, so list[1..3] compiles and returns a new List<T> copy; CollectionsMarshal.AsSpan(list)[1..3] gives a no-copy view when you only read.

string[] statusHistory = ["Draft", "Submitted", "Paid", "Packed", "Shipped"];
string[] lastTwo = statusHistory[^2..]; // a new array
string[] middle = statusHistory[1..^1];
Console.WriteLine(string.Join(" > ", lastTwo));
Console.WriteLine(string.Join(" > ", middle));
string orderNumber = "SO-2026-001042";
Console.WriteLine($"Year {orderNumber[3..7]}, sequence {orderNumber[^6..]}"); // string slices
ReadOnlySpan<string> window = statusHistory.AsSpan()[..3]; // span slice: no copy
Console.WriteLine($"First three via span: {window.Length} items, ends with {window[^1]}");
Range page = 2..4; // System.Range is a value too
Console.WriteLine(string.Join(", ", statusHistory[page]));

Output:

Packed > Shipped
Submitted > Paid > Packed
Year 2026, sequence 001042
First three via span: 3 items, ends with Paid
Paid, Packed

Pitfalls:

  • Slicing an array in a hot loop allocates every time; slice array.AsSpan() instead when you only need to read the window.
  • A range whose start is after its end, or outside the bounds, throws ArgumentOutOfRangeException at run time; the compiler cannot check it.

Introduced in C# 2 (.NET Framework 2.0). A method that returns IEnumerable<T> or IEnumerator<T> and contains yield return is an iterator. The compiler turns it into a state machine: nothing runs when you call the method, each MoveNext runs the body up to the next yield return, and yield break ends the sequence. Values are produced on demand, so a pipeline can stop early (as the sample does after the second batch) without reading the remaining 96 orders.

Iterators are how LINQ operators such as Where and Select are built, and they are the right tool for paging, batching and streaming files or API results. C# 8 added IAsyncEnumerable<T> with await foreach for asynchronous streams. Since C# 13 an iterator may declare ref locals and ref struct locals and contain unsafe blocks, as long as none of them is live across a yield return.

foreach (var batch in Batch(LoadOrderNumbers(), size: 2))
{
Console.WriteLine($"Processing batch: {string.Join(", ", batch)}");
if (batch.Contains("SO-1003")) break; // stop early; the rest is never produced
}
static IEnumerable<string> LoadOrderNumbers()
{
for (int i = 1; i <= 100; i++)
{
Console.WriteLine($" read SO-{1000 + i}");
yield return $"SO-{1000 + i}";
}
}
static IEnumerable<string[]> Batch(IEnumerable<string> source, int size)
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(size); // runs only when enumeration starts
var buffer = new List<string>(size);
foreach (var item in source)
{
buffer.Add(item);
if (buffer.Count == size)
{
yield return buffer.ToArray();
buffer.Clear();
}
}
if (buffer.Count > 0) yield return buffer.ToArray();
}

Output:

read SO-1001
read SO-1002
Processing batch: SO-1001, SO-1002
read SO-1003
read SO-1004
Processing batch: SO-1003, SO-1004

Pitfalls:

  • Argument checks inside an iterator run on the first MoveNext, not at the call; to validate eagerly, check in a non-iterator method that then returns a private iterator (often a local function).
  • Every enumeration reruns the body. Enumerating the result twice re-reads the source; call ToList() once if you need it twice.
  • You cannot yield return inside a try block that has a catch, inside catch or finally, or in a method with ref, in or out parameters.

Introduced in C# 3 (.NET Framework 3.5). A lambda, o => o.Total >= minimum, is an inline anonymous function. LINQ is where most lambdas live: every Where, Select, OrderBy and GroupBy takes one. An expression lambda has a single expression body; a statement lambda uses braces and return. The same lambda text converts either to a delegate such as Func<Order, bool>, which runs as compiled code, or to an expression tree Expression<Func<Order, bool>>, which a query provider can translate; see IEnumerable and IQueryable.

Lambdas capture variables, not values. Combined with LINQ’s deferred execution, a query sees the value of a captured variable at enumeration time, as the sample shows with minimum. The static modifier (C# 9) forbids captures, which avoids accidental closures and their allocations. This section stays with lambdas as LINQ arguments; natural types, default parameters, attributes and parameter modifiers are covered in Methods and lambdas.

List<Order> orders =
[
new("SO-1001", "Harbor Supplies", 120.00m, OrderStatus.Shipped),
new("SO-1002", "Cobalt Cafe", 45.50m, OrderStatus.Submitted),
new("SO-1003", "Harbor Supplies", 80.00m, OrderStatus.Submitted),
];
decimal minimum = 50m;
Func<Order, bool> isLarge = o => o.Total >= minimum; // captures the variable, not its value
var openLarge = orders
.Where(o => o.Status != OrderStatus.Shipped) // expression lambda
.Where(isLarge)
.Select(o => $"{o.Number} {o.Total}");
minimum = 40m; // changed before the query runs
Console.WriteLine(string.Join("; ", openLarge)); // deferred: sees 40
var labeled = orders.Select((o, index) => // statement lambda with two parameters
{
string flag = o.Total > 100m ? "!" : "";
return $"{index + 1}. {o.Number}{flag}";
});
Console.WriteLine(string.Join(" ", labeled));
var byCustomer = orders.ToLookup(static o => o.Customer); // static: cannot capture by accident
Console.WriteLine($"Harbor Supplies orders: {byCustomer["Harbor Supplies"].Count()}");
public enum OrderStatus { Submitted, Shipped }
public record Order(string Number, string Customer, decimal Total, OrderStatus Status);

Output:

SO-1002 45.50; SO-1003 80.00
1. SO-1001! 2. SO-1002 3. SO-1003
Harbor Supplies orders: 2

Pitfalls:

  • A lambda that captures a loop variable or a variable changed later sees the latest value when the query finally runs.
  • Lambdas passed to IQueryable<T> methods must be translatable by the provider; a call to your own C# method inside them fails at run time or forces client evaluation.

Introduced in C# 3 (.NET Framework 3.5). new { Customer = g.Key, Orders = g.Count() } creates an instance of a compiler-generated class with read-only properties, value-based Equals and GetHashCode, and a readable ToString. Property names can be inferred from the expression, so new { o.Number, o.Total } produces properties Number and Total. Two anonymous object creations with the same property names, types and order in the same assembly share one type.

Anonymous types exist for LINQ projections: they give an intermediate or final query result named fields without declaring a class for every shape. Because the type has no name you can write, it is used with var and stays inside the method. Since C# 10 you can copy one with a with expression.

List<Order> orders =
[
new("SO-1001", "Harbor Supplies", 120.00m),
new("SO-1002", "Cobalt Cafe", 45.50m),
new("SO-1003", "Harbor Supplies", 80.00m),
];
var summaries = orders
.GroupBy(o => o.Customer)
.Select(g => new { Customer = g.Key, Orders = g.Count(), Revenue = g.Sum(o => o.Total) })
.OrderByDescending(s => s.Revenue);
foreach (var s in summaries)
Console.WriteLine(s); // compiler-generated ToString
var a = new { Customer = "Cobalt Cafe", Orders = 1 };
var b = new { Customer = "Cobalt Cafe", Orders = 1 };
Console.WriteLine($"Value equality: {a.Equals(b)}, same type: {a.GetType() == b.GetType()}");
public record Order(string Number, string Customer, decimal Total);

Output:

{ Customer = Harbor Supplies, Orders = 2, Revenue = 200.00 }
{ Customer = Cobalt Cafe, Orders = 1, Revenue = 45.50 }
Value equality: True, same type: True

Pitfalls:

  • An anonymous type cannot appear in a method signature; returning one as object or dynamic loses type safety. Use a record or a tuple when the shape crosses a method boundary.
  • Property order matters for type identity: new { A = 1, B = 2 } and new { B = 2, A = 1 } are different types.

Introduced in C# 3 (.NET Framework 3.5). Query syntax, from ... where ... select ..., is a language feature that the compiler translates into calls to methods named Where, Select, Join, GroupBy, OrderBy and so on. It works with anything that has those methods: LINQ to Objects, IQueryable<T> providers such as EF Core, and your own types.

Query syntax has two real advantages over method syntax. The let clause introduces a computed range variable without nesting anonymous types by hand, and join ... on ... equals and group ... by ... into are easier to read than the equivalent method calls with result selectors. Method syntax is shorter for simple filters and is the only way to call operators that have no keyword, such as Count, Sum, Take or Distinct. Mixing both, as the sample does with g.Count() inside a query, is normal.

List<Customer> customers = [new("C-100", "Harbor Supplies", "UK"), new("C-200", "Cobalt Cafe", "IE")];
List<Order> orders =
[
new("SO-1001", "C-100", 120.00m),
new("SO-1002", "C-200", 45.50m),
new("SO-1003", "C-100", 80.00m),
];
var report =
from o in orders
join c in customers on o.CustomerId equals c.Id
let withTax = Math.Round(o.Total * 1.2m, 2)
where withTax > 50m
group withTax by c.Name into g
orderby g.Key
select new { Customer = g.Key, Orders = g.Count(), Gross = g.Sum() };
foreach (var row in report)
Console.WriteLine($"{row.Customer}: {row.Orders} orders, {row.Gross} gross");
// The compiler translates the query into method calls; this is equivalent:
var sameReport = orders
.Join(customers, o => o.CustomerId, c => c.Id, (o, c) => new { o, c })
.Select(x => new { x.c.Name, WithTax = Math.Round(x.o.Total * 1.2m, 2) })
.Where(x => x.WithTax > 50m)
.GroupBy(x => x.Name, x => x.WithTax)
.OrderBy(g => g.Key)
.Select(g => new { Customer = g.Key, Orders = g.Count(), Gross = g.Sum() });
Console.WriteLine($"Same result: {report.SequenceEqual(sameReport)}");
public record Customer(string Id, string Name, string Country);
public record Order(string Number, string CustomerId, decimal Total);

Output:

Cobalt Cafe: 1 orders, 54.60 gross
Harbor Supplies: 2 orders, 240.00 gross
Same result: True

Pitfalls:

  • A query expression is deferred like any LINQ query: it runs each time you enumerate it, and sees the current contents of its sources.
  • join in query syntax is an inner join; a left join needs join ... into followed by DefaultIfEmpty(), or the LeftJoin operator added in .NET 10.

Introduced with LINQ in C# 3 (.NET Framework 3.5). IEnumerable<T> LINQ operators, in System.Linq.Enumerable, take delegates (Func<T, bool>) and run the query in your process. IQueryable<T> operators, in System.Linq.Queryable, take expression trees (Expression<Func<T, bool>>) and only record the query; a provider such as EF Core translates the whole tree, typically to SQL, when you enumerate it. The same lambda text compiles to either form depending on the static type of the source.

That static type decides where the work happens. Keep a query typed as IQueryable<T> while you add filters, ordering and paging so they run in the database. As soon as it becomes IEnumerable<T>, through AsEnumerable(), ToList(), or a method parameter typed IEnumerable<T>, every later operator runs in memory over everything fetched so far.

The sample uses AsQueryable() on a list to show the expression tree a provider would receive; in production the IQueryable<T> comes from a provider such as EF Core.

#:property PublishAot=false
// File-based apps default to Native AOT analysis, which warns about AsQueryable; a console project does not.
using System.Linq.Expressions;
List<Order> orders =
[
new("SO-1001", 120.00m, true),
new("SO-1002", 45.50m, false),
new("SO-1003", 80.00m, false),
];
// IEnumerable<T>: Where takes Func<Order, bool>, compiled code that runs in this process.
IEnumerable<Order> inMemory = orders.Where(o => !o.Shipped && o.Total > 50m);
// IQueryable<T>: Where takes Expression<Func<Order, bool>>, a data structure a provider translates.
IQueryable<Order> queryable = orders.AsQueryable().Where(o => !o.Shipped && o.Total > 50m);
Console.WriteLine(string.Join(", ", inMemory.Select(o => o.Number)));
Console.WriteLine(queryable.Expression); // what a provider such as EF Core would inspect
Expression<Func<Order, bool>> filter = o => o.Total > 100m;
Console.WriteLine($"{filter.Body.NodeType}: {filter.Body}");
// Calling AsEnumerable() switches the rest of the pipeline to in-memory LINQ.
var mixed = queryable.AsEnumerable().Where(o => o.Number.EndsWith('3'));
Console.WriteLine(mixed.GetType().Name);
public record Order(string Number, decimal Total, bool Shipped);

Output:

SO-1003
System.Collections.Generic.List`1[Order].Where(o => (Not(o.Shipped) AndAlso (o.Total > 50)))
GreaterThan: (o.Total > 100)
IEnumerableWhereIterator`1

Pitfalls:

  • Passing an IQueryable<T> to a method that takes IEnumerable<T> and then filtering there silently downloads the whole table and filters in memory.
  • Not every C# expression can be translated. EF Core evaluates untranslatable code on the client only in the final Select and throws anywhere else, so test queries against the real provider.
  • C# 14 can bind span-based MemoryExtensions.Contains instead of Enumerable.Contains inside expression trees over arrays, which providers and the expression interpreter may not support; call Enumerable.Contains(array, value) explicitly if a provider rejects it.
  • Create: collection expressions for literals and concatenation; add with(...) (C# 15) for capacity or comparers; use new when you need constructor arguments on older language versions.
  • Address and slice: ^ and .. on arrays, strings and spans; slice spans, not arrays, in hot paths.
  • Produce lazily: an iterator when items come from paging, files or computation and callers may stop early; a materialized list when callers enumerate several times.
  • Query: method syntax for short pipelines, query syntax for joins, let and grouping. Anonymous types inside a method, records when results leave it.
  • Where it runs: stay on IQueryable<T> until all filtering, sorting and paging is composed, then materialize once.

What is deferred execution, and when does a LINQ query actually run? Most LINQ operators return an object that describes the query. Nothing runs until something enumerates it: foreach, ToList, First, Count and similar. Each enumeration runs the whole pipeline again against the current source data and current captured variables.

What is the difference between items[^1] and items[items.Length - 1]? They select the same element. ^1 creates an Index from the end, and for arrays, strings, spans and countable types with an int indexer the compiler lowers it to the subtraction. It is clearer, and it works the same on types that use Count instead of Length.

Does a range slice copy data? It depends on the type. Arrays and strings return new copies; Span<T>, ReadOnlySpan<T> and Memory<T> return views over the same memory. That is why performance-sensitive code slices spans.

Why would you choose an iterator over returning a List<T>? An iterator produces items on demand, so memory stays flat for large or unbounded sources and callers can stop early. The trade-offs are deferred exceptions, re-execution on every enumeration, and the cost of a state machine for small fixed results.

What does the compiler generate for an anonymous type? A sealed internal class with read-only properties in declaration order, a constructor, value-based Equals and GetHashCode over all properties, and a ToString listing them. Identical shapes in one assembly share the type.

Senior scenario: an OrdersPortal report endpoint became slow and memory-hungry after a refactor that moved filters into a helper method. What do you look for? Check the helper’s parameter and return types. If it takes or returns IEnumerable<Order> while the source is an EF Core IQueryable<Order>, everything after that point runs in memory: the database returns every row and the filtering, sorting and paging happen in the web process. Change the helper to accept and return IQueryable<Order> (or Expression<Func<Order, bool>> predicates), confirm the generated SQL with logging or ToQueryString(), and materialize once at the end with paging applied.