CA2252: Aanmelden voor preview-functies voordat u ze gebruikt

Artikel
09/06/2023

Eigenschappen	Weergegeven als
Regel-id	CA2252
Titel	Aanmelden voor preview-functies voordat u ze gebruikt
Categorie	Gebruik
Oplossing is brekend of niet-brekend	Niet-brekend
Standaard ingeschakeld in .NET 9	Als fout

Oorzaak

Een client maakt gebruik van preview-API's of typen in hun assembly zonder expliciet lokaal of op module- of assemblyniveau te kiezen.

Beschrijving van regel

Wanneer een API of assembly die is ingericht met het RequiresPreviewFeaturesAttribute kenmerk wordt gebruikt, controleert deze regel of de aanroepsite heeft gekozen voor preview-functies. Een oproepsite heeft zich aangemeld voor preview-functies als een van de volgende opties van toepassing is:

Het valt binnen het bereik van een RequiresPreviewFeaturesAttribute aantekening.
Het maakt deel uit van een assembly of module die al is aangemeld voor preview-functies.

In de volgende afbeelding ziet u een voorbeeld van de diagnose CA2252.

Lib Hier ziet u een voorbeeldtype dat is samengesteld in de Main methode. Main zelf wordt niet geannoteerd als preview-methode, dus diagnostische gegevens worden geproduceerd op de twee constructorsaanroepen binnen Main.

Schendingen oplossen

Er zijn twee manieren om schendingen op te lossen:

Breng een oproepsite binnen het bereik van een aantekening door aantekeningen te maken bij het bovenliggende item met RequiresPreviewFeaturesAttribute. In het vorige voorbeeld APreviewMethod wordt geannoteerd met het RequiresPreviewFeatures kenmerk, dus de analyse negeert het gebruik van het preview-type binnen APreviewMethod. Hier volgt dat bellers van APreviewMethod een vergelijkbare oefening moeten uitvoeren.
U kunt er ook voor kiezen om preview-functies te bekijken op assembly- of moduleniveau. Dit geeft aan de analyse aan dat het gebruik van het preview-type in de assembly gewenst is en daarom worden er geen fouten geproduceerd door deze regel. Dit is de voorkeursmethode om preview-afhankelijkheden te gebruiken. Als u preview-functies in de hele assembly wilt inschakelen, stelt u de eigenschap EnablePreviewFeatures in een .csproj bestand in:

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

Wanneer waarschuwingen onderdrukken

Het onderdrukken van waarschuwingen van deze regel wordt alleen aanbevolen voor geavanceerde use cases waarbij diagnostische gegevens over API's expliciet moeten worden uitgeschakeld. In dit geval moet u bereid zijn om de verantwoordelijkheid te nemen om preview-API's op de juiste wijze te markeren. Denk bijvoorbeeld aan een geval waarin een bestaand type een nieuwe preview-interface implementeert. Omdat het hele type niet kan worden gemarkeerd als preview (voor compatibiliteit met eerdere versies), kan de diagnose rond de typedefinitie lokaal worden uitgeschakeld. Verder moet u de preview-interface-implementaties markeren als preview. Het bestaande type kan nu net als voorheen worden gebruikt, maar aanroepen naar de nieuwe interfacemethoden krijgen diagnostische gegevens. System.Private.CoreLib.csproj gebruikt deze techniek om algemene wiskundige functies beschikbaar te maken voor numerieke typen, zoals Int32, Doubleen Decimal.

In de volgende afbeeldingen ziet u hoe u de CA2252 Analyzer lokaal uitschakelt.

Notitie

U ziet mogelijk fout-positieve waarschuwingen van deze regel als alle volgende van toepassing zijn:

U gebruikt Visual Studio 2022 versie 17.5 of hoger met een oudere versie van de .NET SDK, dat wil zeggen .NET 6 of eerder.
U gebruikt de analyses van de .NET 6 SDK of een oudere versie van de analysepakketten, zoals Microsoft.CodeAnalysis.FxCopAnalyzers.

In dit geval is het veilig om een fout-positieve waarschuwing te onderdrukken. De fout-positieven zijn te wijten aan een wijziging die fouten veroorzaakt in de C#-compiler. Overweeg om een nieuwere analyse te gebruiken die de oplossing voor de fout-positieve waarschuwingen bevat. Voer een upgrade uit naar Microsoft.CodeAnalysis.NetAnalyzers versie 7.0.0-preview1.22464.1 of hoger of gebruik de analyses van de .NET 7 SDK.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Als u deze hele categorie regels wilt uitschakelen, stelt u de ernst voor de categorie none in op in het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Delen via