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.
Features on this page
Section titled “Features on this page”| 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. |
Collection expressions
Section titled “Collection expressions”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 targetHashSet<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-04Lines: 4, featured: 12 orders, first SO-1001Pitfalls:
- 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.
Collection expression arguments
Section titled “Collection expression arguments”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: 2Pitfalls:
with(...)is not supported for arrays,Span<T>orReadOnlySpan<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) whenPrinthasList<string>andHashSet<string>overloads. Assign to a typed variable first.
Index operator
Section titled “Index operator”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 elementConsole.WriteLine($"Previous: {statusHistory[^2]}");
Index current = ^1; // System.Index is a value you can storeConsole.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: ShippedPrevious: PackedIndex ^1 -> offset 4Latest order total: 45.50^0 is past the endPitfalls:
^0is one past the end, so readingitems[^0]always throws; it is only useful as the exclusive end of a range.^1on an empty collection throws just like[Length - 1]; check for empty first.
Range operator
Section titled “Range operator”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 arraystring[] 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 copyConsole.WriteLine($"First three via span: {window.Length} items, ends with {window[^1]}");
Range page = 2..4; // System.Range is a value tooConsole.WriteLine(string.Join(", ", statusHistory[page]));Output:
Packed > ShippedSubmitted > Paid > PackedYear 2026, sequence 001042First three via span: 3 items, ends with PaidPaid, PackedPitfalls:
- 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
ArgumentOutOfRangeExceptionat run time; the compiler cannot check it.
Iterators and yield
Section titled “Iterators and yield”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-1002Processing batch: SO-1001, SO-1002 read SO-1003 read SO-1004Processing batch: SO-1003, SO-1004Pitfalls:
- 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 returninside atryblock that has acatch, insidecatchorfinally, or in a method withref,inoroutparameters.
Lambda expressions
Section titled “Lambda expressions”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 runsConsole.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 accidentConsole.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.001. SO-1001! 2. SO-1002 3. SO-1003Harbor Supplies orders: 2Pitfalls:
- 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.
Anonymous types
Section titled “Anonymous types”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: TruePitfalls:
- An anonymous type cannot appear in a method signature; returning one as
objectordynamicloses 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 }andnew { B = 2, A = 1 }are different types.
LINQ query expressions
Section titled “LINQ query expressions”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 grossHarbor Supplies: 2 orders, 240.00 grossSame result: TruePitfalls:
- A query expression is deferred like any LINQ query: it runs each time you enumerate it, and sees the current contents of its sources.
joinin query syntax is an inner join; a left join needsjoin ... intofollowed byDefaultIfEmpty(), or theLeftJoinoperator added in .NET 10.
IEnumerable and IQueryable
Section titled “IEnumerable and IQueryable”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-1003System.Collections.Generic.List`1[Order].Where(o => (Not(o.Shipped) AndAlso (o.Total > 50)))GreaterThan: (o.Total > 100)IEnumerableWhereIterator`1Pitfalls:
- Passing an
IQueryable<T>to a method that takesIEnumerable<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
Selectand throws anywhere else, so test queries against the real provider. - C# 14 can bind span-based
MemoryExtensions.Containsinstead ofEnumerable.Containsinside expression trees over arrays, which providers and the expression interpreter may not support; callEnumerable.Contains(array, value)explicitly if a provider rejects it.
Choosing between them
Section titled “Choosing between them”- Create: collection expressions for literals and concatenation; add
with(...)(C# 15) for capacity or comparers; usenewwhen 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,
letand 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.
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Methods and lambdas: lambda syntax and features beyond LINQ.
- Object construction, initialization and properties: indexers, records and
with. - Memory and performance: spans, the cheapest way to slice.
- Pattern matching: list patterns work on the same countable, indexable types.
- Release guides: C# 3, C# 8, C# 12, C# 15, and the version history.