Run a single generator at a time

[chsienki]

Background and Motivation

Today the generator driver only has the ability to run all generators it contains. As part of the razor cohosting work we would like the ability to only update a single generator (the razor generator in this case).

While we could remove the existing generators, run the driver, and then re-add them, this throws away any saved state associated with the removed generators meaning subsequent runs would not be incremental.

Proposed API

namespace Microsoft.CodeAnalysis
{
    public abstract class GeneratorDriver
    {
        public GeneratorDriver RunGenerators(Compilation compilation, CancellationToken cancellationToken = default) 

+       public GeneratorDriver RunGenerator(ISourceGenerator generator, Compilation compilation, CancellationToken cancellationToken = default)  
    }
}

Usage Examples

var compilation = GetCompilation();
var generator1 = new MySourceGenerator();
var generator2 = new MySourceGenerator();
var driver = new CSharpGeneratorDriver([generator1, generator2]);

// run all generators
driver = driver.RunGenerators(compilation);

// run only a single generator
driver = driver.RunGenerator(generator1, compilation);

var runResult = driver.GetRunResult();

var gen1Result = runResult.Results[0]; // result from second run
var gen2Result = runResult.Results[1]; // result from initial 'all generators' run

Open question: What happens if generator passed to RunGenerator isn't part of the driver? Exception, or just nothing happens?

Alternative Designs

// choose generator to run by type
// May run multiple generators, need to consider constraint on TGenerator to handle both ISourceGenerator and IIncrementalGenerator
public GeneratorDriver RunGenerator<TGenerator>(Compilation compilation, CancellationToken cancellationToken = default) 

// Add a param to RunGenerators that specifies a set of generators to run. 
// Generally, don't see a need to run a subset greater than a single generator.
// Passing null to say 'all' generators seems weird.
public GeneratorDriver RunGenerators(Compilation compilation, CancellationToken cancellationToken = default, IEnumerable<ISourceGenerator> specificGenerators = null) 

// Add a param to RunGenerators that has a filter
// Less weird that the filter being null equals all generators
public GeneratorDriver RunGenerators(Compilation compilation, CancellationToken cancellationToken = default, Func<ISourceGenerator, bool> generatorFilter = null) 

[333fred]

API Review

• We think a multiple-generator option is the better approach given balanced mode may want to run multiple generators in the future
• We'll change the filter parameter to have a context future-proofing the signature
• We'll also reorder the parameters to put the Func second and make it non-optional

public GeneratorDriver RunGenerators(Compilation compilation, Func<RunGeneratorsFilterContext, bool> generatorFilter, CancellationToken cancellationToken = default);

Conclusion: Above API shape is approved.