Anpassa Roslyn-analysatorregler

Varje Roslyn-analysregel, eller diagnostik, har ett standardtillstånd för allvarlighetsgrad och undertryckning som du kan anpassa för projektet. Den här artikeln beskriver hur du ställer in allvarlighetsgrad för analysverktyg och undertrycker överträdelser av analysverktyg.

Allvarlighetsgrad

Du kan konfigurera allvarlighetsgraden för analysregler i en EditorConfig-fil och från glödlampans meny.

I följande tabell visas de olika allvarlighetsalternativ som du kan konfigurera för en diagnostik:

Allvarlighetsgrad (Solution Explorer)	Allvarlighetsgrad (EditorConfig-fil)	Byggtidsbeteende	Redigeringsbeteende
Fel	error	Överträdelser visas på fliken Fel i fönstret Fellista och i kommandoradsversionens utdata och gör att byggen misslyckas.	Den felaktiga koden understryks med en röd vågrät linje och markeras med en liten röd ruta i rullningslisten.
Varning	warning	Överträdelser visas på fliken Varning i fönstret Fellista och i kommandoradsversionens utdata, men gör inte att byggen misslyckas.	Den felaktiga koden understryks med en grön vågrät linje och markeras med en liten grön ruta i rullningslisten.
Förslag	suggestion	Överträdelser visas på fliken Meddelande i fönstret Fellista men inte i kommandoradens byggutdata.	Den berörda koden understryks med en grå vågrät linje och markeras med en liten grå ruta i rullningslisten.
I bakgrunden	silent	Osynlig för användaren.	Osynlig för användaren, men diagnostiken rapporteras till IDE-diagnostikmotorn.
Ingen	none	Fullständigt undertryckt.	Fullständigt undertryckt.
Förinställning	default	Motsvarar regelns standard allvarlighetsgrad. Om du vill fastställa standardvärdet för en regel kan du visa fönstret Egenskaper.	Motsvarar regelns standard allvarlighetsgrad.

Visa regelöverträdelser

Om en analysator hittar några överträdelser av analysregeln rapporterar den dem i fönstret Fellista och i kodredigeraren.

Följande skärmbild visar regelöverträdelser som rapporterats i fönstret Fellista . De överträdelser av analyseraren som rapporteras i fellistan matchar allvarlighetsgradsinställningen för regeln:

Överträdelser av analysregler visas också i kodredigeraren som vågiga linjer under den anstötliga koden. Följande skärmbild visar till exempel tre överträdelser: ett fel (röd vågrät linje), en varning (grön vågrät linje) och ett förslag (tre grå punkter):

Många diagnostiker har en eller flera associerade kodkorrigeringar som du kan tillämpa för att korrigera regelöverträdelsen. Kodkorrigeringar visas i menyn med glödlampans ikon tillsammans med andra typer av snabbåtgärder. Mer information om kodkorrigeringar finns i Vanliga snabbåtgärder.

Konfigurera allvarlighetsnivåer

Du kan ange regelns allvarlighetsgrad med någon av följande metoder:

• EditorConfig
• Meny för glödlampa
• Solution Explorer

Tyst jämfört med ingen allvarlighetsgrad

Silent allvarlighetsgradsregler som är aktiverade som standard skiljer sig från inaktiverade regler eller None allvarlighetsregler:

• Om en kodkorrigering har registrerats för en Silent allvarlighetsgradsregel erbjuder Visual Studio kodkorrigeringen som en kodrefaktoriseringsåtgärd för glödlampa även om den dolda diagnostiken inte är synlig för användaren. Om allvarlighetsgradsregeln är inaktiverad som Noneerbjuds inte kodkorrigeringen.
• Poster som anger allvarlighetsgraden för flera analysregler samtidigt i en EditorConfig-fil kan masskonfigurera Silent allvarlighetsgradsregler. None allvarlighetsreglerna kan inte konfigureras på det här sättet. I stället måste de konfigureras genom poster som anger allvarlighetsgraden för varje regel-ID i en EditorConfig-fil.

Ange allvarlighetsgrad för regeln i en EditorConfig-fil

EditorConfig-filer är tillgängliga i Visual Studio 2019 version 16.3 och senare.

Att ange en regels allvarlighetsgrad i en EditorConfig-fil har företräde framför alla allvarlighetsgrader som anges i en regeluppsättning eller i Solution Explorer. Du kan konfigurera allvarlighetsgraden antingen manuellt i en EditorConfig-fil eller automatiskt via glödlampan som visas bredvid en överträdelse.

Konfigurera regel allvarlighetsgrad manuellt i en EditorConfig-fil

Följ dessa steg för att konfigurera regelns allvarlighetsgrad:

1. Lägg till en EditorConfig-fil i projektet om du inte redan har en.

2. Lägg till en post för varje regel som du vill konfigurera under motsvarande filändelse.

   Exempel: posten för att ställa in allvarlighetsgraden för CA1822 till error för C#-filer är följande:

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

3. Du kan ange regelns allvarlighetsgrad för varje diagnostikregel-ID i en EditorConfig-fil med följande syntax:

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

4. För analysverktyg i IDE-kodstil kan du även konfigurera dem i en EditorConfig-fil med hjälp av en annan syntax.

   Till exempel dotnet_style_qualification_for_field = false:suggestion. Men om du anger en allvarlighetsgrad med hjälp av syntaxen dotnet_diagnostic har den företräde. Mer information finns i Språkkonventioner för EditorConfig.

Ange allvarlighetsgraden för flera analysregler samtidigt i en EditorConfig-fil

Möjligheten att ange flera analysregler samtidigt i en EditorConfig-fil finns i Visual Studio 2019 version 16.5 och senare.

Du kan ange allvarlighetsgraden för en specifik kategori av analysregler eller för alla analysregler med en enda post i en EditorConfig-fil:

• Ange regelns allvarlighetsgrad för en kategori av analysregler:

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

• Ange regelns allvarlighetsgrad för alla analysregler:

  dotnet_analyzer_diagnostic.severity = <severity>

Poster som konfigurerar flera analysregler samtidigt gäller endast för regler som är aktiverade som standard. Analyserregler som är inaktiverade som standard i analyspaketet måste aktiveras via explicita dotnet_diagnostic.<rule ID>.severity = <severity> objekt.

Om du har flera poster som gäller för ett specifikt regel-ID är prioritetsordningen för den tillämpliga posten följande:

• En allvarlighetsgradspost för en enskild regel efter ID har företräde framför en allvarlighetsgradspost för en kategori.
• En allvarlighetsgradspost för en kategori har företräde framför en allvarlighetsgradspost för alla analysregler.

Tänk dig följande EditorConfig-exempel, där CA1822 är en prestandaregel:

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

I det här exemplet gäller alla tre element för prestandaregeln CA1822. Men med de angivna prioritetsreglerna har den första regel-ID-baserade allvarlighetsgraden företräde framför nästa poster. I det här exemplet har CA1822 en effektiv allvarlighetsgrad på error. Återstående prestandaregler har allvarlighetsgraden warning. Analysreglerna som inte är prestandaregler har en allvarlighetsgrad på suggestion.

Ange regelns allvarlighetsgrad från glödlampans meny

Visual Studio erbjuder ett bekvämt sätt att konfigurera en regels allvarlighetsgrad från menyn Snabbåtgärder glödlampemenyn. Följ dessa steg:

1. När en överträdelse har inträffat hovra över överträdelsestrecklinjen i redigeraren och välj Visa potentiella korrigeringar för att öppna glödlampans meny. Du kan också placera markören på raden och trycka på Ctrl+. (punkttecknet).

2. Hovra över en allvarlighetsgrad i menyn glödlampa för en förhandsversion av ändringen och konfigurera sedan allvarlighetsgraden enligt följande alternativ:

   • Konfigurera <allvarlighetsgrad för regel-ID> . Ange allvarlighetsgraden för den specifika regeln.

   • Konfigurera allvarlighetsgrad för alla <formatanalysverktyg> . Ange allvarlighetsgraden för alla regler i den specifika regelkategorin.

   • Konfigurera allvarlighetsgrad för alla analysverktyg. Ange allvarlighetsgraden för alla kategorier av analysregler.

     I följande exempel väljer du Ignorera eller konfigurera problem>Konfigurera <regel-ID> :ts allvarlighetsgrad.

     

3. Välj något av allvarlighetsalternativen.

   

   Visual Studio lägger till en post i EditorConfig-filen för att konfigurera regeln till den begärda allvarlighetsgraden, som visas i förhandsgranskningsrutan.

   Om du inte redan har en EditorConfig-fil i projektet skapar Visual Studio en åt dig.

Ange allvarlighetsgrad för regel från Solution Explorer

Följ dessa steg om du vill ange allvarlighetsgrad för regeln från Solution Explorer:

1. I Solution Explorer expanderardu> (eller beroendeanalysverktyg> för .NET Core-projekt).

2. Expandera sammansättningen som innehåller regeln som du vill ange allvarlighetsgraden för.

3. Högerklicka på regeln och välj Ange allvarlighetsgrad. I snabbmenyn väljer du något av allvarlighetsalternativen.

   Visual Studio lägger till en post i EditorConfig-filen för att konfigurera regeln till den begärda nivån. Om projektet använder en regeluppsättningsfil i stället för en EditorConfig-fil läggs allvarlighetsgradsposten till i regeluppsättningsfilen.

   Om du inte redan har en EditorConfig-fil eller regeluppsättningsfil i projektet skapar Visual Studio en ny EditorConfig-fil åt dig.

Visa analysverktyg och diagnostik från Solution Explorer

Du kan göra mycket av anpassningen av analysdiagnostik från Solution Explorer. Om du installerar en analysator som ett NuGet-paket visas noden Analyzeers under noden Referenser (eller Beroenden för .NET Core-projekt) i Solution Explorer. Följ dessa steg för att visa analysverktygen och diagnostiken:

1. I Solution Explorer expanderar du projektet, expanderar Referenser eller beroenden och expanderar sedan Analysverktyg. Expandera en av analyssammansättningarna för att se diagnostiken i sammansättningen.

   Ikonen bredvid varje diagnostik anger dess allvarlighetsgrad:

   • x i en cirkel anger allvarlighetsgraden Fel
   • ! i en triangel anger allvarlighetsgraden Varning
   • i i en hel cirkel anger allvarlighetsgraden Förslag
   • i i en streckad cirkel anger allvarlighetsgraden Tyst
   • Nedåtriktad pil i en fast cirkel anger allvarlighetsgraden Ingen

   

2. Om du vill visa egenskaperna för en diagnostik, inklusive dess beskrivning och standard allvarlighetsgrad, högerklickar du på diagnostiken och väljer sedan Egenskaper. Eller välj diagnostiken och tryck sedan på Alt+Retur.

   Fönstret Egenskaper visas.

   

3. Om du vill visa egenskaper för kodformatregler (IDE-prefix) i fönstret Egenskaper , till exempel standard allvarlighetsgrad, anger du egenskapen EnforceCodeStyleInBuild till true.

4. Om du vill ha onlinedokumentation för en diagnostik högerklickar du på diagnostiken och väljer sedan Visa hjälp.

Konvertera en befintlig regeluppsättningsfil till en EditorConfig-fil

I Visual Studio 2019 version 16.5 och senare är regeluppsättningsfiler inaktuella till förmån för EditorConfig-filer för analysverktygskonfiguration för hanterad kod. EditorConfig-filer är mer flexibla och gör det möjligt för dig att konfigurera både allvarlighetsgrader för analysregler och analysalternativ, inklusive alternativ för kodformat i Visual Studio IDE. Eftersom allvarlighetsgradskonfigurationen för Visual Studio-verktygen för analysregler nu är optimerade för att fungera med EditorConfig-filer i stället för regeluppsättningsfiler, uppmanas du att konvertera alla befintliga projekt som fortfarande använder regeluppsättningsfiler.

När du konverterar din regeluppsättningsfil till en EditorConfig-fil, sparar du den i roten på ditt repository eller i lösningsmappen. Detta säkerställer att allvarlighetsgradsinställningarna från den här filen automatiskt gäller för hela lagringsplatsen eller lösningen.

Du kan konvertera en befintlig regeluppsättningsfil till en EditorConfig-fil med hjälp av antingen regeluppsättningsredigeraren eller kommandoraden.

Anmärkning

.NET Core- och .NET 5+-projekt stöder inte menykommandon för regeluppsättningar i Solution Explorer, till exempel Öppna aktiv regeluppsättning. Om du vill ange en regeluppsättning som inte är standard för ett .NET Core- eller .NET 5+-projekt lägger du till egenskapen CodeAnalysisRuleSet manuellt i projektfilen. Du kan fortfarande konfigurera reglerna i regeluppsättningen i regeluppsättningsredigeraren.

Följ dessa steg om du vill använda regeluppsättningsredigeraren. Om projektet redan använder en specifik regeluppsättningsfil för dess egenskapsvärde CodeAnalysisRuleSet kan du konvertera den till en motsvarande EditorConfig-fil från regeluppsättningsredigeraren:

1. Dubbelklicka på regeluppsättningsfilen i Solution Explorer.

   Regeluppsättningsfilen öppnas i regeluppsättningsredigeraren med ett klickbart informationsfält längst upp.

   

2. Välj länken i informationsfältet för att migrera redigeringsfilen för regeluppsättningen.

3. I dialogrutan Spara som väljer du den katalog där du vill generera EditorConfig-filen och väljer sedan Spara.

   Den genererade EditorConfig öppnas i redigeraren. Dessutom uppdateras egenskapen CodeAnalysisRuleSet MSBuild i projektfilen så att den inte längre refererar till den ursprungliga regeluppsättningsfilen.

   Den ursprungliga regeluppsättningsfilen kan tas bort från projektet.

   Anmärkning

   I ett .NET Framework-projekt kan standardregeluppsättningsfilen inte migreras eller tas bort från projektet.

Följ dessa steg för att använda kommandoraden:

1. Installera NuGet-paketet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Kör RulesetToEditorconfigConverter.exe från det installerade paketet, med sökvägar till regeluppsättningsfilen och EditorConfig-filen som kommandoradsargument.

   Till exempel:

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

I följande exempel visas en regeluppsättningsfil som ska konverteras till en EditorConfig-fil:

<?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>

I följande exempel visas den resulterande EditorConfig-filen efter konverteringen:

# 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

Konfigurera genererad kod

Analysverktyg körs på källfiler i ett projekt och rapporterar eventuella överträdelser som de hittar. Dessa överträdelser är dock inte användbara för systemgenererade filer. Exempel är genererade kodfiler, till exempel designergenererade kodfiler, tillfälliga källfiler som genereras av byggsystemet och så vidare. För de här typerna av filer kan användarna inte redigera filerna manuellt och bryr sig inte om att åtgärda eventuella överträdelser.

Därför undersöker analysdrivrutinen som standard endast filer med vissa namn, filnamnstillägg eller automatiskt genererade filhuvuden som genererade kodfiler. Ett filnamn som slutar med .designer.cs eller .generated.cs anses till exempel vara genererad kod. Dessa heuristiker kanske dock inte kan identifiera alla anpassade genererade kodfiler i användarens källkod.

I Visual Studio 2019 version 16.5 och senare kan slutanvändarna konfigurera specifika filer och mappar som ska behandlas som genererad kod i en EditorConfig-fil.

Följ dessa steg för att lägga till en sådan konfiguration:

1. Om du inte redan har en EditorConfig-fil för projektet lägger du till en.

2. Lägg till posten generated_code = true | false för specifika filer och mappar. Om du till exempel vill behandla alla filer vars namn slutar med .MyGenerated.cs genererad kod använder du den här posten:

   [*.MyGenerated.cs]
   generated_code = true
   

Förhindra överträdelser

Du kan förhindra regelöverträdelser med hjälp av olika metoder. Mer information finns i Utelämna kodanalysöverträdelser.

Kommandoradsanvändning

När du skapar projektet på kommandoraden visas regelöverträdelser i byggutdata om följande villkor uppfylls:

• Analysverktygen installeras med .NET SDK eller som ett NuGet-paket och inte som ett .vsix-tillägg .

  För analysverktyg som har installerats med .NET SDK kan du behöva aktivera analysverktygen. För kodformat kan du även framtvinga kodformat på versioner genom att ange en MSBuild-egenskap.

• En eller flera regler överträds i projektets kod.

• Allvarlighetsgraden för en regel som brutits är inställd på antingen varning, i vilket fall överträdelser inte orsakar att bygget misslyckas eller fel, i vilket fall överträdelser orsakar att bygget misslyckas.

Utförligheten i build-utdata påverkar inte om regelöverträdelser visas. Även med tyst verbositet visas regelöverträdelser i byggresultatet.

Om du är van vid att köra äldre analys från kommandoraden, antingen med FxCopCmd.exe eller via msbuild med RunCodeAnalysis flaggan, kan du göra det med kodanalysverktyg i stället.

Om du vill se överträdelser av analysverktyg på kommandoraden när du skapar projektet med hjälp av msbuild kör du ett kommando som liknar:

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

Följande skärmbild visar kommandoradsversionens utdata från att skapa ett projekt som innehåller en regelöverträdelse för analysverktyg:

Beroende projekt

Om du lägger till en referens till ett projekt som har NuGet-analysverktyg i ett .NET Core-projekt lägger Visual Studio automatiskt till analysverktygen i det beroende projektet. Om du vill inaktivera det här beteendet (till exempel om det beroende projektet är ett enhetstestprojekt) markerar du NuGet-paketet som privat genom att ange PrivateAssets attributet i filen .csproj eller .vbproj i det refererade projektet:

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

Relaterat innehåll

• Översikt över kodanalyserare i Visual Studio
• Skicka ett kodanalysfel
• Använda regeluppsättningar
• Förhindra kodanalysöverträdelser
• Konfigurationsalternativ för kodanalys