使用 EditorConfig 和 GitHub Actions 强制执行.NET 代码格式化

很久没发文了，最近比较忙啊比较忙！有好多朋友的留言错过了，实在抱歉！
本文是我发布在 Microsoft Community Content 的一篇文章的中文版，可点击“阅读原文”查看。

编码风格是个人偏好。但是，在团队中保持一致的编码风格很重要。自动化代码格式化过程可以帮助我们减少代码审查的时间，提高代码质量。在本教程文章中，您将学习如何使用 EditorConfig 和 GitHub Actions 强制执行.NET 代码格式化。

我们将会探索以下内容：

• 如何创建一个 EditorConfig 文件
• 如何在本地格式化 .NET 代码
• 如何使用 GitHub Actions 强制执行 .NET 代码格式化

准备工作

您需要准备以下内容：

• .NET 6 SDK or later^[1]
• Visual Studio 2022^[2]
• 一个 .NET 项目及其 GitHub 存储库^[3]

1. 创建 EditorConfig 文件

EditorConfig 文件定义和维护一致的编码样式，无论您使用哪种编辑器或 IDE。它是一个文本文件，其中包含一组定义如何格式化代码的设置。EditorConfig 支持各种编程语言和 IDE。在代码存储库中定义 EditorConfig 文件可以帮助我们对同一项目的开发人员实施统一的编码样式。

要了解更多关于 EditorConfig 的信息，请参阅官方文档^[4]。

要创建一个 EditorConfig 文件，您有几种选择：

1.1 使用 Visual Studio 的选项对话框

1. 使用 Visual Studio 打开您的 .NET 项目或解决方案。点击 工具 > 选项 > 文本编辑器 > C# > 代码样式。点击 从设置生成 .editoconfig 文件 按钮。这将会在您的项目中创建一个名为 .editorconfig 的文件。

2. 选择项目或解决方案的根目录，将文件命名为 .editorconfig，然后点击 保存。

1.2 使用 Visual Studio 的解决方案浏览器

1. 使用 Visual Studio 打开您的 .NET 项目或解决方案。在解决方案资源管理器中，右键单击项目或解决方案，然后选择 添加 > 新建项。
2. 在 添加新项 对话框中，搜索 editorconfig。您会看到有两个模板：

3. 选择 EditorConfig 文件 (.NET) 模板，将文件重命名为 .editorconfig，然后点击 添加。这将会在您的项目中创建一个名为 .editorconfig 的文件。

1.3 使用 dotnet new 命令

1. 打开命令提示符或终端，然后导航到您的 .NET 项目或解决方案的根目录。
2. 运行以下命令：

dotnet new editorconfig

这将会在您的项目中创建一个名为 .editorconfig 的文件。

注意 .editorconfig 文件会应用到当前目录以及所有子目录的所有文件。如果您想要在特定目录中使用不同的编码样式，您可以在该目录中创建一个新的 .editorconfig 文件来覆盖上层目录中的设置。但是，建议仅使用一个 .editorconfig 文件，以避免不必要的混乱。

2. 编辑 EditorConfig 文件

现在，您已经创建了一个名为 .editorconfig 的文件，您可以使用任意文本编辑器打开它。建议使用 Visual Studio 2022 来编辑，因为它提供了一个可视化的编辑器。

1. 使用 Visual Studio 打开 .editorconfig 文件。您可以看到代码样式的默认设置。

2. 按您的需求编辑设置。例如，您可以更改缩进大小，更改换行符，更改空格的使用方式，更改换行符的使用方式等等。注意不同的团队可能会有不同的偏好。请在修改之前与团队成员讨论。

3. 在本地格式化 .NET 代码

在本地格式化 .NET 代码有几种方法。

3.1 使用 Visual Studio 在保存时格式化代码

1. 使用 Visual Studio 打开您的 .NET 项目或解决方案。点击 工具 > 选项 > 文本编辑器 > 代码清理。选择 在保存时格式化代码 复选框。

2. 点击 设置代码清理。您可以选择保存文件时要格式化的代码样式。点击 确定。
3. 打开一个 .NET 文件，然后编辑它。当您保存文件时，Visual Studio 将会自动格式化代码。您也可以使用 Ctrl + K, Ctrl + E 快捷键来格式化代码。

3.2 在构建时格式化代码

打开 .csproj 文件，然后添加以下代码：

<PropertyGroup>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

当您构建项目时，Visual Studio 将会自动格式化代码。

3.3 使用 .NET CLI 命令

打开命令提示符或终端，然后导航到您的 .NET 项目或解决方案的根目录。运行以下命令：

dotnet format

这将会格式化您的项目中的所有文件。

以下是一些常用的命令：

• 验证代码格式化，不做任何修改：

dotnet format --verify-no-changes

• 格式化指定的项目或解决方案：

dotnet format ./SampleWebApi/SampleWebApi.sln

• 报告详细的格式化信息：

dotnet format --verbosity diagnostic

您可以找到更多关于 dotnet format 命令的信息，请参阅官方文档^[5]。

4. 使用 GitHub Actions 强制执行 .NET 代码格式化

GitHub Actions 是一个 CI/CD 平台，可以帮助我们自动化软件开发工作流程。您可以使用 GitHub Actions 在创建 Pull Request 时自动格式化代码。这样，您就可以在代码合并到主分支之前发现格式错误。

1. 打开您的 .NET 项目或解决方案的 GitHub 存储库。点击 Actions。
2. 在 Continuous integration 下，点击 .NET 任务的 Configure 按钮。

3. 将 workflow 重命名为 dotnet-format.yml 或其他您喜欢的名称。
4. 将以下代码复制到 dotnet-format.yml 文件中：

name: .NET format

on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]

jobs:
dotnet-format:

runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v3
- name: Setup .NET
uses: actions/setup-dotnet@v3
with:
dotnet-version: 8.0.x
- name: Restore dependencies
run: dotnet restore
- name: Format
run: dotnet format --verify-no-changes --verbosity diagnostic

请根据您的项目修改 dotnet-version。还可能需要修改项目或解决方案的文件夹路径。

在这个 YAML 文件中，我们定义了一个名为 .NET format 的 workflow。它将会在 main 分支上的 push 和 pull request 事件触发。它将会在 Ubuntu 上运行。它将会调用 dotnet format 命令来格式化代码。--verify-no-changes --verbosity diagnostic 参数将会验证代码格式化，不做任何修改，并报告详细的格式化信息。

5. 点击 Start commit 按钮，提交修改。
6. 创建一个新的 Pull Request。GitHub Actions 将会自动运行 dotnet format 命令来格式化代码。如果代码格式化失败，GitHub Actions 将会报告错误。

总结

在本教程文章中，您学习了如何使用 EditorConfig 和 GitHub Actions 强制执行 .NET 代码格式化。要了解更多关于 .NET 代码风格的信息，请参阅以下资源：

• .NET Code style preferences^[6]
• Create portable, custom editor settings with EditorConfig^[7]
• .NET Code-style rule options^[8]
• .NET Code-style rules^[9]
• Overview of .NET source code analysis^[10]
• GitHub Actions documentation^[11]

如果您使用 Azure DevOps Pipelines，您也可以实现类似的功能。请参阅官方文档^[12]。

参考资料