Proposal: obsolete ISourceGenerator, SyntaxReceiver and all non-incremental APIs

Background and Motivation

The non-incremental generator APIs, namely ISourceGenerator & friends, are fundamentally not scalable and suffer from pretty big performance issues, which makes it so that they should literally just never be used. Them existing poses several issues:

• There’s plenty of docs and blog posts around showing how to use these APIs. Especially new developers see them, think they’re correct, and then proceed to write their own generators like that. Which means that:
  • They waste time learning how to use a fundamentally broken API
  • They will waste time when (ideally) migrating, as their architecture will not have been properly structured for incrementality
  • If they publish their generators, users will use them, potentially in large solutions, VS will become slow, and they’ll just open tickets for VS without realizing the issue is with one of the NuGet packages they’re referencing
  • Even if they don’t open tickets for VS, they’ll still just enjoy a much worse developer UX while working
• There’s literally nothing that clearly tells them that these types should just never be used anymore

This same scenario happened several times on C# Discord, and it keeps happening. It would be nice to just finally obsolete these types 🙂

Proposed API

namespace Microsoft.CodeAnalysis
{
+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public interface ISourceGenerator
    {
    }

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public interface ISyntaxReceiver
    {
    }

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public delegate ISyntaxReceiver SyntaxReceiverCreator();

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public interface ISyntaxContextReceiver
    {
    }

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public delegate ISyntaxContextReceiver? SyntaxContextReceiverCreator();

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public readonly struct GeneratorInitializationContext
    {
    }

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public readonly struct GeneratorExecutionContext
    {
    }

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public readonly struct GeneratorSyntaxContext
    {
    }

+   [Obsolete("Non-incremental source generators should not be used, use IIncrementalGenerator instead.")]
    public readonly struct GeneratorPostInitializationContext
    {
    }
}

Risks

No risks. This is not a binary nor a source breaking change. If people wanted to still use them they can just suppress the warning. It seems like just letting everyone use ISourceGenerator with no warnings whatsoever is a bigger risk on its own.

[jaredpar]

I’m not against this. When we went into source generators we went in knowing there was a decent chance we’d need to invent a better interface for the IDE, and if that happened we’d push the community in that direction over time. Incremental source generators are well established at this point and all our future design thoughts are around them only. I think an obsolete here as a nudge to get the ecosystem moving is fine.

@CyrusNajmabadi, @chsienki, @KathleenDollard thoughts?

[333fred]

We can use a custom attribute in the .NET 6/7 version of roslyn, and use the standard one in old versions.