Proposal: Two-Phase Incremental Generators for Cross-Generator Dependencies

[StephaneDelcroix]

Two-Phase Incremental Generators

Summary

This proposal extends the existing incremental generator infrastructure to support a two-phase compilation model. In this model, generators can emit type declarations (signatures) in phase one, and full implementations in phase two. This enables generators to reference types produced by other generators, solving cross-generator dependency issues that currently require complex workarounds.

Motivation

Modern .NET applications commonly use multiple source generators that need to reference types created by other generators. The current limitation where generators cannot see each other's outputs creates significant problems for framework and library authors.

Real-World Problem: .NET MAUI

A typical .NET MAUI application uses multiple generators:

• XAML compiler - generates code-behind
• CommunityToolkit.Mvvm - generates observable properties and commands
• MAUI Community Toolkit - generates behaviors and converters
• Blazor - generates component code

When XAML code-behind needs to reference an MVVM-generated property, compilation fails because the XAML generator runs without visibility into the MVVM generator's output:

// CommunityToolkit.Mvvm generates this property
public partial class MainViewModel : ObservableObject
{
    [ObservableProperty]
    private string _title;
    // Generates: public string Title { get; set; }
}

// XAML generator tries to reference it - FAILS
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        BindingContext = new MainViewModel();
        BindingContext.Title = "Hello";  // ERROR: Title doesn't exist yet
    }
}

Current Workarounds

1. Nested Generator Execution - Invoke one generator from within another

   • Only works for generators you control
   • Violates independence principles
   • Creates tight coupling

2. Heuristic Type Guessing - Assume type shapes and allow errors

   • Poor developer experience
   • Cryptic error messages
   • Breaks on version changes

3. MSBuild Ordering - Use Before/After properties

   • Requires knowing all generators
   • Breaks with transitive dependencies
   • Forces full recompilation
   • No circular dependency resolution

Proposed Solution

Introduce a two-phase compilation model where generators declare types in phase one and implement them in phase two.

API Design

public void Initialize(IncrementalGeneratorInitializationContext context)
{
    // Phase 1: Declare types and signatures
    // These are visible to other generators in Phase 2
    context.RegisterDeclarationOutput(
        source: ...,
        action: (context, source) => 
        {
            // Emit partial types, method signatures, property declarations
            // No implementation bodies
        });
    
    // Phase 2: Provide implementations
    // Can see all declarations from Phase 1
    context.RegisterImplementationSourceOutput(
        source: ...,
        action: (context, source) => 
        {
            // Emit method bodies, complete implementations
            // Has access to enriched compilation including all declarations
        });
}

Execution Model

Phase 1: Declaration Phase

1. Create initial Compilation from user code
2. Execute all RegisterDeclarationOutput actions across all generators
3. Collect generated declaration sources (partial types, signatures)
4. Create EnrichedCompilation = initial compilation + declaration sources
5. Provide EnrichedCompilation to Phase 2

Phase 2: Implementation Phase

1. Use EnrichedCompilation that includes all generator declarations
2. Execute all RegisterImplementationSourceOutput and RegisterSourceOutput actions
3. Each generator can now see types declared by other generators
4. Produce final compilation output

Concrete Example

Phase 1 - CommunityToolkit.Mvvm declares property:

context.RegisterDeclarationOutput(source, (ctx, data) => {
    ctx.AddSource("MainViewModel.g.cs", @"
    public partial class MainViewModel : ObservableObject
    {
        public string Title { get; set; } // Declaration only
    }");
});

Phase 2 - MAUI XAML generator sees and uses it:

context.RegisterImplementationSourceOutput(source, (ctx, data) => {
    // Semantic model now includes Title property from Phase 1
    var viewModel = compilation.GetTypeByMetadataName("MainViewModel");
    var titleProp = viewModel.GetMembers("Title").FirstOrDefault();
    
    ctx.AddSource("MainPage.g.cs", @"
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            BindingContext = new MainViewModel();
            BindingContext.Title = ""Hello""; // ✓ Compiles successfully
        }
    }");
});

Phase 2 - CommunityToolkit.Mvvm implements property:

context.RegisterImplementationSourceOutput(source, (ctx, data) => {
    ctx.AddSource("MainViewModel.g.cs", @"
    public partial class MainViewModel : ObservableObject
    {
        private string _title;
        public string Title 
        { 
            get => _title;
            set => SetProperty(ref _title, value); // Implementation
        }
    }");
});

Design Principles

Determinism: Phase 1 cannot access other generators' declarations, preventing circular dependencies and non-deterministic behavior.

Performance: Only declaration changes trigger Phase 2 invalidation. Implementation-only changes don't cascade to dependent generators.

Compatibility: Existing single-phase generators continue to work. The two-phase model is opt-in via new registration methods.

Scalability: Generators don't need to know about each other. The runtime manages visibility automatically.

Benefits

1. No explicit ordering required - Eliminates MSBuild Before/After complexity
2. Better incremental compilation - Implementation changes don't cascade unnecessarily
3. Improved developer experience - Fewer cryptic compilation errors
4. Framework interoperability - Enables rich ecosystem of composable generators
5. Backward compatible - Existing generators continue to work unchanged
6. Prevents circular dependencies - Phase 1 isolation ensures deterministic compilation

Comparison with Existing APIs

API	Phase	Visibility	Current Behavior
RegisterPostInitializationOutput	Pre-compilation	N/A	Global usings, attributes
RegisterDeclarationOutput (new)	Phase 1	Initial compilation only	Type signatures, partial declarations
RegisterImplementationSourceOutput (enhanced)	Phase 2	Declarations from all generators	Complete implementations
RegisterSourceOutput	Phase 2	Declarations from all generators	Both declaration and implementation

Open Questions

1. Naming: RegisterDeclarationOutput vs RegisterSignatureOutput?
2. Granularity: Should declaration vs implementation be per-generator or per-output?
3. Diagnostics: How should errors in Phase 1 affect Phase 2 execution?
4. Incremental behavior: What level of caching between phases?
5. Strictness: Should the limitation to produce just declarations in Phase 1 be enforced or recommended?
6. Existing RegisterSourceOutput: Should it continue to work in Phase 2, or be deprecated in favor of explicit declaration/implementation split?

Prior Art

• Roslyn Issue #57589 - Earlier two-phase proposal discussion (October 2020)
• Current RegisterImplementationSourceOutput - Already distinguishes implementation from other outputs
• Source Generators Cookbook
• Incremental Generators

Implementation Considerations

This proposal would require:

1. Extensions to IncrementalGeneratorInitializationContext API
2. New compilation pipeline stages in the generator driver
3. Updates to incremental compilation caching strategy to track declaration vs implementation changes
4. Generator testing infrastructure updates to support two-phase execution
5. Documentation and migration guidance for generator authors
6. Performance analysis to ensure phase separation doesn't introduce overhead

Related Issues

• Cross-generator dependencies in .NET MAUI
• Razor/Blazor component generation challenges
• Third-party generator ecosystem limitations

---

Authors: .NET MAUI Team
Date: November 2025
Status: Proposal

[StephaneDelcroix]

better naming, or other ideas achieving the same purpose are welcome as well

[CyrusNajmabadi]

This seems to have the same issue as other proposals. Namely that it produces multiple compilations. Each one will generate their own symbol trees. And each one will need to be checked as the information generated into one can change the meaning of code within that same compilation (for example, all types may now bind to something else entirely.

This is particularly problematic as compilations and all this binding is expensive. And nothing can be shared from compilation to compilation.

If we want something faster, we should design it so it can operate within the context of a single compilation. But this is hard as either the newly generated code is somehow walled off so it cannot impact other code, or it generates in a fashion that requires rebinding all code to see if the meaning changed.

[CyrusNajmabadi]

Better incremental compilation - Implementation changes don't cascade unnecessarily

I don't really understand this statement.

I think it would be good to make an examplar with two hypothetical generators. And show how this works step by step initially.

Then show how an edit affects things, and why the has "better incremental compilation".

Remember that for a compilation there is currently no incrementality possible for source symbols. Because they are immutable and can reach all other source symbols, and all source symbols get back to syntax, it necessarily means that any change whatsoever forces an entirely new source symbol graph.

And as all source symbols are now different, the meaning of all code in the compilation can all be different.

Making new compilations is precisely what we must not do with new SG apis. .

[StephaneDelcroix]

I will rework this proposal next week

[StephaneDelcroix]

@CyrusNajmabadi what I meant was that it doesn't trigger regeneration on every changed, there is no ordering or invalidation. it's 2-phases, but the phrasing was confusing.

I'm in the context of generating source code from xaml (but you know that, and it's irrelevant to the problem), but let's use that as an example, and 2 generators. the problems are even more complex when we mix that with blazor.

imagine a page, and that's user code

<ContentPage
    xmlns=...
    x:Class="MyPage"
    MyAwesomeTitle="{Binding foo}"
/>

public class MyPage : ContentPage
{
    [Bindable]
    public string MyAwesomeTitle {get; set;}
}

the [Bindable] is provided by some external toolkit and actually generate a bindable property. We found at least 3 such attributes in different 3rd party toolkits (CommunityToolkit.Maui.BindablePropertyAttribute, SQuan.Helpers.Maui.Mvvm.BindablePropertyAttribute, Maui.BindableProperty.Generator.Core.AutoBindableAttribute), all being slight different (attributing a property, or a field, you name it)

in order to properly generate this code

this.SetBinding(MyAwesomeTitleProperty, new Binding("foo");

The Xaml source generator has to be able to find the MyAwesomeTitleProperty BindableProperty, check that it exists, etc... Unfortunately, this isn't part of the compilation we receive when we RegisterPostInitializationSourceOutput.

Ignoring the names proposed earlier, roslyn source generation is already multiple phases:

• RegisterPostInitializationSourceOutput => early on, generated source is part of the compilation
• RegisterSourceOutput => happens on every keystroke so the generated code is available to c# code
• RegisterImplementationSourceOutput => can be delayed til the actual production of the final assembly

Our Xaml sourcegen tries to be a good citizen, and split the API declaration and the actual content in RegisterSourceOutput and RegisterImplementationSourceOutput

As there's no obligation for generators registered in RegisterImplementationSourceOutput to run in a timely manner (unless there are free cpu cycles), what we'd like is an augmented compilation available there, containing the sources generated at RegisterSourceOutput level.

This is not an hypothetical issue, we're facing it, and the workarounds are ugly and incomplete:

• heuristic for some [BindableProperty] attributes [XSG] Add heuristic to support bindable properties generated by other source generators maui#32597
• guess the typenames generated by blazor [XSG] fallback to strings for x:Type maui#32384
• manually adding the result of our 1st phase into our 2nd phase https://github.com/dotnet/maui/blob/main/src/Controls/src/SourceGen/XamlGenerator.cs#L70-L89

the 2 first workaround are solutions in search of a problem, and will fire back. the 3rd is ok, as we cache the source to avoid recomputation, but is only possible because we own both