Freigeben über

CA2252: Vorschaufunktionen vor der Verwendung aktivieren

Eigenschaft Wert
Regel-ID CA2252
Titel Vorschaufunktionen vor der Nutzung aktivieren
Kategorie Verwendung
Fix führt zu Unterbrechungen oder bleibt funktionsfähig Untrennbar
Standardmäßig in .NET 10 aktiviert Als Fehler betrachtet
Anwendbare Sprachen C# und Visual Basic

Ursache

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

Regelbeschreibung

Wenn eine API oder Assembly verwendet wird, die mit dem Attribut RequiresPreviewFeaturesAttribute versehen ist, überprüft diese Regel, ob die Aufrufstelle die Vorschaufunktionen unterstützt. Ein Aufrufstelle hat Vorschaufunktionen aktiviert, wenn eine der folgenden Bedingungen zutrifft:

  • Sie befindet sich innerhalb des Bereichs einer RequiresPreviewFeaturesAttribute-Anmerkung.
  • Es ist Teil einer Assembly oder eines Moduls, bei denen bereits Vorschaufeatures aktiviert wurden.

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

Code-Editor mit CA2252-Warnung.

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

So beheben Sie Verstöße

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

  • Bringen Sie eine Aufrufstelle in den Geltungsbereich einer Anmerkung, indem Sie das übergeordnete Element mit RequiresPreviewFeaturesAttribute annotieren. 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 der Assembly- oder Modulebene aktivieren. 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 Abhängigkeiten in Vorschauversion. 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 kennzeichnen. Nun kann der bestehende Typ wie zuvor verwendet werden, aber Aufrufe der neuen Schnittstellenmethoden werden diagnostisch überwacht. 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.

CA2252 – Unterdrücken der Diagnose zum Erkennen von Vorschaufeatures

CA2252 – Explizites Markieren von Schnittstellenimplementierungen

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 Fehlalarme 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 auf none in der Konfigurationsdatei fest.

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

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

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

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

Siehe auch

  • Last updated on