Your C# incremental generator's output step reruns after every unrelated edit in the IDE; why does a pipeline model holding an ISymbol defeat caching, and what fixes it?
answer
- the driver compares step outputs
- symbols belong to one compilation
- arrays compare by reference
- records of strings
- TrackedSteps and run reasons
basics
~20 sThe driver skips downstream steps only when a step returns values equal to last run's. An ISymbol is a new object in every compilation, so it is never equal; return a record of strings and equatable collections instead.
solid answer
~40 sAn incremental pipeline caches by comparing each step's outputs with the previous run's: equal values stop the work, so `RegisterSourceOutput` is skipped. A symbol belongs to one `Compilation`, so after any edit the new `ISymbol` never equals the old one, and the cookbook warns it can also root old compilations in memory. `SyntaxNode`, `Location`, arrays and `ImmutableArray<T>` fail the same way, the collections because they compare by reference. Fix it by extracting what you need inside the transform into a `record` of strings, with collections wrapped for element-wise equality, and by narrowing `CompilationProvider` with `Select` before any `Combine`. Prove it with `trackIncrementalGeneratorSteps: true` and `WithTrackingName`, checking that a second run reports `Cached` or `Unchanged`.
code
csharp · 17 lines// Anti-pattern: the model is the symbol itself, so it differs after every edit.
var bad = context.SyntaxProvider.ForAttributeWithMetadataName("Demo.AutoDescribeAttribute",
static (_, _) => true,
static (ctx, _) => ctx.TargetSymbol)
.WithTrackingName("DescribeModel");
// Fix: extract strings inside the transform; the record's generated Equals compares values.
var good = context.SyntaxProvider.ForAttributeWithMetadataName("Demo.AutoDescribeAttribute",
static (_, _) => true,
static (ctx, _) => new DescribeModel(
ctx.TargetSymbol.ContainingNamespace.ToDisplayString(),
ctx.TargetSymbol.Name,
string.Join(", ", ((INamedTypeSymbol)ctx.TargetSymbol).GetMembers()
.OfType<IPropertySymbol>().Select(p => p.Name))))
.WithTrackingName("DescribeModel");
internal sealed record DescribeModel(string Namespace, string TypeName, string Members);go deeper
Recall that a generator can reuse its previous output when its inputs look the same, and that the comparison uses the values you return.
Explain value equality versus reference equality for records, arrays and symbols, and why a new compilation produces new symbol objects.
Diagnose a non-caching pipeline with tracked steps, then fix it with records of strings, equatable collection wrappers and narrowed Combine inputs, and lock it in with a test.
Make incremental behaviour a release criterion for internal generators, since every developer's editor pays for a pipeline that never caches.
## How an incremental pipeline decides to skip work Every step in an incremental generator's pipeline (`ForAttributeWithMetadataName`, `Select`, `Where`, `Combine`, `Collect`) keeps a table of the values it produced in the previous run. When the compilation changes, the driver must rerun the early steps, because almost any edit can change semantics. But as soon as a step produces values that are **equal** to last time's, the driver marks them unchanged and reuses everything downstream, including the source text the output step produced. Roslyn's cookbook puts it directly: pipeline models must be **value equatable**, and that is critical to incrementality. Equality here means `Equals` on your model type. So the question "will my output step rerun?" becomes "does my model compare equal across two compilations when nothing relevant changed?" ## What breaks equality - **`ISymbol`** (and everything derived from it, such as `INamedTypeSymbol`). A symbol belongs to one `Compilation`; the next compilation creates new symbol objects, so the old and new values are never equal. The cookbook says symbols are never equatable and adds a second cost: keeping them in models can **root old compilations** and hold large amounts of memory. - **`SyntaxNode` and `Location`.** Any edit to a file makes that file's nodes unequal to the previous ones. They are tolerated in the earliest steps but should leave the model as soon as possible. - **Collections with reference equality.** Arrays, `ImmutableArray<T>` and `List<T>` compare by reference, so a record holding one is unequal every run even when the elements match. - **`Compilation` combined too early.** `Combine(context.CompilationProvider)` hands the output step a value that changes on every edit; the docs show extracting the one fact you need with `Select` first, such as `CompilationProvider.Select((c, _) => c.AssemblyName)`. ## Seeing it happen Roslyn's `CSharpGeneratorDriver` can record what each step did. Create it with `new GeneratorDriverOptions(IncrementalGeneratorOutputKind.None, trackIncrementalGeneratorSteps: true)`, name a step with `.WithTrackingName("DescribeModel")`, run the driver, edit a file the generator does not care about, run again, and read `GetRunResult().Results[0].TrackedSteps["DescribeModel"]` and `TrackedOutputSteps`. Each output carries an `IncrementalStepRunReason`: `New`, `Modified`, `Unchanged`, `Cached` or `Removed`. In a scratch run of three `[AutoDescribe]` generators against the same edit (a constant changed in an unrelated class): | Model returned by the transform | Model step | Source output step | |---|---|---| | `record DescribeModel(string? Namespace, string TypeName, string Body)` | Unchanged | Cached | | `ctx.TargetSymbol` itself | Modified | Modified | | `record ArrayModel(string Name, ImmutableArray<string> Props)` | Modified | Modified | The second and third generators regenerate their file after an edit that had nothing to do with `Price`. In an editor that runs generators on every keystroke, that is the "generator runs on every keystroke" complaint. ## The fix 1. **Extract early.** In the `ForAttributeWithMetadataName` transform, read what you need from `TargetSymbol` and the semantic model and return only **strings, numbers, enums and booleans**. 2. **Use records** for models, so value equality is generated for you; the cookbook recommends records over classes for exactly this reason. 3. **Wrap collections** in a type with element-wise equality, the cookbook's "wrapper type around arrays", for example an `EquatableArray<T>` implementing `IEquatable<EquatableArray<T>>` with `SequenceEqual` and a matching `GetHashCode`. 4. **Narrow before combining.** `Select` the assembly name or the one analyzer option you need before `Combine`. 5. **Test it.** Assert in a unit test that the second run's tracked steps report `Cached` or `Unchanged`, so a later change that sneaks a symbol back into the model fails the build of the generator, not the patience of its users. ## A review checklist for generator models - Does any record or struct reachable from a pipeline step hold an `ISymbol`, `SyntaxNode`, `Location`, `SemanticModel` or `Compilation`? - Does any model field use an array, `List<T>` or `ImmutableArray<T>` without an element-wise wrapper? - Is `CompilationProvider` or `AnalyzerConfigOptionsProvider` combined whole into a provider that reaches an output? - Is there a test that runs the driver twice and checks the run reasons of the named steps? - Does `Collect` gather values that could have stayed per-target, making one change regenerate everything? ## What stays fine - Using symbols **inside** the transform is normal; the transform needs them. The rule is about what leaves it. - Equal models still let the early steps rerun on each edit; caching removes the expensive part, the output step and everything after it, not all work. - Diagnostics carry a `Location`, which is one reason the cookbook prefers a separate analyzer for reporting them.
- Why does a record holding an ImmutableArray<string> still miss the cache?A record's generated `Equals` compares each field with its type's equality, and `ImmutableArray<T>` compares by reference to the underlying array, not by elements. Every run builds a new array, so the field, and therefore the record, is unequal. Wrap the array in a struct implementing `IEquatable<EquatableArray<T>>` with `SequenceEqual` and an element-based `GetHashCode`, as the cookbook suggests.
- How do you keep an analyzer option in the model without combining the whole provider?Combine `AnalyzerConfigOptionsProvider` with your values, then immediately `Select` the single option string you need into the model, so the output step compares a string rather than the options object. The same applies to `CompilationProvider`: `Select` the assembly name or language version first, then `Combine` that small value.
- Holding an ISymbol in the model is fine because symbols are cached.
- Generators always rerun fully on every edit, so caching is pointless.
- ImmutableArray<T> compares its elements, so it is safe in models.
- Using symbols inside the transform breaks incrementality.
- Combining CompilationProvider early is harmless if the output is small.