Unity 6.3
0 онлайн 25 гостей 3 в системе
Вход
← Руководство

Область анализатора и файлы наборов правил

По умолчанию анализаторы в корне Assets папка применяется ко всем предопределенные сборки в вашем проекте: то есть, к любым скриптам в Assets папки или ее подпапки, которые не являются частью пользовательской сборки, определенной с помощью файл определения сборки.

Если анализатор находится в папке, которая содержит файл определения сборки, или одной из ее подпапок, анализатор применяется только к этой сборке и к любой другой сборке, которая на нее ссылается.

Используя определения сборок, например, a пакет может предоставить анализаторы, которые анализируют только код, связанный с пакетом, что может помочь пользователям пакетов правильно использовать пакет API.

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

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

Набор правил по умолчанию

Можно создать файл набора правил с именем Default.ruleset в 2000 году Assets корневой папки. Правила, определенные в Default.ruleset применяется ко всем предопределенные сборки, и все сборки, изготовленные с использованием файлы определения сборки.

Переопределение правила по умолчанию

Для отдельных сборок можно создать дополнительные файлы наборов правил, переопределяющие набор по умолчанию.

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

Только следующие .ruleset файлы разрешены внутри корня Assets папка:

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

Чтобы переопределить Default.ruleset для индивидуального сборочного устройства, определенного в определении сборочного устройства (.asmdef) файл, создать специальный файл набора правил и поместить его рядом с .asmdef файл. Например, Assets/Scripts/Runtime/MyRuntimeAssembly.ruleset может содержать набор правил, который переопределяет набор правил по умолчанию для сборки Assets/Scripts/Runtime/MyRuntimeAssembly.asmdef.

Примечание: Наименование .ruleset файл для пользовательской сборки не должен совпадать с именем сборки.

Сфера применения правил и оптимальная практика

Default.ruleset применяется ко всем сборкам проекта, включая предопределённые и пользовательские, если только их не переопределяют наборы правил для конкретных сборок. Default.ruleset является единственным файлом набора правил, который может применяться к нескольким сборкам.

Любые дополнительные пользовательские файлы .ruleset имеют отношение один к одному с сборками. Пользовательский файл .ruleset должен быть размещен рядом с файлом определения сборки (.asmdef) для сборки, к которой он применяется.

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

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

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

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

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

  1. Создайте подпапку с именем Subfolder внутри папки Assets проекта.
  2. Внутри Subfolder:
    1. Создайте новый файл определения сборки (.asmdef).
    2. Сохраните дубликат RethrowError.cs со страницы Установка и использование существующего анализатора или генератора источников.
  3. Создайте файл 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, так и к 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 снова компилирует проект, в окне Консоли появляются следующие сообщения:

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 override them.

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

Альтернативы файлам наборов правил

Если вы контролируете код анализатора, вы можете написать сам анализатор, чтобы он вел себя по-разному в зависимости от определенных расположений или сборок. Например, вы можете написать код анализатора, чтобы он возвращался без анализа ничего под Assets/ThirdParty, чтобы предотвратить его запуск на стороннем коде.

Например, следующий фрагмент кода демонстрирует, как можно изменить пример анализатора, созданного в Создание и использование анализатора Roslyn для раннего возвращения, если анализируемый код находится в путях Assets/ThirdParty или Assets/Legacy:

private static void AnalyzeInvocation(SyntaxNodeAnalysisContext context)
{
    var invocation = (InvocationExpressionSyntax)context.Node;

    if (!(invocation.Expression is MemberAccessExpressionSyntax memberAccess))
        return;

    // Match calls where the method name is "Log"
    if (memberAccess.Name.Identifier.Text != "Log")
        return;

    // Verify the symbol belongs to UnityEngine.Debug
    var symbolInfo = context.SemanticModel.GetSymbolInfo(memberAccess);
    if (!(symbolInfo.Symbol is IMethodSymbol methodSymbol))
        return;

    var containingType = methodSymbol.ContainingType;
    if (containingType?.ToDisplayString() != "UnityEngine.Debug")
        return;

    // Early out for exempt folders
    var location = invocation.GetLocation();
    var tree = location.SourceTree;
    if (tree == null)
        return;

    var filePath = tree.FilePath ?? string.Empty;

    if (IsInExemptPath(filePath))
        return;

    var diagnostic = Diagnostic.Create(Rule, memberAccess.GetLocation());
    context.ReportDiagnostic(diagnostic);
}

private static bool IsInExemptPath(string filePath)
{
    if (string.IsNullOrEmpty(filePath))
        return false;

    var normalized = filePath.Replace('\\', '/');

    return normalized.IndexOf("/Assets/Legacy/", System.StringComparison.OrdinalIgnoreCase) >= 0
        || normalized.IndexOf("/Assets/ThirdParty/", System.StringComparison.OrdinalIgnoreCase) >= 0;
}

В качестве альтернативы вы можете использовать файл editorconfig для централизации исключений. Например, следующий файл .editorconfig в корне проекта изменяет предупреждение EX0001, созданное в примере Создание и использование анализатора Roslyn, на ошибку:

root = true

[*.cs]
# Set EX0001 to error
dotnet_diagnostic.EX0001.severity = error

Дополнительные ресурсы