Přizpůsobení pravidel analyzátoru Roslyn

Každé pravidlo analyzátoru Roslyn nebo diagnostika má výchozí stav závažnosti a potlačení, který můžete přizpůsobit pro svůj projekt. Tento článek popisuje nastavení závažností analyzátoru a potlačení porušení analyzátoru.

Úrovně závažnosti

V sadě Visual Studio 2019 verze 16.3 a novější můžete nakonfigurovat závažnost pravidel analyzátoru v souboru EditorConfig z nabídky žárovky a v okně Seznam chyb.

Následující tabulka uvádí různé možnosti závažnosti, které můžete nakonfigurovat pro diagnostiku:

Závažnost (Průzkumník řešení)	Závažnost (soubor EditorConfig)	Chování v čase sestavení	Chování editoru
Chyba	error	Porušení se zobrazí na kartě Chyba v okně Seznam chyb a ve výstupu sestavení příkazového řádku a způsobí selhání sestavení.	Off-endový kód je podtržen červenou vlnovkou a označen malým červeným rámečkem na posuvníku.
Upozorňující	warning	Porušení se zobrazí na kartě Upozornění v okně Seznam chyb a ve výstupu sestavení příkazového řádku, ale nezpůsobí selhání sestavení.	Off-endový kód je podtržen zelenou vlnovkou a označen malým zeleným rámečkem na posuvníku.
Návrh	suggestion	Porušení se zobrazí na kartě Zpráva v okně Seznam chyb, ale ne ve výstupu sestavení příkazového řádku.	Ovlivněný kód je podtržen šedou vlnovkou a označen malým šedým rámečkem na posuvníku.
Tichý	silent	Neviditelné pro uživatele.	Neviditelné pro uživatele, ale diagnostika se hlásí diagnostickému modulu IDE.
Nic	none	Potlačeno úplně.	Potlačeno úplně.
Výchozí	default	Odpovídá výchozí závažnosti pravidla. Pokud chcete určit výchozí hodnotu pravidla, podívejte se na její okno Vlastnosti.	Odpovídá výchozí závažnosti pravidla.

Zobrazení porušení pravidel

Pokud analyzátor najde porušení pravidel analyzátoru, nahlásí je v okně Seznam chyb a v editoru kódu.

Následující snímek obrazovky ukazuje porušení pravidel hlášená v okně Seznam chyb. Porušení analyzátoru hlášená v seznamu chyb odpovídají nastavení úrovně závažnosti pravidla:

Porušení pravidel analyzátoru se také zobrazí v editoru kódu jako vlnovky pod kódem pro přesměrování. Na následujícím snímku obrazovky jsou například tři porušení: jedna chyba (červená vlnovka), jedno upozornění (zelená vlnovka) a jeden návrh (tři šedé tečky):

Mnoho diagnostik má jednu nebo více přidružených oprav kódu, které můžete použít k opravě porušení pravidla. Opravy kódu se zobrazují v nabídce ikon žárovky spolu s dalšími typy rychlých akcí. Další informace o opravách kódu najdete v tématu Běžné rychlé akce.

Konfigurace úrovní závažnosti

Závažnost pravidla můžete nastavit pomocí některé z následujících metod:

• EditorConfig
• Nabídka žárovky
• Okno Seznam chyb
• Průzkumník řešení

Bezobslužné vs. Žádná závažnost

Silent Pravidla závažnosti, která jsou ve výchozím nastavení povolená, se liší od zakázaných pravidel nebo None pravidel závažnosti:

• Pokud je oprava kódu zaregistrovaná pro Silent pravidlo závažnosti, Sada Visual Studio nabízí opravu kódu jako akci refaktoringu kódu žárovky, i když není pro uživatele viditelná skrytá diagnostika. Pokud je pravidlo závažnosti zakázané, Noneoprava kódu se nenabízí.
• Položky, které nastavují závažnost více pravidel analyzátoru najednou v souboru EditorConfig, mohou hromadně konfigurovat Silent pravidla závažnosti. None Pravidla závažnosti nelze tímto způsobem nakonfigurovat. Místo toho musí být nakonfigurovány prostřednictvím položek, které nastavují závažnost v souboru EditorConfig pro každé ID pravidla.

Nastavení závažnosti pravidla v souboru EditorConfig

Soubory EditorConfig jsou dostupné v sadě Visual Studio 2019 verze 16.3 a novější.

Nastavení závažnosti pravidla v souboru EditorConfig má přednost před jakoukoli závažností nastavenou v sadě pravidel nebo v Průzkumník řešení. Závažnost můžete nakonfigurovat buď ručně v souboru EditorConfig, nebo automaticky prostřednictvím žárovky, která se zobrazí vedle porušení.

Ruční konfigurace závažnosti pravidla v souboru EditorConfig

Pokud chcete nakonfigurovat závažnost pravidla, postupujte takto:

1. Pokud ho ještě nemáte, přidejte do projektu soubor EditorConfig.

2. Přidejte položku pro každé pravidlo, které chcete nakonfigurovat pod odpovídající příponou souboru.

   Například položka pro nastavení závažnosti pro CA1822 pro error soubory jazyka C# je následující:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Závažnost pravidla pro každé ID diagnostického pravidla v souboru EditorConfig můžete nastavit pomocí následující syntaxe:

   dotnet_diagnostic.<rule ID>.severity = <severity>

4. Pro analyzátory stylu kódu IDE je můžete také nakonfigurovat v souboru EditorConfig pomocí jiné syntaxe.

   Například dotnet_style_qualification_for_field = false:suggestion. Pokud ale pomocí syntaxe nastavíte závažnost dotnet_diagnostic , bude mít přednost. Další informace naleznete v tématu Jazykové konvence pro EditorConfig.

Nastavení závažnosti více pravidel analyzátoru najednou v souboru EditorConfig

Možnost nastavit více pravidel analyzátoru najednou v souboru EditorConfig je k dispozici v sadě Visual Studio 2019 verze 16.5 a novější.

Můžete nastavit závažnost pro konkrétní kategorii pravidel analyzátoru nebo pro všechna pravidla analyzátoru s jedinou položkou v souboru EditorConfig:

• Nastavte závažnost pravidla pro kategorii pravidel analyzátoru:

  dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>

• Nastavte závažnost pravidla pro všechna pravidla analyzátoru:

  dotnet_analyzer_diagnostic.severity = <severity>

Položky, které konfigurují více pravidel analyzátoru najednou, platí jenom pro pravidla, která jsou ve výchozím nastavení povolená. Pravidla analyzátoru, která jsou ve výchozím nastavení v balíčku analyzátoru označená jako zakázaná, musí být povolena prostřednictvím explicitních dotnet_diagnostic.<rule ID>.severity = <severity> položek.

Pokud máte více položek, které platí pro konkrétní ID pravidla, pořadí priorit příslušné položky je následující:

• Položka závažnosti pro jednotlivá pravidla podle ID má přednost před položkou závažnosti pro kategorii.
• Položka závažnosti pro kategorii má přednost před položkou závažnosti pro všechna pravidla analyzátoru.

Podívejte se na následující příklad EditorConfig, kde CA1822 je pravidlo výkonu:

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

V tomto příkladu platí pro pravidlo výkonu CA1822 všechny tři položky. Při použití zadaných pravidel priority má však první položka závažnosti na základě ID pravidla přednost před dalšími položkami. V tomto příkladu má CA1822 účinnou závažnost error. Zbývající pravidla výkonu mají závažnost warning. Pravidla analyzátoru, která nejsou pravidly výkonu, mají závažnost suggestion.

Nastavení závažnosti pravidla z nabídky žárovky

Visual Studio nabízí pohodlný způsob konfigurace závažnosti pravidla z nabídky Žárovka Rychlých akcí . Postupujte následovně:

1. Jakmile dojde k narušení, najeďte myší na vlnovku porušení v editoru a zvolte Zobrazit potenciální opravy a otevřete nabídku žárovky. Nebo umístěte kurzor na čáru a stiskněte ctrl+. (tečka).

2. V nabídce žárovky najeďte myší na úroveň závažnosti pro náhled změny a pak nakonfigurujte závažnost podle následujících možností:

   • Nakonfigurujte <závažnost ID> pravidla. Nastavte závažnost pro konkrétní pravidlo.

   • Nakonfigurujte závažnost pro všechny <analyzátory stylů> . Nastavte závažnost pro všechna pravidla v konkrétní kategorii pravidel.

   • Nakonfigurujte závažnost pro všechny analyzátory. Nastavte závažnost pro všechny kategorie pravidel analyzátoru.

     V následujícím příkladu vyberte Potlačit nebo nakonfigurovat problémy>Konfigurace <závažnosti ID> pravidla.

     

3. Zvolte jednu z možností závažnosti.

   

   Visual Studio přidá do souboru EditorConfig položku pro konfiguraci pravidla na požadovanou úroveň závažnosti, jak je znázorněno v poli Náhled.

   Pokud v projektu ještě nemáte soubor EditorConfig, Visual Studio ho vytvoří za vás.

Nastavení závažnosti pravidla z okna Seznam chyb

Visual Studio také nabízí pohodlný způsob konfigurace závažnosti pravidla z místní nabídky seznamu chyb. Postupujte následovně:

1. Po narušení klikněte pravým tlačítkem myši na položku diagnostiky v seznamu chyb.

2. V místní nabídce vyberte Nastavit závažnost a pak vyberte jednu z možností závažnosti.

   

   Visual Studio přidá do souboru EditorConfig položku pro konfiguraci pravidla na požadovanou úroveň.

   Pokud v projektu ještě nemáte soubor EditorConfig, Visual Studio ho vytvoří za vás.

Nastavení závažnosti pravidla z Průzkumník řešení

Pokud chcete nastavit závažnost pravidla z Průzkumník řešení, postupujte takto:

1. V Průzkumník řešení rozbalte analyzátory odkazů>(nebo analyzátory závislostí> pro projekty .NET Core).

2. Rozbalte sestavení obsahující pravidlo, pro které chcete nastavit závažnost.

3. Klikněte pravým tlačítkem myši na pravidlo a vyberte Nastavit závažnost. V místní nabídce zvolte jednu z možností závažnosti.

   Visual Studio přidá do souboru EditorConfig položku pro konfiguraci pravidla na požadovanou úroveň. Pokud váš projekt místo souboru EditorConfig používá soubor sady pravidel, přidá se do souboru sady pravidel položka závažnosti.

   Pokud v projektu ještě nemáte soubor editorConfig nebo soubor sady pravidel, Visual Studio pro vás vytvoří nový soubor EditorConfig.

Zobrazení analyzátorů a diagnostiky z Průzkumník řešení

Většinu přizpůsobení diagnostiky analyzátoru můžete provádět z Průzkumník řešení. Pokud nainstalujete analyzátor jako balíček NuGet, v Průzkumník řešení se v Průzkumník řešení zobrazí uzel Analyzátory v uzlu Reference (nebo uzel Závislosti pro projekty .NET Core). Při zobrazení analyzátorů a diagnostiky postupujte takto:

1. V Průzkumník řešení rozbalte projekt, rozbalte odkazy nebo závislosti a potom rozbalte analyzátory. Rozbalte jedno ze sestavení analyzátoru, abyste viděli diagnostiku v sestavení.

   Ikona vedle každé diagnostiky označuje její úroveň závažnosti:

   • x v kruhu označuje závažnost chyby.
   • ! v trojúhelníku označuje závažnost upozornění.
   • i v pevném kruhu označuje závažnost návrhu .
   • i v tečkované kruhové znaméně závažnost Tiché
   • Šipka směřující dolů v plném kruhu označuje závažnost Žádné

   

2. Pokud chcete zobrazit vlastnosti diagnostiky, včetně popisu a výchozí závažnosti, klikněte pravým tlačítkem myši na diagnostiku a vyberte Vlastnosti. Nebo vyberte diagnostiku a stiskněte klávesu Alt+Enter.

   Zobrazí se okno Vlastnosti .

   

3. Chcete-li zobrazit vlastnosti pravidel stylu kódu (předpona IDE) v okně Properties, například výchozí závažnost, nastavte EnforceCodeStyleInBuild vlastnost na true.

4. V případě online dokumentace k diagnostice klikněte pravým tlačítkem myši na diagnostiku a pak vyberte Zobrazit nápovědu.

Převod existujícího souboru sady pravidel na soubor EditorConfig

V sadě Visual Studio 2019 verze 16.5 a novějších jsou soubory sad pravidel zastaralé ve prospěch souborů EditorConfig pro konfiguraci analyzátoru pro spravovaný kód. Soubory EditorConfig jsou flexibilnější a umožňují konfigurovat závažnosti pravidel analyzátoru i možnosti analyzátoru, včetně možností stylu kódu ide sady Visual Studio. Vzhledem k tomu, že nástroje sady Visual Studio pro konfiguraci závažnosti pravidel analyzátoru jsou teď optimalizované tak, aby fungovaly se soubory EditorConfig místo souborů sady pravidel, doporučujeme převést všechny existující projekty, které stále používají soubory sady pravidel.

Při převodu existujícího souboru sady pravidel na soubor EditorConfig ho uložte do kořenového adresáře úložiště nebo do složky řešení. Tím zajistíte, aby se nastavení závažnosti tohoto souboru automaticky použilo pro celé úložiště nebo řešení.

Existující soubor sady pravidel můžete převést na soubor EditorConfig pomocí editoru sady pravidel nebo příkazového řádku.

Poznámka:

Projekty .NET Core a .NET Standard nepodporují příkazy nabídky pro sady pravidel v Průzkumník řešení, například Otevřít sadu aktivních pravidel. Chcete-li zadat jiné než výchozí sadu pravidel pro projekt .NET Core nebo .NET Standard, přidejte do souboru projektu vlastnost CodeAnalysisRuleSet ručně. Pravidla v sadě pravidel můžete pořád konfigurovat v editoru sad pravidel.

Pokud chcete použít editor sad pravidel, postupujte takto. Pokud váš projekt už pro jeho CodeAnalysisRuleSet hodnotu vlastnosti používá určitý soubor sady pravidel, můžete ho z editoru sady pravidel převést na ekvivalentní soubor EditorConfig:

1. Poklikejte na soubor sady pravidel v Průzkumník řešení.

   Soubor sady pravidel se otevře v editoru sad pravidel s informačním panelem, na který se dá kliknout v horní části.

   

2. Výběrem odkazu na informační panel migrujte soubor editoru sady pravidel.

3. V dialogovém okně Uložit jako vyberte adresář, do kterého chcete vygenerovat soubor EditorConfig, a pak vyberte Uložit.

   Vygenerovaný EditorConfig se otevře v editoru. Kromě toho, MSBuild vlastnost CodeAnalysisRuleSet je aktualizována v souboru projektu tak, aby již odkazovat na původní soubor sady pravidel.

Pokud chcete použít příkazový řádek, postupujte takto:

1. Nainstalujte balíček NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Spusťte RulesetToEditorconfigConverter.exe z nainstalovaného balíčku s cestami k souboru sady pravidel a souboru EditorConfig jako argumenty příkazového řádku.

   Příklad:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

Následující příklad ukazuje soubor sady pravidel, který se má převést na soubor EditorConfig:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

Následující příklad ukazuje výsledný soubor EditorConfig po převodu:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Konfigurace vygenerovaného kódu

Analyzátory běží na zdrojových souborech v projektu a hlásí všechna porušení, která najdou. Tato porušení ale nejsou užitečná pro systémem generované soubory. Příkladem jsou vygenerované soubory kódu, například soubory kódu generované návrhářem, dočasné zdrojové soubory vygenerované systémem sestavení atd. U těchto typů souborů uživatelé nemůžou soubory ručně upravovat a nemají obavy o opravu jakýchkoli porušení.

Ovladač analyzátoru proto ve výchozím nastavení zkoumá pouze soubory s určitými názvy, příponami souborů nebo automaticky vygenerovanými hlavičkami souboru jako vygenerovanými soubory kódu. Například název souboru končící .designer.cs nebo .generated.cs se považuje za vygenerovaný kód. Tyto heuristiky ale nemusí být schopné identifikovat všechny vlastní vygenerované soubory kódu ve zdrojovém kódu uživatele.

V sadě Visual Studio 2019 verze 16.5 a novějších můžou koncoví uživatelé nakonfigurovat konkrétní soubory a složky, které se mají považovat za vygenerovaný kód v souboru EditorConfig.

Pokud chcete přidat takovou konfiguraci, postupujte takto:

1. Pokud ještě nemáte soubor EditorConfig pro váš projekt, přidejte ho.

2. generated_code = true | false Přidejte položku pro konkrétní soubory a složky. Pokud chcete například zacházet se všemi soubory, jejichž název končí .MyGenerated.cs jako vygenerovaný kód, použijte tuto položku:

   [*.MyGenerated.cs]
   generated_code = true
   

Potlačení porušení

Porušení pravidel můžete potlačit různými metodami. Informace naleznete v tématu Potlačení porušení analýzy kódu.

Použití příkazového řádku

Při sestavování projektu na příkazovém řádku se ve výstupu sestavení zobrazí porušení pravidel, pokud jsou splněny následující podmínky:

• Analyzátory se instalují se sadou .NET SDK nebo jako balíček NuGet, a ne jako rozšíření .vsix .

  U analyzátorů nainstalovaných pomocí sady .NET SDK možná budete muset povolit analyzátory. U stylů kódu můžete také vynutit styly kódu v buildech nastavením vlastnosti MSBuild.

• V kódu projektu se porušuje jedno nebo více pravidel.

• Úroveň závažnosti porušení pravidla je nastavená buď na upozornění, v takovém případě porušení nezpůsobí selhání sestavení nebo chybu, v takovém případě porušení způsobí selhání sestavení.

Úroveň podrobností výstupu sestavení nemá vliv na to, jestli se zobrazují porušení pravidel. I s tichou podrobností se porušení pravidel zobrazí ve výstupu sestavení.

Pokud jste zvyklí na spouštění starší analýzy z příkazového řádku, a to buď pomocí FxCopCmd.exe , nebo pomocí nástroje msbuild s RunCodeAnalysis příznakem, můžete to udělat pomocí analyzátorů kódu.

Pokud chcete zobrazit porušení analyzátoru na příkazovém řádku při sestavování projektu pomocí nástroje msbuild, spusťte příkaz podobný následujícímu:

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

Následující snímek obrazovky ukazuje výstup sestavení příkazového řádku z sestavení projektu, který obsahuje porušení pravidla analyzátoru:

Závislé projekty

Pokud v projektu .NET Core přidáte odkaz na projekt, který obsahuje analyzátory NuGet, Visual Studio tyto analyzátory automaticky přidá do závislého projektu. Chcete-li toto chování zakázat (například pokud závislý projekt je projekt testování jednotek), označte balíček NuGet jako soukromý nastavením PrivateAssets atributu v souboru .csproj nebo .vbproj odkazovaného projektu:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Související obsah

• Přehled analyzátorů kódu v sadě Visual Studio
• Odeslání chyby analyzátoru kódu
• Použití sad pravidel
• Potlačení porušení analýzy kódu
• Možnosti konfigurace pro analýzu kódu