Roslyn 分析器和规则集文件

在 Unity 项目中使用 Roslyn 分析器规则集文件，可检查代码的样式、质量和其他问题。

您可以使用现有分析器库来检查代码，也可以编写自己的分析器来提升组织内的最佳做法或惯例。本页介绍了如何在空的 Unity 项目中使用 Roslyn 分析器。

使用现有的 Roslyn 分析器库

要使用现有的 Roslyn 分析器库，请在您的项目中安装 NuGet 的 ErrorProne.NET.CoreAnalyzers 库。然后打开 .csproj 文件。该项目包含三个 .dll 文件作为分析器：

  <ItemGroup>
      <Analyzer Include="packages\ErrorProne.NET.CoreAnalyzers.0.1.2\analyzers\dotnet\cs\ErrorProne.NET.Core.dll" />
      <Analyzer Include="packages\ErrorProne.NET.CoreAnalyzers.0.1.2\analyzers\dotnet\cs\ErrorProne.Net.CoreAnalyzers.dll" />
      <Analyzer Include="packages\ErrorProne.NET.CoreAnalyzers.0.1.2\analyzers\dotnet\cs\RuntimeContracts.dll" />
    </ItemGroup>

将三个 .dll 文件移动到 Unity 项目中的 Assets 文件夹（或 Assets 文件夹内的任何文件夹）。在编辑器中选择 .dll 文件。在 Plugin Inspector 中的 Select platforms for plugin 下方, 禁用 Any Platform。在 Include platforms 下方，禁用 Editor 和 Standalone 平台。然后，为所有 DLL 指定一个名为“RoslynAnalyzer”的新资源标签。

为了测试一切是否正常，请在项目的 Assets 文件夹中保存一个名为 RethrowError.cs 的文件，其中包含以下代码。此代码导致 ErrorProne.NET 引发有关不正确异常传播和可疑异常处理的警告：

using System;
using UnityEngine;

public class RethrowError : MonoBehaviour
{
    void Update()
    {
        try
        {
            DoSomethingInteresting();
        }
        catch (Exception e)
        {
            Debug.Log(e.Message);
            throw e;
        }
    }

    private void DoSomethingInteresting()
    {
        throw new System.NotImplementedException();
    }
}

执行此操作后，您应该会在 Console 窗口中看到以下两个警告：

Assets\RethrowError.cs(14,23): warning EPC12: Suspicious exception handling: only e.Message is observed in exception block.
Assets\RethrowError.cs(15,19): warning ERP021: Incorrect exception propagation.Use throw; instead.

分析器范围

如果分析器位于 Assets 文件夹，或者位于一个子文件夹中且其任何父文件夹都不包含程序集定义文件，分析器将全局应用于您项目的所有程序集。如果分析器位于包含程序集定义的文件夹或此类文件夹的子文件夹中，则分析器仅应用于从该程序集定义生成的程序集以及引用它的任何其他程序集。

这意味着一个包提供的分析器可仅应用于使用该包的代码，例如帮助指导包的用户正确使用该包的 API。

规则集文件

要定义如何处理项目中的分析器引发的各种警告和错误的规则，您可以创建规则集文件。有关如何创建自定义规则集的更多信息，请参阅 Microsoft 的 Visual Studio 文档如何创建自定义规则集。

在 Assets 根文件夹中，放置一个名为 Default.ruleset 的规则集文件。您在 Default.ruleset 中定义的规则应用于所有预定义的程序集（例如 Assembly-CSharp.dll），以及所有使用 .asmdef 文件构建的程序集。

要覆盖用于预定义程序集的 Default.ruleset 中的规则，请在根文件夹中创建一个名为 [PredefinedAssemblyName].ruleset 的 .ruleset 文件。例如，Assembly-CSharp.ruleset 中的规则应用于 Assembly-CSharp.dll 中的代码。根文件夹中只允许使用这些 .ruleset 文件：

Default.ruleset
Assembly-CSharp.ruleset
Assembly-CSharp-firstpass.ruleset
Assembly-CSharp-Editor.ruleset
Assembly-CSharp-Editor-firstpass.ruleset

工作流程：在 Unity 中测试规则集文件

要在 Unity 中测试规则集文件，请执行以下步骤：

步骤 1：设置规则集文件

在项目的 Assets 文件夹中创建一个名为 Subfolder 的子文件夹。
在 Subfolder 内：
1. 创建一个新的 .asmdef 文件。
2. 保存 RethrowError.cs 的重复副本。
在 Assets 中创建一个 Default.ruleset 文件，包含如下代码：

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description=" " ToolsVersion="10.0">
  <Rules AnalyzerId="ErrorProne.NET.CodeAnalyzers" RuleNamespace="ErrorProne.NET.CodeAnalyzers">
    <Rule Id="ERP021" Action="Error" />
  <Rule Id="EPC12" Action="None" />
  </Rules>
</RuleSet>

Default.ruleset 文件定义了以下规则：

将关于可疑异常处理的警告的 EPC12 禁止。
将关于错误异常传播的警告的 ERP021 提升为错误。

第 2 步：重新加载项目

将规则集文件添加到您的项目后，重新导入程序集中需应用规则的任何脚本。这会强制 Unity 使用新的规则集文件重新编译程序集。重新编译后，您应该在 Console 窗口中看到两条消息：

Assets\Subfolder\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation.Use throw; instead.
Assets\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation.Use throw; instead.

请注意，Unity 将 Default.ruleset 中定义的规则应用到 Assets/RethrowError.cs 和 Assets/Subfolder/RethrowError.cs。

第 3 步：添加自定义规则集

在 Assets/Subfolder，创建一个 .ruleset 文件，并根据您的喜好命名（本例中为 Hello.ruleset）：

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description=" " ToolsVersion="10.0">
  <Rules AnalyzerId="ErrorProne.NET.CodeAnalyzers" RuleNamespace="ErrorProne.NET.CodeAnalyzers">
    <Rule Id="ERP021" Action="Info" />
    <Rule Id="EPC12" Action="Info" />
  </Rules>
</RuleSet>

这个新的 Hello.ruleset 文件告诉 Unity 将 EPC12 和 ERP021 打印到控制台，而不将它们视为警告或错误。

Unity 再次编译项目后，您会在 Console 窗口中看到以下消息：

Assets\Subfolder\RethrowError.cs(14,23): info EPC12: Suspicious exception handling: only e.Message is observed in exception block.
Assets\Subfolder\RethrowError.cs(15,19): info ERP021: Incorrect exception propagation.Use throw; instead.
Assets\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation.Use throw; instead.

Default.ruleset 中的规则仍然应用于 Assets\RethrowError.cs，但它们不再应用于 Assets\Subfolder\RethrowError.cs，因为 Hello.ruleset 中的规则将其覆盖。

有关所有允许的规则集操作文件的更多信息，请参阅 Visual Studio 文档使用代码分析规则集编辑器。

手册