CA2252: Zrezygnuj z funkcji w wersji zapoznawczej przed ich użyciem

  • Artykuł
Właściwości Wartość
Identyfikator reguły CA2252
Tytuł Przed użyciem funkcji w wersji zapoznawczej
Kategoria Użycie
Poprawka powodująca niezgodność lub niezgodność Niezgodność
Domyślnie włączone na platformie .NET 8 Jako błąd

Przyczyna

Klient korzysta z interfejsów API lub typów w wersji zapoznawczej w zestawie bez jawnego wyrażenia zgody lokalnie lub na poziomie modułu lub zestawu.

Opis reguły

Gdy używany jest interfejs API lub zestaw ozdobiony atrybutem RequiresPreviewFeaturesAttribute , ta reguła sprawdza, czy witryna wywołania zdecydowała się na funkcje w wersji zapoznawczej. Jeśli ma zastosowanie jedna z następujących opcji, witryna połączeń zdecydowała się na korzystanie z funkcji w wersji zapoznawczej:

  • Znajduje się on w zakresie RequiresPreviewFeaturesAttribute adnotacji.
  • Jest to część zestawu lub modułu, który już zdecydował się na funkcje w wersji zapoznawczej.

Na poniższej ilustracji przedstawiono przykład diagnostyki CA2252.

Code editor with CA2252 warning.

Lib Oto typ wersji zapoznawczej skonstruowany w metodzie Main . Main sama w sobie nie jest oznaczona adnotacją jako metoda w wersji zapoznawczej, dlatego diagnostyka jest generowana na dwóch wywołaniach konstruktorów wewnątrz Mainelementu .

Jak naprawić naruszenia

Istnieją dwa sposoby naprawiania naruszeń:

  • Przełącz witrynę wywołania w zakresie adnotacji, dodając adnotację do elementu nadrzędnego za pomocą polecenia RequiresPreviewFeaturesAttribute. W poprzednim przykładzie APreviewMethod element jest adnotacją z atrybutem RequiresPreviewFeatures , więc analizator ignoruje użycie typu podglądu wewnątrz APreviewMethodelementu . Wynika to z tego, że osoby wywołujące APreviewMethod będą musiały wykonać podobne ćwiczenie.

  • Możesz również wyrazić zgodę na korzystanie z funkcji w wersji zapoznawczej na poziomie zestawu lub modułu. Wskazuje to analizatorowi, że użycie typu podglądu w zestawie jest pożądane, a w konsekwencji żadne błędy nie zostaną wygenerowane przez tę regułę. Jest to preferowany sposób korzystania z zależności w wersji zapoznawczej. Aby włączyć funkcje w wersji zapoznawczej wewnątrz całego zestawu, ustaw właściwość EnablePreviewFeatures w .csproj pliku:

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

Kiedy pomijać ostrzeżenia

Pomijanie ostrzeżeń z tej reguły jest zalecane tylko w przypadku zaawansowanych przypadków użycia, w których diagnostyka interfejsów API musi być jawnie wyłączona. W takim przypadku musisz być gotów odpowiednio wziąć na siebie odpowiedzialność za oznaczanie interfejsów API w wersji zapoznawczej. Rozważmy na przykład przypadek, w którym istniejący typ implementuje nowy interfejs w wersji zapoznawczej. Ponieważ cały typ nie może być oznaczony jako wersja zapoznawcza (w celu zapewnienia zgodności z poprzednimi wersjami), diagnostyka wokół definicji typu może być wyłączona lokalnie. Ponadto należy oznaczyć implementacje interfejsu w wersji zapoznawczej jako wersja zapoznawcza. Teraz istniejący typ może być używany tak jak poprzednio, ale wywołania nowych metod interfejsu będą uzyskiwać diagnostykę. System.Private.CoreLib.csproj używa tej techniki do uwidaczniania ogólnych funkcji matematycznych na typach liczbowych, takich jak Int32, Doublei Decimal.

Na poniższych obrazach pokazano, jak lokalnie wyłączyć analizator CA2252.

CA2252 - Suppress Detect Preview Feature Diagnostic

CA2252 - Mark Interface Implementations Explicitly

Uwaga

Jeśli wszystkie następujące elementy mają zastosowanie, mogą pojawić się ostrzeżenia fałszywie dodatnie z tej reguły:

  • Używasz programu Visual Studio 2022 w wersji 17.5 lub nowszej ze starszą wersją zestawu .NET SDK, czyli platformą .NET 6 lub starszą.
  • Używasz analizatorów z zestawu .NET 6 SDK lub starszej wersji pakietów analizatora, takich jak Microsoft.CodeAnalysis.FxCopAnalyzers.

W takim przypadku można bezpiecznie pominąć ostrzeżenie fałszywie dodatnie. Wyniki fałszywie dodatnie są spowodowane zmianą powodującą niezgodność w kompilatorze języka C#. Rozważ użycie nowszego analizatora zawierającego poprawkę dla ostrzeżeń fałszywie dodatnich. Przeprowadź uaktualnienie do wersji Microsoft.CodeAnalysis.NetAnalyzers w wersji 7.0.0-preview1.22464.1 lub nowszej lub użyj analizatorów z zestawu .NET 7 SDK.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby wyłączyć tę całą kategorię reguł, ustaw ważność dla kategorii na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Zobacz też