源代码生成器指南

在.NET环境中，源代码生成器是一种在编译时运行的代码，它可以生成额外的代码或更改功能。本文将通过六个部分的指南，引导了解源代码生成器的创建和使用过程。

目录

• 第1部分 - 引言 / 准备创建源代码生成器
• 第2部分 - 创建源代码生成器的基础架构
• 第3部分 - 实现源代码生成器
• 第4部分 - 调试源代码生成器
• 第5部分 - 将源代码生成器打包成NuGet包
• 第6部分 - 如何使用NuGet源代码生成器

源代码生成器是在代码编译期间运行的代码，它通过检查代码中的命名空间、类、属性/字段、特性、接口等来生成代码。本文讨论的源代码生成器的输出是构建对象母亲（Object Mother）。Martin Fowler将它们描述为“在测试中使用的一种类，用于帮助创建用于测试的示例对象”。

本教程按重要性和讨论内容的顺序标记文件夹。每一步都是基于前一步构建的，因此建议第一次通过本教程时，按顺序逐步进行。每个文件夹中都有一个额外的Readme.md文件，详细讨论了该步骤的目的。此外，可以使用WinMerge等工具比较文件夹，以查看重要的变化。

教程概览

本教程适用于Visual Studio或VS Code。但是，由于作者不是VS Code用户，可能需要自行研究如何进行。可能遇到问题的两个领域是：

• 工具 - 将看到一个Visual Studio所需的选项。VS Code可能也有类似的要求。
• 调试 - 这可能只在Visual Studio中可用。

以下是实现的最低要求，使用的方法为ForAttributeWithMetadataName：

• Roslyn 4.3.1+
• .NET SDK 6.0.400+
• C#10.0+
• Visual Studio17.3 (.NET 6) / 17.8 (.NET 8)

在将Visual Studio升级到至少17.3之后，必须通过安装程序添加一个额外的功能。

准备创建源代码生成器

反向工作是创建生成对象的最简单方法。这样做可以帮助：

• 识别需要重复的部分
• 需要动态替换的部分
• 验证最终产品是否符合需求

创建一个简单的控制台应用程序，以想要的一般格式布局。这将包括：

• 一个“运行”方法，用于测试（Program.cs）
• 包含需要产生最终产品的类（Models文件夹）
• 一个类，包含所有方法和字符串插值，用于创建最终产品（FileGenerator.cs）

在这一点上，FileGenerator包含返回占位符数据的桩方法。当创建自己的生成器时，可以添加想要的任何内容。作者更喜欢在第3步 - 实现中通过方法进行有意义的更改。

确保应用程序运行并返回需要的一般形式。

• 2024年1月18日：初始版本
• 2024年1月20日：添加了关于源代码生成器的背景部分

在开始之前，了解源代码生成器的基本概念和背景知识是非常重要的。源代码生成器是一种特殊的代码，它在编译过程中运行，可以生成或修改代码。这种生成器可以用于多种目的，例如生成测试数据、创建辅助类或方法、甚至在编译时进行代码分析和重构。

在本部分中，将讨论源代码生成器的基本概念，并为生成器项目做准备。将从创建一个简单的控制台应用程序开始，这个应用程序将模拟最终产品，并帮助理解生成器需要做什么。

创建一个简单的控制台应用程序，这个应用程序将模拟最终产品，并帮助理解生成器需要做什么。这个应用程序将包括：

• 一个“运行”方法，用于测试（Program.cs）
• 包含需要产生最终产品的类（Models文件夹）
• 一个类，包含所有方法和字符串插值，用于创建最终产品（FileGenerator.cs）

在这一点上，FileGenerator包含返回占位符数据的桩方法。当创建自己的生成器时，可以添加想要的任何内容。作者更喜欢在第3步 - 实现中通过方法进行有意义的更改。

确保应用程序运行并返回需要的一般形式。这将帮助验证生成器的输出是否符合预期，并确保生成器能够正确地生成代码。

第2部分 - 创建源代码生成器的基础架构

在这部分，将创建源代码生成器的基础架构。这包括设置项目、添加必要的依赖项和配置文件。将从创建一个新的.NET项目开始，并逐步添加所需的组件。

首先，创建一个新的.NET项目。可以使用Visual Studio或VS Code来创建项目。在创建项目时，请确保选择正确的项目类型和目标框架。

接下来，添加必要的依赖项。这包括Roslyn编译器API和其他可能需要的库。可以通过NuGet包管理器来添加这些依赖项。

最后，配置项目以支持源代码生成器。这可能包括设置项目文件、添加配置选项等。确保项目配置正确，以便生成器能够正确地生成代码。

第3部分 - 实现源代码生成器

在这部分，将实现源代码生成器的核心功能。这包括编写代码来分析输入、生成输出并处理错误。将从分析输入开始，并逐步实现生成器的各个部分。

首先，需要分析输入代码。这包括读取源代码文件、解析语法树和提取所需的信息。将使用Roslyn编译器API来完成这项工作。

接下来，需要生成输出代码。这包括根据输入代码生成新的代码文件、修改现有代码或添加新的特性。将使用Roslyn编译器API来生成代码，并确保输出符合预期。

最后，需要处理可能发生的错误。这包括捕获异常、记录错误信息和提供有用的错误消息。将确保生成器能够优雅地处理错误，并提供足够的信息以便用户调试问题。

第4部分 - 调试源代码生成器

在这部分，将学习如何调试源代码生成器。这包括设置断点、查看变量和执行代码。将从设置断点开始，并逐步学习如何调试生成器的各个部分。

首先，需要在源代码生成器的代码中设置断点。这将帮助在调试时暂停执行并查看当前的状态。将使用Visual Studio或VS Code的调试工具来设置断点。

接下来，需要查看变量的值。这将帮助理解代码的执行流程和变量的状态。将使用调试工具来查看变量的值，并确保它们符合预期。

最后，需要执行代码并观察结果。这将帮助验证生成器的行为是否正确，并确保生成的代码符合预期。将使用调试工具来执行代码，并确保生成器能够正确地生成代码。

第5部分 - 将源代码生成器打包成NuGet包

在这部分，将学习如何将源代码生成器打包成NuGet包。这包括创建包文件、添加元数据和发布包。将从创建包文件开始，并逐步学习如何打包生成器。

首先，需要创建一个包文件。这包括编写.nuspec文件、添加必要的文件和设置元数据。将使用NuGet包管理器来创建包文件。

接下来，需要添加元数据。这包括设置包的标题、描述、版本和其他信息。将确保元数据准确无误，以便用户能够找到并理解包。

最后，需要发布包。这包括将包上传到NuGet.org或其他包存储库。将使用NuGet命令行工具或Visual Studio来发布包。

第6部分 - 如何使用NuGet源代码生成器

在这部分，将学习如何使用NuGet源代码生成器。这包括安装包、配置项目和使用生成器。将从安装包开始，并逐步学习如何使用生成器。

首先，需要安装NuGet包。这可以通过Visual Studio的NuGet包管理器或命令行工具来完成。将确保包已正确安装，并可以在项目中使用。

接下来，需要配置项目以使用生成器。这可能包括设置项目文件、添加配置选项等。将确保项目配置正确，以便生成器能够正确地生成代码。