CA2252: Vorschaufeatures vor der Verwendung abonnieren

Artikel
06/05/2023

Eigenschaft	Wert
Regel-ID	CA2252
Titel	Vorschaufeatures vor der Verwendung abonnieren
Kategorie	Verwendung
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert	Als Fehler

Ursache

Ein Client verwendet Vorschau-APIs oder -Typen in seiner Assembly, ohne sie entweder lokal oder auf Modul- oder Assemblyebene explizit zu abonnieren.

Regelbeschreibung

Wenn eine API oder Assembly verwendet wird, die mit dem Attribut RequiresPreviewFeaturesAttribute versehen ist, überprüft diese Regel, ob die Aufrufwebsite Vorschaufeatures abonniert hat. Eine Aufrufwebsite hat Vorschaufeatures abonniert, wenn eine der folgenden Bedingungen erfüllt ist:

Sie befindet sich innerhalb des Bereichs einer RequiresPreviewFeaturesAttribute-Anmerkung.
Sie ist Teil einer Assembly oder eines Moduls, für die bzw. das bereits Vorschaufeatures abonniert wurden.

In der folgenden Abbildung sehen Sie ein Beispiel für die CA2252-Diagnose.

Hier ist Lib ein Vorschautyp, der in der Methode Main erstellt wird. Main selbst ist nicht als Vorschaumethode angemerkt, sodass die Diagnose für die beiden Konstruktoraufrufe innerhalb von Main erstellt wird.

Behandeln von Verstößen

Es gibt zwei Möglichkeiten, Verstöße zu beheben:

Verlegen Sie eine Aufrufsite in den Bereich einer Anmerkung, indem Sie das übergeordnete Element mit der Anmerkung RequiresPreviewFeaturesAttribute versehen. Im vorherigen Beispiel ist APreviewMethod mit dem Attribut RequiresPreviewFeatures versehen, sodass das Analysetool die Verwendung des Vorschautyps in APreviewMethod ignoriert. Daraus folgt, dass Aufrufer von APreviewMethod eine ähnliche Aktion ausführen müssen.
Sie können Vorschaufeatures auch auf Assembly- oder Modulebene abonnieren. Dadurch wird dem Analysetool mitgeteilt, dass die Verwendung des Vorschautyps in der Assembly gewünscht ist. Somit werden von dieser Regel keine Fehler erzeugt. Dies ist die bevorzugte Methode zur Nutzung von Vorschauabhängigkeiten. Um Vorschaufeatures innerhalb der gesamten Assembly zu aktivieren, legen Sie die Eigenschaft EnablePreviewFeatures in einer .csproj-Datei fest:

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

Wann sollten Warnungen unterdrückt werden?

Das Unterdrücken der von dieser Regel generierten Warnungen wird nur für fortgeschrittene Anwendungsfälle empfohlen, in denen die Diagnose für APIs explizit deaktiviert werden muss. In diesem Fall müssen Sie dazu bereit sein, die Verantwortung für die entsprechende Kennzeichnung von Vorschau-APIs zu übernehmen. Stellen Sie sich beispielsweise einen Fall vor, in dem ein vorhandener Typ eine neue Vorschauschnittstelle implementiert. Da nicht der gesamte Typ als Vorschau gekennzeichnet werden kann (aus Gründen der Abwärtskompatibilität), kann die Diagnose für die Typdefinition lokal deaktiviert werden. Darüber hinaus müssen Sie die Implementierungen der Vorschauschnittstelle als Vorschau markieren. Jetzt kann der vorhandene Typ wie zuvor verwendet werden, aber Aufrufe der neuen Schnittstellenmethoden erhalten eine Diagnose. System.Private.CoreLib.csproj verwendet diese Technik, um generische mathematische Features für numerische Typen wie Int32, Double und Decimal verfügbar zu machen.

Die folgenden Abbildungen zeigen, wie Sie das CA2252-Analysetool lokal deaktivieren.

Hinweis

Möglicherweise werden falsch positive Warnungen von dieser Regel angezeigt, wenn alle der folgenden Punkte zutreffen:

Sie verwenden Visual Studio 2022, Version 17.5 oder höher, mit einer älteren Version des .NET SDK, d. h. .NET 6 oder früher.
Sie verwenden die Analysetools aus dem .NET 6 SDK oder einer älteren Version der Analysetoolpakete, z. B. Microsoft. CodeAnalysis.FxCopAnalyzers.

In diesem Fall ist es unproblematisch, eine falsch positive Warnung zu unterdrücken. Die falsch positiven Warnungen sind auf einen Breaking Change im C#-Compiler zurückzuführen. Erwägen Sie die Verwendung von neueren Analysetools, die den Hotfix für falsch positive Warnungen enthalten. Führen Sie ein Upgrade auf Microsoft. CodeAnalysis.NetAnalyzers Version 7.0.0-preview1.22464.1 oder höher aus, oder verwenden Sie die Analysetools aus dem .NET 7 SDK.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Um diese gesamte Kategorie von Regeln zu deaktivieren, legen Sie den Schweregrad für die Kategorie in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Teilen über