CA2252: A funkciók előzetes verziójának használata előtt

Tulajdonság	Érték
Szabályazonosító	CA2252
Cím	A funkciók előzetes verzióban való használata előtt
Kategória	Használat
A javítás kompatibilitástörő vagy nem törik	Nem törés
Alapértelmezés szerint engedélyezve a .NET 8-ban	Hibaként

Ok

Az ügyfél előzetes verziójú API-kat vagy típusokat használ a szerelvényben anélkül, hogy kifejezetten helyileg, vagy a modul vagy a szerelvény szintjén döntene.

Szabály leírása

Az attribútummal RequiresPreviewFeaturesAttribute dekorált API vagy szerelvény használata esetén ez a szabály ellenőrzi, hogy a híváswebhely engedélyezte-e az előzetes verziójú funkciók használatát. Egy híváswebhely engedélyezte az előzetes verziójú funkciókat, ha az alábbiak valamelyike érvényes:

• Ez egy széljegyzet hatókörén RequiresPreviewFeaturesAttribute belül van.
• Ez egy olyan szerelvény vagy modul része, amely már engedélyezte az előzetes verziójú funkciók használatát.

Az alábbi képen a CA2252 diagnosztikára vonatkozó példa látható.

Itt található egy előzetes verziótípus, Lib amely a Main metódusban van létrehozva. Main a rendszer nem jegyzeteli meg előzetes metódusként, ezért a két konstruktorhíváson Maindiagnosztikát hoznak létre.

Szabálysértések kijavítása

A szabálysértések kétféleképpen oldhatóak meg:

• Hozzon létre egy híváswebhelyet egy széljegyzet hatókörébe, ha a szülőjét a következővel RequiresPreviewFeaturesAttributejegyzeteli: . Az előző példában APreviewMethod az attribútum megjegyzést RequiresPreviewFeatures ad, így az elemző figyelmen kívül hagyja az előnézeti típus használatát.APreviewMethod Ebből következik, hogy a hívóknak APreviewMethod hasonló gyakorlatot kell végrehajtaniuk.

• A funkciók előnézetét szerelvény- vagy modulszinten is választhatja. Ez azt jelzi az elemzőnek, hogy a szerelvény előzetes típushasználata kívánatos, és ennek következtében ez a szabály nem okoz hibákat. Ez az előzetes verziójú függőségek használata előnyben részesített módja. Az előzetes verziójú funkciók teljes szerelvényen belüli engedélyezéséhez állítsa be az EnablePreviewFeatures tulajdonságot egy .csproj fájlban:

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

Mikor kell letiltani a figyelmeztetéseket?

A szabály figyelmeztetéseinek mellőzése csak olyan speciális használati esetekben ajánlott, ahol az API-kon végzett diagnosztikát explicit módon le kell tiltani. Ebben az esetben vállalnia kell az előzetes verziójú API-k megfelelő megjelölésének felelősségét. Vegyük például azt az esetet, amikor egy meglévő típus új előnézeti felületet implementál. Mivel a teljes típus nem jelölhető meg előnézetként (visszamenőleges kompatibilitás esetén), a típusdefiníció körüli diagnosztikát helyileg le lehet tiltani. Emellett meg kell jelölnie az előnézeti felület implementációit előzetes verzióként. A meglévő típus már használható a korábbiakhoz hasonlóan, de az új felületi metódusok hívásai diagnosztikát kapnak. A System.Private.CoreLib.csproj ezzel a technikával általános matematikai funkciókat tesz elérhetővé olyan numerikus típusok esetében, mint Int32a , Doubleés Decimal.

Az alábbi képeken a CA2252-elemző helyi letiltása látható.

Megjegyzés:

Ha az alábbiak mindegyike érvényes, a szabály tévesen pozitív figyelmeztetéseket jeleníthet meg:

• A Visual Studio 2022 17.5-ös vagy újabb verzióját használja a .NET SDK egy régebbi verziójával, vagyis a .NET 6-os vagy korábbi verziójával.
• A .NET 6 SDK-ból származó elemzőket vagy az elemzőcsomagok egy régebbi verzióját használja, például a Microsoft.CodeAnalysis.FxCopAnalyzerst.

Ebben az esetben nyugodtan el lehet tiltani egy hamis pozitív figyelmeztetést. A hamis pozitív értékek a C#-fordító kompatibilitástörő változásának köszönhetők. Fontolja meg egy újabb elemző használatát, amely tartalmazza a hamis pozitív figyelmeztetések javítását. Frissítsen a Microsoft.CodeAnalysis.NetAnalyzers 7.0.0-preview1.22464.1-es vagy újabb verziójára, vagy használja a .NET 7 SDK elemzőit.

Figyelmeztetés mellőzése

Ha csak egyetlen szabálysértést szeretne letiltani, adjon hozzá előfeldolgozási irányelveket a forrásfájlhoz a szabály letiltásához és újbóli engedélyezéséhez.

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

Ha le szeretné tiltani egy fájl, mappa vagy projekt szabályát, állítsa annak súlyosságát none a konfigurációs fájlban.

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

A teljes szabálykategória letiltásához állítsa be a kategória súlyosságát none a konfigurációs fájlban.

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

További információ: Kódelemzési figyelmeztetések letiltása.

Kapcsolódó információk

• EnablePreviewFeatures és GenerateRequiresPreviewFeaturesAttribute
• Előzetes verziójú funkciótervező dokumentum