介绍C#源生成器

05/06/2020 16:13:43 | China Standard Time

微软在2020年4月29日发布了源代码生成器的第一个预览，这是一个新的 C# 编译器功能，它允许开发人员检查用户代码并生成新的 C# 源文件添加到编译中，这是一种新的组件，我们称之为源生成器。要开始使用源生成器，需要安装最新的 .NET 5 预览和最新的 Visual Studio 2019 16.6 预览。

## 什么是源生成器？

除非您一直密切关注与 C# 语言和编译器相关的每个原型和提案，否则您很有可能会立即询问"什么是源生成器"。源生成器是在编译期间运行的代码段，可以检查程序以生成与代码的其余部分一起编译的其他文件。

源生成器是 C# 开发人员可以编写的新型组件，允许您执行两项主要操作：
1. 检索正在编译的所有用户代码。编写与正在编译的代码的语法和语义模型的代码，就像现在的分析器一样。
2. 生成可在编译过程中添加到编译对象的 C# 源文件。换句话说，在编译代码时，可以提供其他源代码作为编译的输入。

您可以使用编译器在编译过程中构建的丰富元数据来检查用户代码，然后将 C# 代码添加到基于您分析的数据的编译中！如果您熟悉 Roslyn 分析器，则可以将源生成器视为可以添加 C# 源代码的分析仪。

源生成器作为编译阶段运行，如下所示：
![](https://corehome.oss-cn-shenzhen.aliyuncs.com/blogs/Picture1.png)

源生成器是一个 .NET Standard 2.0 程序集，由编译器与任何分析器一起加载。它可以用于加载和运行 .NET 标准组件的环境。

现在，您已经了解了什么是源生成器，让我们了解一些可以案例。

## 可以从源生成器中受益的案例

源生成器最重要的方面不是它是什么，而是它可以启用什么。
今天，有三种常规方法可以检查用户代码： runtime reflection, IL weaving, 和 juggling MSBuild tasks 。源生成器要比每种方法都好。

runtime reflection 是很久以前 .NET 就有的一种强大的技术。有无数使用它的方案。一个非常常见的方案是在应用启动并使用该数据生成内容时，对用户代码执行一些分析。

例如，ASP.NET Core 在 Web 服务首次运行时使用反射来发现您定义的构造，以便它可以"连接"控制器和 RazorPage 等内容。尽管这使您能够编写具有强大抽象的简单代码，但它在运行时会产生性能损失：当 Web 服务或应用首次启动时，在发现运行时反射代码完成运行之前，它无法接受任何请求！尽管这种性能损失并不大，但在某种程度上是一个固定的成本。

使用源代码生成器时，启动的控制器的发现阶段,可以通过分析源代码并发出"连接"应用所需的代码，在编译时进行。可以使启动时间加快，因为在运行时执行的操作被放在了编译时执行。

源生成器可以提高性能，其方式不仅限于在运行时进行反射以发现类型。某些方案涉及多次调用 MSBuild C# 任务（称为 CSC），以便他们可以从编译中检查数据。可以想象，调用编译器不止一次会影响构建应用的总时间！我们正在研究如何使用源代码生成器来避免处理类似 MSBuild 任务的需要。

源生成器可以提供的另一个功能是禁止使用某些 [stringly-typed](https://wiki.c2.com/?StringlyTyped "stringly-typed") API，例如控制器和 RazorPage 之间的 ASP.NET Core 路由。使用源生成器，可以强类型路由，并将生成必要的字符串作为编译时间详细信息。这将减少错误键入的字符串文本导致请求未命中正确控制器的次数。

## 源生成器和提前（AOT）编译

源生成器的另一个特点是，它们可以帮助消除基于链接器和 AOT（提前）编译优化的主要障碍。许多框架和库大量使用反射或反射发射，如System.Text.Json，系统.Text.正则表达式，以及ASP.NET核心和 WPF 等框架，在运行时从用户代码中发现和发出的类型。

我们还发现，许多顶级NuGet 包大量使用反射来发现运行时的类型。合并这些包对于大多数 .NET 应用至关重要，因此代码使用 AOT 编译器优化的"可链接性"和功能将受到很大影响。我们期待与我们优秀的 OSS 社区合作，了解这些软件包如何使用源生成器并改善整个 .NET 生态系统。

## HelloWorld 源生成器版本

前面提到的源生成器的所有示例都非常复杂。让我们通过一个非常基本的案例来了解一下源生成器，编写自己的源生成器。

随着时间的推移，我们将使使用模板工具使入门变得更加容易。下面介绍如何手动执行此操作：

1. 创建如下所示的 .NET Standard 类库：

```xml
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>preview</LangVersion>
  </PropertyGroup>

  <PropertyGroup>
    <RestoreAdditionalProjectSources>https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet5/nuget/v3/index.json ;$(RestoreAdditionalProjectSources)</RestoreAdditionalProjectSources>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="3.6.0-3.20207.2" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.0.0-beta2.final" PrivateAssets="all" />
  </ItemGroup>

</Project>
```

2. 修改或创建一个 C# 文件，该文件指定您自己的源生成器，如下所示：

```csharp
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Text;

namespace SourceGeneratorSamples
{
    [Generator]
    public class HelloWorldGenerator : ISourceGenerator
    {
        public void Execute(SourceGeneratorContext context)
        {
            // begin creating the source we'll inject into the users compilation
            var sourceBuilder = new StringBuilder(@"
				using System;
				namespace HelloWorldGenerated
				{
					public static class HelloWorld
					{
						public static void SayHello() 
						{
							Console.WriteLine(""Hello from generated code!"");
							Console.WriteLine(""The following syntax trees existed in the compilation that created this program:"");
			");

            // using the context, get a list of syntax trees in the users compilation
            var syntaxTrees = context.Compilation.SyntaxTrees;

            // add the filepath of each tree to the class we're building
            foreach (SyntaxTree tree in syntaxTrees)
            {
                sourceBuilder.AppendLine($@"Console.WriteLine(@"" - {tree.FilePath}"");");
            }

            // finish creating the source to inject
            sourceBuilder.Append(@"
        }
    }
}");

            // inject the created source into the users compilation
            context.AddSource("helloWorldGenerator", SourceText.From(sourceBuilder.ToString(), Encoding.UTF8));
        }

        public void Initialize(InitializationContext context)
        {
            // No initialization required for this one
        }
    }
}
```

3. 将项目中的源生成器添加为分析器，并将预览添加到 LangVersion 到项目文件，如下所示：

```xml

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>


<ItemGroup>
    
    <ProjectReference Include="path-to-sourcegenerator-project.csproj" 
                      OutputItemType="Analyzer"
                      ReferenceOutputAssembly="false" />
</ItemGroup>
```

在 Visual Studio 中编写代码时，您将看到源生成器正在运行，生成的代码可用于项目。现在，你可以这样调用它：

```csharp
public class SomeClassInMyCode
{
    public void SomeMethodIHave()
    {
		// calls Console.WriteLine("Hello World!") and then prints out syntax trees
        HelloWorldGenerated.HelloWorld.SayHello();
    }
}
```

**注意：需要重新启动 Visual Studio 才能查看 IntelliSense，并借助早期工具消除错误**

使用源生成器可以执行更多操作，而不仅仅是类似这样的简单操作：
- 自动实现具有附加属性的类的接口，例如 INotifyPropertyChanged
- 根据从源生成器上下文检查的数据生成设置文件
- 将类中的值序列化到 JSON 字符串
- 等等。

[源生成器说明书](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.cookbook.md "源生成器说明书")中有一些解决这些问题的方法。

此外，我们在[GitHub 上提供了一组示例](https://github.com/dotnet/roslyn-sdk/tree/master/samples/CSharp/SourceGenerators "GitHub 上提供了一组示例")，您可以自行尝试。

如上所述，我们正在努力使编写和使用源生成器的变得体验更好，例如添加模板、允许无缝 IntelliSense 和导航、调试以及提高 Visual Studio 生成源文件的响应性和性能。

## 源生成器处于预览状态

如果您拥有用 C# 编写的 .NET 库，那么现在是评估源生成器并查看它们是否适合的时候了。很有可能，如果您的库大量使用反射，您将以某种方式受益。

为了帮助实现这一点，我们建议阅读以下文档：
- [源生成器设计文档](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.md "源生成器设计文档")，其中解释了源生成器 API 和当前功能
- [源生成器说明书](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.cookbook.md "源生成器说明书")，它提供了不同方案的不同源生成器的示例


## 源生成器的下一步工作

第一个预览：Visual Studio 预览版本可以体验到最基本的功能，但这还未达到我们预期的目标 。在立下flag支持某些功能之前，我们可能会探索一些不同的设计。从现在到 .NET 5 版本之间最大的焦点领域之一是改进源生成器的编辑体验。此外，我们期望修改 API 以适应合作伙伴团队和我们的 OSS 社区的反馈。

此外，我们将确保对源生成器的分发方式有良好的体验。我们目前以package的形式进行分发。当前使用 Analyzer 基础结构来处理编辑器工具中的配置。

## 常见问题

下面是我们预计有些人可能提出的问题列表。

### 源生成器与其他元编程功能（如宏或编译器插件）相比如何？

源生成器是元编程的一种形式，因此将它们与其他语言（如宏）的类似功能进行比较是很自然的。关键区别是源生成器不允许您重写用户代码。我们将此限制视为一个重大优势，因为它使用户代码在运行时保持可预测。我们认识到重写用户代码是一项非常强大的功能，但我们不太可能让源生成器来执行此操作。

### 源生成器如何与 F# 中的类型提供程序进行比较？

如果您是 F# 程序员（或熟悉语言），那么您可能听说过[Type Providers](https://docs.microsoft.com/zh-cn/dotnet/fsharp/tutorials/type-providers/ "Type Providers")。源生成器部分受到类型提供程序的启发，但有一些差异使它们与众不同。主要区别是类型提供程序是 F# 语言的一部分，并且基于外部源在内存中发出类型、属性和方法。源生成器是一种编译器功能，用于分析 C# 源代码并添加 C# 源代码重新包含在编译中。

### 我应该删除所有反射代码吗？

不！反射是一个令人难以置信的有用的工具使用。在某些情况下，反射确实带来了一些性能和"可链接性"挑战，这些挑战可以通过源生成器解决。我们建议仔细评估源生成器是否适合您的方案。

### 源生成器与分析器有什么不同？

源生成器与分析器类似，因为两者都是编译器功能。关键区别是，分析器最终发出可用于与代码修复和关联的诊断。源生成器最终生成添加到编译中的 C# 源代码。[设计文件](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.md#discussion--open-issues--todos "设计文件")中还讨论了其他几个差异。

### 我能否使用源代码生成器修改/重写现有代码？

不。如前所述，源代码生成器不允许重写用户源代码。我们不打算允许他们这样做。他们只能通过向编译添加 C# 源文件来增强编译。

### 源生成器何时退出预览？

我们打算在C#9中发布源生成器。但是，如果到时候未准备就绪，我们将会保留为预览版，并确保用户在需要时选择它。

### 我可以更改源生成器中的 TFM 吗？

从技术上讲，是的。源生成器是  .NET Standard 2.0 components，与任何项目一样，您可以更改 TFM。但是，它现在仅支持作为 .NET Standard 2.0 components 加载到项目中。

### 源生成器会支持 Visual Basic 和 F# 吗？

源生成器当前仅是 C# 功能。由于这是第一次预览，因此从现在到发布版本之间，可能更改许多内容。目前，我们不打算将源生成器添加到 Visual Basic 。如果您是 F# 开发人员，并且希望看到添加此功能，请搜索建议或在 [F# 语言建议存储库](https://github.com/fsharp/fslang-suggestions/ "F# 语言建议存储库") 中提交建议。

### 源生成器引入类库存在兼容性问题吗？

这个取决于类库。由于 VB 和 F# 目前不支持源生成器，因此库作者应避免设计其功能。在采用源生成器之前，库作者需要仔细考虑这一点。我们预计大多数库作者将使用源生成器来增强（而不是替换）C# 开发人员的当前体验。

### 为什么我没有得到用于生成的代码的 IntelliSense？为什么 Visual Studio 生成出错？

构建源生成器后，您需要重新启动 Visual Studio，以使错误消失，并且 IntelliSense 会针对生成的源代码显示 IntelliSense。之后就会起作用。

### 我可以在 Visual Studio 中调试或导航到生成的源吗？

最终，我们将支持 Visual Studio 中生成源的导航和调试。早期预览阶段尚不支持它。

### 如何发布自己的源生成器？

源生成器可以作为 NuGet 包提供，就像今天的 Analyzer 一样。事实上，它们与分析器使用相同的管道。如果您曾经发布过分析器，那么您可以轻松地发布源生成器。

### 是否会有微软创作的源生成器？

最终，是的。但是，目前还是第一个预览版本，可能需要很多更改来适应各种方案。当前 Microsoft 没有创作源生成器的计划。

TOP