学习Source Generators之HelloWorld

介绍

源生成器是 C# 开发人员可以编写的一种新组件，允许执行两个主要操作：

1. 检索表示正在编译的所有用户代码的编译对象。 可以检查此对象，并且可以编写适用于正在编译的代码的语法和语义模型的代码，就像现在使用分析器一样。
2. 生成可在编译过程中添加到编译对象的 C# 源文件。 也就是说，在编译代码时，可以提供其他源代码作为编译的输入。

结合使用这两项操作能充分发挥源生成器的强大功能。 可以使用编译器在编译时构建的丰富元数据检查用户代码。 然后，生成器将 C# 代码发送回基于已分析数据的同一编译。 如果你熟悉 Roslyn 分析器，可以将源生成器视为可发出 C# 源代码的分析器。
源生成器作为编译阶段运行，如下所示：

源生成器是由编译器与任何分析器一起加载的 .NET Standard 2.0 程序集。 它在可以加载和运行 .NET Standard 组件的环境中使用。
注意：目前只能用 .NET Standard 2.0 程序集作源生成器。

实现Hello Wolrd

接下来开始使用Source Genertor实现我们我HelloWorld程序。

创建项目

创建一个HelloWorld的控制台项目。
将Program改成部分类。并添加一个Hello的部分方法。

namespace HelloWorld
{
    partial class Program
    {
        static void Main(string[] args)
        {
            Hello("Generated Code");
        }

        static partial void Hello(string name);
    }
}

接下来创建一个netstandard2.0的类库。
命名成HelloWorld.Analysis。添加依赖Microsoft.CodeAnalysis.CSharp和Microsoft.CodeAnalysis.Analyzers。需要设置PrivateAssets=“all”。
完整配置如下：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.2.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" PrivateAssets="all" />
  </ItemGroup>
</Project>

这里需要注意的是Microsoft.CodeAnalysis.CSharp不宜使用太高版本，太高版本可能会出现无法正常生成代码的情况。
在HelloWorld项目中添加HelloWorld.Analysis的项目依赖。并设置OutputItemType="Analyzer" ReferenceOutputAssembly="false"
如下所示：

<Project Sdk="Microsoft.NET.Sdk">

	<PropertyGroup>
		<OutputType>Exe</OutputType>
		<TargetFramework>net8.0</TargetFramework>
		<ImplicitUsings>enable</ImplicitUsings>
		<Nullable>enable</Nullable>
	</PropertyGroup>

	<ItemGroup>
		<ProjectReference Include="..\HelloWorld.Analysis\HelloWorld.Analysis.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
	</ItemGroup>

</Project>

实现Generator

在HelloWorld.Analysis中添加HelloSourceGenerator类。继承并实现ISourceGenerator接口。并且需要在类上加上Generator特性标签。
然后再Exceute中实现我们的代码生成逻辑。

using Microsoft.CodeAnalysis;

namespace HelloWorld.Analysis
{
    [Generator]
    public class HelloSourceGenerator : ISourceGenerator
    {
        public void Execute(GeneratorExecutionContext context)
        {
            var mainMethod = context.Compilation.GetEntryPoint(context.CancellationToken);

            string source = $@"// <auto-generated/>
using System;

namespace {mainMethod.ContainingNamespace.ToDisplayString()}
{{
    public static partial class {mainMethod.ContainingType.Name}
    {{
        static partial void Hello(string name) =>
            Console.WriteLine($""Hello: '{{name}}'"");
    }}
}}
";
            var typeName = mainMethod.ContainingType.Name;

            context.AddSource($"{typeName}.g.cs", source);
        }

        public void Initialize(GeneratorInitializationContext context)
        {
        }
    }
}

在上面代码中，通过Compilation获取Program程序入口的信息。包括命名空间，类名等等等。最后AddSource($"{typeName}.g.cs", source);表示我们把代码生成到.g.cs后缀的文件中。

编译

接下来启动编译项目，在HelloWorld的依赖项的分析器中会出现一个Program.g.cs文件。

双击打开可以看到生成的代码。并且会提示该文件是自动生成的，无法编辑。
可以看到，文件中我们实现了部分类Program中的部分方法Hello。

运行项目

启动项目，可以看到我们成功输出由Source Genertor生成的Hello方法的实现。

注意事项

细心的同学可能会看到我们编译的时候会出现一个警告：
warning RS1036: “HelloWorld.Analysis.HelloSourceGenerator”: 包含分析器或源生成器的项目应指定属性“true”
建议我们在项目中添加EnforceExtendedAnalyzerRules的属性。
当我们添加这个属性后这个警告就会消失。

<Project Sdk="Microsoft.NET.Sdk">

	<PropertyGroup>
		<TargetFramework>netstandard2.0</TargetFramework>
		<LangVersion>latest</LangVersion>
		<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
	</PropertyGroup>

	<ItemGroup>
		<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.2.0" PrivateAssets="all" />
		<PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" PrivateAssets="all" />
	</ItemGroup>
</Project>

设置 EnforceExtendedAnalyzerRules 为 true 的作用就是提供 API 禁用分析功能，防止写出分析器不支持的代码。设置 EnforceExtendedAnalyzerRules 为 true 时，有部分的 API 将会被提示不可用。具体API可以看： https://raw.githubusercontent.com/dotnet/roslyn-analyzers/2b6ab8d727ce73a78bcbf026ac75ea8a7c804daf/src/Microsoft.CodeAnalysis.Analyzers/Core/AnalyzerBannedSymbols.txt

Debug

前面我们直接编译就生成了代码，打断点也不会触发。那么我们如何调试SourceGenerator呢？
可以使用Debugger.Launch();来触发调试。
在我们的运行代码中加入这一行。在编译时会触发调试提示。

using Microsoft.CodeAnalysis;
using System.Diagnostics;

namespace HelloWorld.Analysis
{
    [Generator]
    public class HelloSourceGenerator : ISourceGenerator
    {
        public void Execute(GeneratorExecutionContext context)
        {
            Debugger.Launch(); //触发Debug
            var mainMethod = context.Compilation.GetEntryPoint(context.CancellationToken);

            string source = $@"// <auto-generated/>
using System;

namespace {mainMethod.ContainingNamespace.ToDisplayString()}
{{
    public static partial class {mainMethod.ContainingType.Name}
    {{
        static partial void Hello(string name) =>
            Console.WriteLine($""Hello: '{{name}}'"");
    }}
}}
";
            var typeName = mainMethod.ContainingType.Name;

            context.AddSource($"{typeName}.g.cs", source);
        }

        public void Initialize(GeneratorInitializationContext context)
        {
        }
    }
}

加入代码后，重新执行项目编译操作。会弹出Debugger提示。

点击OK即可进入调试模式。

如果不需要点击Cancel则可以跳过。

结语

本文初步的了解了SourceGenerator的功能以及使用和调试的方式，后面的文章我们再来逐步深入学习。