Анализаторы Roslyn и файлы наборов правил

Руководство Unity 2020.3 (LTS)
Скриптинг
Настройка среды скриптов
Анализаторы Roslyn и файлы наборов правил

Используйте анализаторы Roslyn и файлы наборов правил в проектах Unity для проверки стиля, качества и других проблем вашего кода.

Вы можете использовать существующие библиотеки анализаторов для проверки своего кода и писать собственные анализаторы, чтобы продвигать лучшие практики или соглашения в вашей организации. На этой странице объясняется, как использовать анализаторы Roslyn в пустом проекте Unity.

Примечание. Анализаторы Roslyn совместимы только с общедоступными интегрированными средами разработки Unity, такими как Visual Studio и JetBrains Rider.

Использование существующей библиотеки анализатора Roslyn

Чтобы использовать существующую библиотеку анализатора Roslyn, установите библиотеку ErrorProne.NET.CoreAnalyzers из NuGet внутри вашего проекта. Затем откройте файл .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" />
    
  </ItemGroup>

Переместите три файла .dll в папку Assets (или любую папку, вложенную в папку Assets) в Unity. проект. В редакторе выберите файл .dll. В Инспекторе подключаемых модулей в разделе Выбор платформ для подключаемого модуля отключите параметр Любая платформа. В разделе Включить платформы отключите платформы Editor и Standalone. Затем присвойте всем библиотекам DLL новую метку объекта с именем RoslynAnalyzer.

Чтобы проверить, все ли работает, сохраните файл с именем RethrowError.cs со следующим кодом в папке Assets вашего проекта. Этот код заставляет 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();
    }
}

После этого вы должны увидеть следующие два предупреждения в окне консолиокне редактора Unity, в котором отображаются ошибки, предупреждения и другие сообщения, созданные Unity или вашими собственными сценариями. Подробнее
См. в Словарь:

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 или в подпапке, не содержащей файл определения сборки в любой из родительских папок. Если анализатор находится в папке, содержащей определение сборки, или во вложенной папке такой папки, анализатор применяется только к сборке, созданной на основе этого определения сборки, и ко всем другим сборкам, которые на нее ссылаются.

Это означает, что пакетконтейнер, в котором хранятся различные типы функций и ресурсы для Unity, включая инструменты и библиотеки Editor или Runtime, коллекции ресурсов и шаблоны проектов. Пакеты — это автономные единицы, которые диспетчер пакетов Unity может совместно использовать в проектах Unity. В большинстве случаев они называются пакетами, но иногда их называют пакетами Unity Package Manager (UPM). Подробнее
See in Словарь может предоставить анализаторы, применимые только к коду, использующему пакет, например, чтобы помочь пользователям пакета правильно использовать API пакета.

Файлы набора правил

Чтобы определить собственные правила обработки различных предупреждений и ошибок, выдаваемых анализаторами в вашем проекте, вы можете создать файл набора правил. Дополнительные сведения о том, как создать собственный набор правил, см. в документации Microsoft Visual Studio по адресу как создать собственный набор правил.

В корневую папку Assets поместите файл набора правил с именем Default.ruleset. Правила, определенные в Default.ruleset, применяются ко всем предопределенным сборкам (например, Assembly-CSharp.dll) и ко всем сборкам. созданные с использованием файлов .asmdef.

Чтобы переопределить правила в Default.ruleset для предопределенной сборки, создайте файл .ruleset в корневой папке с имя [PredefinedAssemblyName].ruleset. Например, правила в Assembly-CSharp.ruleset применяются к коду в Assembly-CSharp.dll. Только эти файлы .ruleset разрешены в корневой папке:

Набор правил по умолчанию
Assembly-CSharp.ruleset
Assembly-CSharp-firstpass.ruleset
Assembly-CSharp-Editor.ruleset
Assembly-CSharp-Editor-firstpass.ruleset

Рабочий процесс: тестирование файлов набора правил в Unity

Чтобы протестировать файлы наборов правил в Unity, выполните следующие действия:

Шаг 1. Настройте файл набора правил

Создайте вложенную папку с именем Subfolder внутри папки Assets вашего проекта.
Внутри подпапки:
1. Создайте новый файл .asmdef.
2. Сохраните копию файла RethrowError.cs.
Создайте файл Default.ruleset внутри Assets со следующим кодом:

<?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 перекомпилировать сборку с использованием новых файлов набора правил. После перекомпиляции вы должны увидеть два сообщения в окне консоли:

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, так и к Активы/Подпапка/RethrowError.cs.

Step 3: Add a custom ruleset

В Assets/Subfolder создайте файл .ruleset и дайте ему любое имя (в этом примере< code class="mono">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 снова скомпилирует проект, вы должны увидеть следующие сообщения в окне консоли:

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 по адресу Использование редактора набора правил анализа кода.

Другие анализаторы

Ниже приведены ссылки на Github-репозитории других популярных библиотек анализаторов Roslyn:

потрясающие анализаторы
dotnet/roslyn-analyzers
Добавлена совместимость с анализатором Roslyn в 2020.2

Вы можете отблагодарить автора, за перевод документации на русский язык. ₽ Спасибо