NetFabric/NetFabric.Numerics / .agents/skills/dotnet-enumerable
dotnet-enumerable
VerifiedWrite and optimize C#/.NET enumerables, iterators, and LINQ usage. USE FOR: choosing IEnumerable<T>/IReadOnlyCollection<T>/IReadOnlyList<T>/ICollection<T>/IList<T>/IAsyncEnumerable<T> for params/returns; foreach codegen and value-type vs reference-type enumerator performance (List<T>, arrays, Span<T>, ImmutableArray<T>, ArraySegment<T>); avoiding boxed enumerator allocations; Count() vs Any() vs Count property complexity traps; First()/Single()(OrDefault) cost and predicate-overload collapsing; ToList()/ToArray() allocation cost vs lazy evaluation; returning Enumerable.Empty<T>()/yield break instead of null; writing yield-based iterators, lazy validation, coroutines, behavior trees; writing async iterators with await foreach/yield return, EnumeratorCancellation/WithCancellation token propagation, ConfigureAwait; handling enumerables via reflection/Roslyn (NetFabric.Reflection/CodeAnalysis). DO NOT USE FOR: SIMD/vectorized span math (dotnet-simd); generic math over numeric types (dotnet-generic-math).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
| references/async-enumeration.md | markdown | 3.6 KB |
| references/custom-iterators.md | markdown | 6.3 KB |
| references/enumerable-interfaces.md | markdown | 5.2 KB |
| references/iteration-performance.md | markdown | 7.5 KB |
| references/linq-patterns.md | markdown | 4.5 KB |
| references/tooling.md | markdown | 3.8 KB |
references/async-enumeration.md
View on GitHub# Async Enumeration Usage (IAsyncEnumerable\<T\>)
Consuming and cancelling async streams — concerns that have no sync-`foreach` equivalent. Interface shapes: [enumerable-interfaces.md](enumerable-interfaces.md#iasyncenumerablet--iasyncenumeratort). Writing an async iterator with `yield return`: [custom-iterators.md](custom-iterators.md#async-iterators).
## `await foreach` Desugaring
```csharp
var enumerator = source.GetAsyncEnumerator();
try
{
while (await enumerator.MoveNextAsync())
Use(enumerator.Current);
}
finally { if (enumerator is not null) await enumerator.DisposeAsync(); }
```
`await foreach` binds by the same pattern-based rules as `foreach`: a directly callable `GetAsyncEnumerator()` returning a type with `Current` and an awaitable `MoveNextAsync()` is enough — `IAsyncEnumerable<T>` isn't strictly required, matching how `foreach` doesn't strictly require `IEnumerable<T>`.
`foreach`/`await foreach` are not interchangeable — using the wrong one is a compile error naming the correct one to use:
| Code | Meaning |
|---|---|
| CS8414 / CS9353 | `foreach` used on a type that only implements the async-enumerable pattern — use `await foreach` |
| CS8415 | `await foreach` used on a type that only implements the sync-enumerable pattern — use `foreach` |
| CS8412 | `GetAsyncEnumerator`'s return type doesn't have a public `Current`/`MoveNextAsync` matching the pattern |
## Cancellation
Two ways to get a token into an async iterator:
```csharp
async IAsyncEnumerable<T> QueryAsync<T>(
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
while (...)
{
cancellationToken.ThrowIfCancellationRequested();
yield return item;
}
}
// caller
await foreach (var item in QueryAsync<T>().WithCancellation(token))
{
...
}
```
- `[EnumeratorCancellation]` on a `CancellationToken` parameter tells the compiler to route the token passed to the generated `GetAsyncEnumerator(CancellationToken)` into that parameter's value.
- `.WithCancellation(token)` (on the caller's side) is how that token actually gets supplied — it's what ends up calling `GetAsyncEnumerator(token)` instead of `GetAsyncEnumerator(default)`.
- Diagnostics: **CS8424** (attribute used on a non-token parameter, or outside an async-iterator returning `IAsyncEnumerable<T>`) fails to compile; **CS8425** (a token parameter exists but isn't attributed) compiles but silently ignores the caller's `WithCancellation` token; **CS8426** (attribute on more than one parameter) fails to compile.
## ConfigureAwait
Each `MoveNextAsync()` await captures the current `SynchronizationContext`/`TaskScheduler` by default, same as any other `await`. Disable capturing on the whole stream with `.ConfigureAwait(false)` (an extension on `IAsyncEnumerable<T>`, not per-await inside the iterator):
```csharp
await foreach (var item in source.WithCancellation(token).ConfigureAwait(false))
{
...
}
```
## IAsyncEnumerable\<T\> vs Task\<IReadOnlyList\<T\>\>
| Return | Use when |
|---|---|
| `IAsyncEnumerable<T>` | Items are produced incrementally (paged API, DB cursor, file stream) and the caller can start processing before the full sequence is available |
| `Task<IReadOnlyList<T>>` / `Task<T[]>` | The whole result must be materialized anyway, or the caller always needs random access/count |
Don't wrap an already-materializing `Task<List<T>>`-returning method as `IAsyncEnumerable<T>` purely for API consistency — that forces full materialization before the first `yield return` fires, losing the incremental-processing benefit while adding state-machine overhead for nothing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |