Add source generator to emit public Program class definition

[captainsafia]

With the introduction of top-level statements in .NET 6, there is not longer an explicit Program class defined in user's ASP.NET Core applications. Instead, we rely on the Program class generated by the compiler, which has a default visibility of internal.

This introduces an annoying hurdle for users who want to write integration tests on top of our WebApplicationFactory which requires a public entrypoint as a generic type argument.

To work around this, we document that users can either:

• Add an IVT from their application code to their test code
• Add a public partial class Program {} declaration

The first approach runs the risk of the user having to expose truly internal types to their test code. The second approach is hard to discover.

To resolve this issue, we introduce a new source generator to the shared framework that will emit the public partial class Program {} declaration to applications that:

• Use top-level statements
• Don't declare the Program class as public in some other fashion
• Don't use the old-style Program.Main declarations

[captainsafia]

@wtgodbe Can you sanity check my packaging changes here? I think it's correct given what we had to do in .NEt 8 for the RequestDelegateGenerator but let me know if I missed something.

[captainsafia]

cc: @amcasey for Roslyn review

[dotnet-policy-service]

Hey @dotnet/aspnet-build, looks like this PR is something you want to take a look at.

[martincostello]

Just curious, will there be any analyzer or anything that could point out this was added and that any manually added Program declarations can be removed?

I have a tonne of these I could delete with this built-in (example), so anything that could point it out rather than me needing to go find them all would be useful 😅

[gfoidl]

A different idea / approach:

Update the compiler so that it can emit a public class Program that is configurable via MsBuild-property.
So the default remains the same, when the property is set the public class is emitted.
Thus the change here boils down to updating the template csproj.

Or is the process via compiler, sdk, etc. too tedious that this approach is cheaper?

[captainsafia]

Just curious, will there be any analyzer or anything that could point out this was added and that any manually added Program declarations can be removed?

Oh, good idea! We can definitely author an analyzer + codefix that discovers the public partial class Program { } and recommends removing them if you're targeting net10 and above.

Update the compiler so that it can emit a public class Program that is configurable via MsBuild-property.

There was a proposal to change the compiler's behavior to emit a public Program class by default for top-level statements but it was rejected because:

• At the moment, this ASP.NET Core integration testing scenario seems to be the only one.
• More importantly, there were questions about what the visibility/accessibility of types defined in the generated Program class should be.

With those in mind, it was a bit more straightforward for ASP.NET to control its own destiny here and author a source generator.

[amcasey]

(Haven't read the code yet)

We also don't want to do this if they've explicitly declared it internal, right?

internal partial class Program {}

[amcasey]

I'm pretty sure the compilation knows its own entrypoint, but I'm not sure that's exposed anywhere.

Edit: this might be a useful reference.

[captainsafia]

We also don't want to do this if they've explicitly declared it internal, right?

Yep, this is another good case to cover in tests. Practically, I don't know how frequently users are doing this since the visibility of the Program class is already internal. I suppose it's also possible for somebody to declare private partial class Program { }. It's not you can't declare private or protected access in top-level classes.

Edit: this might be a useful reference.

Good reference! I'll incorporate some of the checks here into our code.

[Tornhoof]

I kinda second @gfoidl's question, isn't there a better way to do this, which technically should just be some switch somewhere during project generation or similar, run only once. Instead a source generator which is evaluated more often.

[captainsafia]

I kinda second @gfoidl's question, isn't there a better way to do this, which technically should just be some switch somewhere during project generation or similar, run only once. Instead a source generator which is evaluated more often.

I started off with this strategy but reached a limitation because there's not a ton of ability to introspect what the Program class that is already defined looks like. We'd end up generating the public partial class Program { } declaration in more situations that is acceptable which might result in surprising behavior.

Also,

some switch somewhere during

I'm assuming you're referring to a switch that the user would set. I'm keen to have this behavior be on-by-default since that moves the needle for this experience a lot more than users having to switch from a declaration in their source code to another switch in their app code.

[amcasey]

The checks that Program is the generated one seem sufficient. I'm ignorant about whether this is an efficient way to write a source generator.

[amcasey]

Out of curiosity, why not program.TypeKind != TypeKind.Class?

[captainsafia]

That's....a good idea 😅 I'll update as needed.

[Tornhoof]

I'm assuming you're referring to a switch that the user would set.

Yeah, something like the implicit usings setting or something similar, could then even be enabled automatically during project creation, but I understand that's a lot more effort than a src gen. Using MSBuild properties to decide if a srcgen should be executed is also not as straight forward as one might think. I admit, that I don't really see any quick win here.