Использование анализаторов RoslynUse Roslyn analyzers

Правила анализатора .NET compiler Platform («Roslyn»), или диагностики, анализ кода C# или Visual Basic при вводе..NET Compiler Platform ("Roslyn") analyzer rules, or diagnostics, analyze your C# or Visual Basic code as you type. Каждый диагностическое событие имеет состояние серьезности и подавления по умолчанию, которое может быть перезаписан для вашего проекта.Each diagnostic has a default severity and suppression state that can be overwritten for your project. В этой статье рассматриваются важность правила параметр, с помощью наборов правил и подавление нарушений.This article covers setting rule severity, using rule sets, and suppressing violations.

Анализаторы в обозревателе решенийAnalyzers in Solution Explorer

Можно сделать, большая часть настройки анализатора диагностики из обозревателе решений.You can do much of the customization of analyzer diagnostics from Solution Explorer. Если вы установить анализаторы как пакет NuGet, анализаторы узел отображается в узле ссылки или зависимости узел в Обозреватель решений.If you install analyzers as a NuGet package, an Analyzers node appears under the References or Dependencies node in Solution Explorer. Если развернуть анализаторыи затем разверните одну из сборок анализатора, вы увидите все средства диагностики в сборке.If you expand Analyzers, and then expand one of the analyzer assemblies, you see all the diagnostics in the assembly.

Анализаторы узел в обозревателе решений

Можно просмотреть свойства диагностики, в том числе его описание, уровень серьезности по умолчанию, в свойства окна.You can view the properties of a diagnostic, including its description and default severity, in the Properties window. Чтобы просмотреть свойства, щелкните правой кнопкой мыши правило и выберите свойства, или выберите правило и нажмите клавишу Alt+ввод.To view the properties, right-click on the rule and select Properties, or select the rule and then press Alt+Enter.

Свойства диагностики в окно "Свойства"

Чтобы просмотреть электронную документацию по для диагностики, щелкните правой кнопкой мыши на диагностику и выберите Просмотр справки.To see online documentation for a diagnostic, right-click on the diagnostic and select View Help.

Значки возле каждого средства диагностики в обозревателе решений соответствует значку, вы увидите в набор при открытии в редакторе правил:The icons next to each diagnostic in Solution Explorer correspond to the icons you see in the rule set when you open it in the editor:

  • Указывает, «i» в кружке серьезность из Infothe "i" in a circle indicates a severity of Info
  • «!» в треугольника указывает серьезность из предупреждениеthe "!" in a triangle indicates a severity of Warning
  • «x» в круг означает серьезность из ошибкиthe "x" in a circle indicates a severity of Error
  • Указывает, «i» в круге на фоне светлый серьезность из Hiddenthe "i" in a circle on a light-colored background indicates a severity of Hidden
  • стрелку вниз в кружке указывает, что диагностики отключеноthe downward-pointing arrow in a circle indicates that the diagnostic is suppressed

Диагностика значки в обозревателе решений

Наборы правилRule sets

Объект набор правил — XML-файл, который хранит состояние серьезности и подавлением для отдельного диагностики.A rule set is an XML file that stores the severity and suppression state for individual diagnostics.

Note

Наборы правил можно включить правила анализа статического кода (двоичный) и анализаторов Roslyn.Rule sets can include rules from both static (binary) code analysis and Roslyn analyzers.

Чтобы изменить активный набор правил в редакторе набора правил, щелкните правой кнопкой мыши ссылки > анализаторы узел в обозревателе решений и выберите Открыть активный набор правил.To edit the active rule set in the rule set editor, right-click on the References > Analyzers node in Solution Explorer and select Open Active Rule Set. Если это при первом изменении набор правил, Visual Studio создается копия правила по умолчанию задать файл, присваивает ему <имя_проекта > .rulesetи добавляет его в проект.If this is the first time you're editing the rule set, Visual Studio makes a copy of the default rule set file, names it <projectname>.ruleset, and adds it to your project. Этот набор также настраиваемых правил становится активный набор правил для проекта.This custom rule set also becomes the active rule set for your project.

Чтобы изменить активный набор правил для проекта, перейдите к анализа кода вкладки свойств проекта.To change the active rule set for a project, navigate to the Code Analysis tab of a project's properties. Выберите набор в списке правил выполнить этот набор правил.Select the rule set from the list under Run this rule set. Чтобы открыть набор правил, выберите откройте.To open the rule set, select Open.

Note

Проекты .NET core и .NET Standard не поддерживают команды меню для наборов правил в обозревателе решений, например открыть активный набор правил..NET Core and .NET Standard projects do not support the menu commands for rule sets in Solution Explorer, for example, Open Active Rule Set. Чтобы указать нестандартный набор правил для проекта .NET Core или .NET Standard, вручную добавить CodeAnalysisRuleSet свойство к файлу проекта.To specify a non-default rule set for a .NET Core or .NET Standard project, manually add the CodeAnalysisRuleSet property to the project file. Можно настроить правила в набор правил в Visual Studio пользовательский Интерфейс редактора набора правил.You can still configure the rules within the rule set in the Visual Studio rule set editor UI.

Важность правилRule severity

Можно настроить уровень серьезности правил анализатора или диагностики, если вы установить анализаторы как пакет NuGet.You can configure the severity of analyzer rules, or diagnostics, if you install the analyzers as a NuGet package. В следующей таблице показаны параметры серьезности для диагностики:The following table shows the severity options for diagnostics:

СерьезностьSeverity Поведение во время сборкиBuild-time behavior Поведение редактораEditor behavior
ErrorError Нарушения отображаются как ошибки в список ошибок командной строки в выходные данные сборки и привести к сбою сборки.Violations appear as Errors in the Error List and in command-line build output, and cause builds to fail. Код, вызвавший ошибку, подчеркнута с красной волнистой и помеченный атрибутом небольшой красный квадрат в полосе прокрутки.Offending code is underlined with a red squiggly, and marked by a small red box in the scroll bar.
ПредупреждениеWarning Нарушения отображаются как предупреждения в список ошибок и командной строки в выходные данные сборки, но не приводят к сбою сборки.Violations appear as Warnings in the Error List and in command-line build output, but do not cause builds to fail. Код, вызвавший ошибку, подчеркнута с зеленой волнистой и помеченный атрибутом небольшой зеленой рамкой на полосе прокрутки.Offending code is underlined with a green squiggly, and marked by a small green box in the scroll bar.
InfoInfo Нарушения отображаются как сообщений в список ошибоки совсем не в выходных данных построения из командной строки.Violations appear as Messages in the Error List, and not at all in command-line build output. Код, вызвавший ошибку, подчеркнута серым, волнистой и помеченный атрибутом небольшое серое поле в полосе прокрутки.Offending code is underlined with a gray squiggly, and marked by a small gray box in the scroll bar.
HiddenHidden Невидимые для пользователя.Non-visible to user. Невидимые для пользователя.Non-visible to user. Диагностические тем не менее передаются в подсистему диагностики интегрированной среды разработки.The diagnostic is reported to the IDE diagnostic engine, however.
NoneNone Полностью подавить.Suppressed completely. Полностью подавить.Suppressed completely.

Кроме того, вы можете «сбросить» важность правила при установке для него по умолчанию.In addition, you can "reset" a rule's severity by setting it to Default. Каждый диагностическое событие имеет уровень серьезности по умолчанию, который можно увидеть в свойства окна.Each diagnostic has a default severity that can be seen in the Properties window.

На следующем рисунке показаны три различных диагностических нарушений в редакторе кода с тремя разными уровнями серьезности.The following screenshot shows three different diagnostic violations in the code editor, with three different severities. Обратите внимание, что цвет волнистой, а также небольшое поле в полосе прокрутки в правой части.Notice the color of the squiggly, as well as the small box in the scroll bar on the right.

Ошибки, предупреждения и сведения о нарушение в редакторе кода

На следующем рисунке показан же трех нарушений, как они указаны в список ошибок:The following screenshot shows the same three violations as they appear in the Error List:

Ошибки, предупреждения и сведения о нарушение в списке ошибок

Можно изменить уровень серьезности правила обозревателе решений, или в <имя_проекта > .ruleset файл, который добавляется в решение после изменения серьезность правила в Обозреватель решений.You can change the severity of a rule from Solution Explorer, or within the <projectname>.ruleset file that is added to the solution after you change the severity of a rule in Solution Explorer.

Файл набора правил в обозревателе решений

Серьезность набора правил из обозревателя решенийSet rule severity from Solution Explorer

  1. В обозревателе решений, разверните ссылки > анализаторы (зависимости > Анализаторы для проектов .NET Core).In Solution Explorer, expand References > Analyzers (Dependencies > Analyzers for .NET Core projects).

  2. Разверните сборку, которая содержит правило, которое нужно задать уровень серьезности для.Expand the assembly that contains the rule you want to set severity for.

  3. Щелкните правой кнопкой мыши правило и выберите установить серьезность набора правил.Right-click on the rule and select Set Rule Set Severity. В выпадающем меню выберите один из параметров уровень серьезности.In the fly-out menu, select one of the severity options.

    Серьезность правила сохраняется в файле набора правил active.The severity for the rule is saved in the active rule set file.

Серьезность набора правил в файл набора правилSet rule severity in the rule set file

  1. Откройте набор правил файл, дважды щелкнув его в обозревателе решений, выбрав открыть активный набор правил в меню щелкните правой кнопкой мыши анализаторы узла, либо выбрав откройте на анализа кода страницу свойств для проекта.Open the rule set file by double-clicking it in Solution Explorer, selecting Open Active Rule Set on the right-click menu of the Analyzers node, or by selecting Open on the Code Analysis property page for the project.

  2. Перейдите к правилу, развернув его соответствующая сборка.Browse to the rule by expanding its containing assembly.

  3. В действие столбец, выберите значение для открытия раскрывающегося списка и выберите нужный уровень серьезности в списке.In the Action column, select the value to open a drop-down list, and select the desired severity from the list.

    Откройте в редакторе файл набора правил

Подавлять нарушенийSuppress violations

Существует несколько способов для подавления нарушения правил:There are multiple ways to suppress rule violations:

  • Из анализ менюFrom the Analyze menu

    Выберите анализ > выполнить анализ кода и подавить активные проблемы в строке меню, чтобы отключить все текущие нарушения.Select Analyze > Run Code Analysis and Suppress Active Issues on the menu bar to suppress all current violations. Иногда это называется «задание базовых показателей».This is sometimes referred to as "baselining".

  • Из обозревателе решенийFrom Solution Explorer

    Можно отключить в обозревателе решений, равным важность правила None.To suppress a violation in Solution Explorer, set the rule's severity to None.

  • Из редактор набора правилFrom the rule set editor

    Можно отключить в редакторе набора правил, снимите флажок рядом с его именем или задать действие для None.To suppress a violation from the rule set editor, uncheck the box next to its name or set Action to None.

  • Из редактор кодаFrom the code editor

    Можно отключить в редакторе кода, поместите курсор в строку кода с нарушением и нажмите клавишу Ctrl+ .To suppress a violation from the code editor, place the cursor in the line of code with the violation and press Ctrl+. Чтобы открыть Быстрые действия меню.to open the Quick Actions menu. Выберите подавлять CAXXXX > в источнике или в файле блокируемых предупреждений.Select Suppress CAXXXX > in Source/in Suppression File.

    Отключение диагностики из меню быстрых действий

  • Из список ошибокFrom the Error List

    Вы можете отключить диагностику один или несколько из список ошибок , выбрав те, которые вы хотите отключить, и щелкните правой кнопкой мыши и выбрав подавлять > Source/In в Файл подавления.You can suppress one or many diagnostics from the Error List by selecting the ones you want to suppress, and then right-clicking and selecting Suppress > In Source/In Suppression File.

    • Если Вы запрещаете в исходном, Просмотр изменений откроется диалоговое окно, отображается предварительный просмотр C# #pragma warning или Visual Basic #Disable Предупреждение директива, которая добавляется к исходному коду.If you suppress In Source, the Preview Changes dialog opens and shows a preview of the C# #pragma warning or Visual Basic #Disable warning directive that's added to the source code.

      Предварительная версия добавления #pragma warning в файле кода

    • При выборе в файле блокируемых предупреждений, Просмотр изменений откроется диалоговое окно, отображается предварительный просмотр SuppressMessageAttribute атрибут, который добавляется файл глобального подавления.If you select In Suppression File, the Preview Changes dialog opens and shows a preview of the SuppressMessageAttribute attribute that's added to the global suppressions file.

      Предварительный просмотр файла подавления при добавлении атрибута SuppressMessage

    В Просмотр изменений диалоговом окне выберите применить.In the Preview Changes dialog, select Apply.

    Note

    Если вы не видите подавлять пункт меню в обозревателе решений, нарушение, весьма вероятно, появятся из сборки и не оперативный анализ.If you don't see the Suppress menu option in Solution Explorer, the violation is likely coming from build and not live analysis. Список ошибок отображает диагностики или правило нарушений, как динамический анализ кода и сборки.The Error List displays diagnostics, or rule violations, from both live code analysis and build. Поскольку диагностика сборки может быть устаревшим, например, если вы закончили редактировать код, чтобы устранить нарушение, но не восстановлена, невозможно закрыть эти диагностические из список ошибок.Since the build diagnostics can be stale, for example, if you've edited the code to fix the violation but haven't rebuilt, you cannot suppress these diagnostics from the Error List. Диагностику из динамического анализа или IntelliSense, всегда актуальны, с помощью актуальных источников и могут исключаться из список ошибок.Diagnostics from live analysis, or IntelliSense, are always up-to-date with current sources and can be suppressed from the Error List. Чтобы исключить построения переключения диагностики из вашего выбора список ошибок Фильтр источника из сборка и IntelliSense для Intellisense только.To exclude build diagnostics from your selection, switch the Error List source filter from Build + IntelliSense to Intellisense Only. Выберите диагностики, который вы хотите отключить и выполнить действия, описанные ранее.Then, select the diagnostics you want to suppress and proceed as described previously.

    Фильтр источника списка ошибок в Visual Studio

Использование командной строкиCommand-line usage

При построении проекта в командной строке, нарушения правил отображаются в выходных данных сборки, при соблюдении следующих условий:When you build your project at the command line, rule violations appear in the build output if the following conditions are met:

  • Анализаторы устанавливаются в виде пакета Nuget, а не как расширение VSIX.The analyzers are installed as a Nuget package and not as a VSIX extension.

  • Одно или несколько правил нарушены в коде проекта.One or more rules are violated in the project's code.

  • Серьезность нарушила правила может принимать значение предупреждение, в этом случае нарушений не приводят к сбою, сборки или ошибка, в этом случае нарушений привести к сбою сборки.The severity of a violated rule is set to either warning, in which case violations don't cause build to fail, or error, in which case violations cause build to fail.

Уровень детализации выходных данных сборки не влияет на отображаются нарушения правил.The verbosity of the build output does not affect whether rule violations are shown. Даже с quiet уровень детализации, нарушения правил отображаются в выходных данных построения.Even with quiet verbosity, rule violations appear in the build output.

Tip

Если вы привыкли выполнения статического анализа кода из командной строки, с помощью FxCopCmd.exe или с помощью msbuild с RunCodeAnalysis флаг, вот как это сделать с помощью анализаторов Roslyn.If you're accustomed to running static code analysis from the command line, either with FxCopCmd.exe or through msbuild with the RunCodeAnalysis flag, here's how to do that with Roslyn analyzers.

Чтобы увидеть нарушения анализатора в командной строке при сборке проекта с помощью msbuild, выполните следующую команду:To see analyzer violations at the command line when you build your project using msbuild, run a command like this:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

На следующем рисунке показано построение из командной строки выходные файлы построения проекта, содержащего нарушений правил анализа:The following image shows the command-line build output from building a project that contains an analyzer rule violation:

Выходные данные MSBuild с нарушением правила

Зависимые проектыDependent projects

В проекте .NET Core при добавлении ссылки в проект, имеющий анализаторов NuGet, эти анализаторы автоматически добавляются в зависимом проекте слишком.In a .NET Core project, if you add a reference to a project that has NuGet analyzers, those analyzers are automatically added to the dependent project too. Чтобы отключить это поведение, например, если зависимый проект модульного теста пометить пакет NuGet в качестве частной в .csproj или .vbproj файл проекта, на который указывает ссылка, задав PrivateAssets атрибут:To disable this behavior, for example if the dependent project is a unit test project, mark the NuGet package as private in the .csproj or .vbproj file of the referenced project by setting the PrivateAssets attribute:

<PackageReference Include="Microsoft.CodeAnalysis.FxCopAnalyzers" Version="2.9.0" PrivateAssets="all" />

См. такжеSee also