如何扩展MSBuild编译流程，重写C#顶级语句文件并保留IDE特性？

需求概述 #

要扩展C#项目的MSBuild编译流程，在编译器处理前将含顶级语句（TLS）的代码文件包装到自定义静态类的Execute()方法中（替代自动生成的<Program>$.Main()），同时保留原文件的IDE静态分析、自动补全等特性，错误需映射回原文件，最终让框架能调用所有生成的Execute()方法。

示例转换：
原文件Foo.cs：

Console.WriteLine("Foo");

生成编译用的Foo.g.cs：

public static class Foo
{
    public static void Execute()
    {
#line 1 "Foo.cs"
        Console.WriteLine("Foo");
#line default
    }
}

现有方案的问题 #

将原文件设为<None>、生成带#line指令的文件的方案，在IDE中存在严重缺陷：

• VS Code：OmniSharp仍触发CS8802（仅允许一个顶级语句编译单元）警告，且无法通过#pragma屏蔽，错误状态更新滞后
• Visual Studio/Rider：#line指令的行映射完全失效，原文件无静态分析反馈，仅基础语法高亮可用

最佳解决方案（最少步骤） #

采用增量Source Generator + 项目属性配置，完全适配C#工具链，兼顾编译流程与IDE体验：

步骤1：调整项目配置 #

修改.csproj，将原文件标记为附加分析文件（保留IDE特性但不参与编译），同时屏蔽顶级语句警告：

<PropertyGroup>
  <!-- 屏蔽附加文件的CS8802警告 -->
  <NoWarn>$(NoWarn);CS8802</NoWarn>
</PropertyGroup>

<ItemGroup>
  <!-- 原文件作为附加文件，供IDE分析和Source Generator读取 -->
  <AdditionalFiles Include="*.cs" Exclude="*.g.cs" />
  <!-- 生成的包装文件参与编译 -->
  <Compile Include="*.g.cs" />
</ItemGroup>

步骤2：实现增量Source Generator #

创建一个增量Source Generator，读取附加文件、识别顶级语句、生成带行映射的包装代码：

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using System.IO;

[Generator]
public class TopLevelWrapperGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // 筛选出包含顶级语句的附加文件
        var targetFiles = context.AdditionalFilesProvider
            .Where(HasTopLevelStatements)
            .Select((file, ct) => (
                FileName: Path.GetFileNameWithoutExtension(file.Path),
                Content: file.GetText(ct)?.ToString() ?? string.Empty
            ));

        // 生成包装代码
        context.RegisterSourceOutput(targetFiles, (spc, data) =>
        {
            var source = $$"""
public static class {{data.FileName}}
{
    public static void Execute()
    {
#line 1 "{{data.FileName}}.cs"
        {{data.Content}}
#line default
    }
}
""";
            spc.AddSource($"{data.FileName}.g.cs", source);
        });
    }

    // 判断文件是否包含顶级语句
    private bool HasTopLevelStatements(AdditionalText file)
    {
        var syntaxTree = CSharpSyntaxTree.ParseText(file.GetText()!.ToString());
        return syntaxTree.GetRoot().Members.Any(m => m is GlobalStatementSyntax);
    }
}

步骤3：集成Source Generator #

• 将Source Generator编译为NuGet包，或直接作为项目引用添加到目标C#项目中
• 重启IDE后，Source Generator会自动参与代码分析与生成流程

方案优势 #

• IDE全兼容：VS、VS Code、Rider均能保留原文件的静态分析、自动补全，#line指令可正确将编译错误映射回原文件
• 编译流程合规：MSBuild仅编译生成的.g.cs文件，避免顶级语句冲突
• 增量高效：仅当原文件修改时才重新生成代码，性能开销极低

内容的提问来源于stack exchange，提问作者Tyrrrz