CA2252: Välj att förhandsgranska funktioner innan du använder dem

Artikel
09/06/2023

Property	Värde
Regel-ID	CA2252
Title	Välj att förhandsgranska funktioner innan du använder dem
Kategori	Användning
Korrigeringen är icke-bakåtkompatibel	Icke-icke-bryta
Aktiverad som standard i .NET 9	Som fel

Orsak

En klient använder förhandsversions-API:er eller typer i sin sammansättning utan att uttryckligen välja antingen lokalt eller på modul- eller sammansättningsnivå.

Regelbeskrivning

När ett API eller en sammansättning som är dekorerad med RequiresPreviewFeaturesAttribute attributet används kontrollerar den här regeln om anropswebbplatsen har valt att förhandsgranska funktioner. En samtalswebbplats har valt att förhandsgranska funktioner om något av följande gäller:

Det ligger inom omfånget för en RequiresPreviewFeaturesAttribute anteckning.
Det är en del av en sammansättning eller modul som redan har valt att förhandsgranska funktioner.

Följande bild visar ett exempel på CA2252-diagnostiken.

Lib Här är en förhandsgranskningstyp som är konstruerad i Main -metoden. Main i sig är inte kommenterat som en förhandsgranskningsmetod, så diagnostik skapas på de två konstruktoranropen i Main.

Så här åtgärdar du överträdelser

Det finns två sätt att åtgärda överträdelser:

Ta med en anropswebbplats inom omfånget för en anteckning genom att kommentera dess överordnade med RequiresPreviewFeaturesAttribute. I föregående exempel APreviewMethod kommenteras med RequiresPreviewFeatures attributet, så analysatorn ignorerar användning av förhandsgranskningstyp i APreviewMethod. Av detta följer att anropare av APreviewMethod måste utföra en liknande övning.
Du kan också välja att förhandsgranska funktioner på sammansättnings- eller modulnivå. Detta indikerar för analysatorn att användning av förhandsversionstyp i sammansättningen önskas och därför skapas inga fel av den här regeln. Det här är det bästa sättet att använda förhandsgranskningsberoenden. Om du vill aktivera förhandsgranskningsfunktioner i hela sammansättningen anger du egenskapen EnablePreviewFeatures i en .csproj fil:

  <PropertyGroup>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
  </PropertyGroup>

När du ska ignorera varningar

Att ignorera varningar från den här regeln rekommenderas endast för avancerade användningsfall där diagnostik på API:er uttryckligen måste inaktiveras. I det här fallet måste du vara villig att ta på dig ansvaret för att markera förhandsversions-API:er på lämpligt sätt. Tänk dig till exempel ett fall där en befintlig typ implementerar ett nytt förhandsgranskningsgränssnitt. Eftersom hela typen inte kan markeras som förhandsversion (för bakåtkompatibilitet) kan diagnostiken runt typdefinitionen inaktiveras lokalt. Dessutom måste du markera implementeringarna av förhandsgranskningsgränssnittet som förhandsversion. Nu kan den befintliga typen användas som tidigare, men anrop till de nya gränssnittsmetoderna hämtar diagnostik. System.Private.CoreLib.csproj använder den här tekniken för att exponera allmänna matematiska funktioner för numeriska typer som Int32, Doubleoch Decimal.

Följande bilder visar hur du inaktiverar CA2252-analysatorn lokalt.

Kommentar

Du kan se falska positiva varningar från den här regeln om alla följande gäller:

Du använder Visual Studio 2022 version 17.5 eller senare med en äldre version av .NET SDK, dvs. .NET 6 eller tidigare.
Du använder analysverktygen från .NET 6 SDK eller en äldre version av analyspaketen, till exempel Microsoft.CodeAnalysis.FxCopAnalyzers.

I det här fallet är det säkert att undertrycka en falsk positiv varning. Falska positiva identifieringar beror på en icke-bakåtkompatibel ändring i C#-kompilatorn. Överväg att använda en nyare analysator som innehåller korrigeringen för falska positiva varningar. Uppgradera till Microsoft.CodeAnalysis.NetAnalyzers version 7.0.0-preview1.22464.1 eller senare eller använd analysverktygen från .NET 7 SDK.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

#pragma warning disable CA2252
// The code that's violating the rule is on this line.
#pragma warning restore CA2252

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

[*.{cs,vb}]
dotnet_diagnostic.CA2252.severity = none

Om du vill inaktivera hela den här regelkategorin anger du allvarlighetsgraden för kategorin till none i konfigurationsfilen.

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Usage.severity = none

Mer information finns i Så här utelämnar du kodanalysvarningar.

Dela via