CA2252: Acconsentire esplicitamente alle funzionalità di anteprima prima di usarle

Proprietà	valore
ID regola	CA2252
Title	Acconsentire esplicitamente alle funzionalità di anteprima prima di usarle
Categoria	Utilizzo
Correzione che causa un'interruzione o un'interruzione	Nessuna interruzione
Abilitato per impostazione predefinita in .NET 8	Come errore

Causa

Un client usa api o tipi di anteprima nell'assembly senza acconsentire esplicitamente a livello locale o a livello di modulo o assembly.

Descrizione regola

Quando viene utilizzata un'API o un assembly decorato con l'attributo RequiresPreviewFeaturesAttribute , questa regola controlla se il sito di chiamata ha acconsento esplicitamente alle funzionalità di anteprima. Un sito di chiamata ha acconsento esplicitamente alle funzionalità di anteprima se si applica uno dei seguenti elementi:

• È all'interno dell'ambito di un'annotazione RequiresPreviewFeaturesAttribute .
• Fa parte di un assembly o di un modulo che ha già scelto di visualizzare in anteprima le funzionalità.

L'immagine seguente mostra un esempio della diagnostica CA2252.

Lib Ecco un tipo di anteprima costruito nel Main metodo . Main se stesso non viene annotato come metodo di anteprima, quindi la diagnostica viene prodotta nelle due chiamate ai due costruttori all'interno Maindi .

Come correggere le violazioni

Esistono due modi per correggere le violazioni:

• Portare un sito di chiamata nell'ambito di un'annotazione annotando il relativo elemento padre con RequiresPreviewFeaturesAttribute. Nell'esempio precedente, APreviewMethod viene annotato con l'attributo , quindi l'analizzatore ignora l'utilizzo RequiresPreviewFeatures del tipo di anteprima all'interno APreviewMethoddi . Segue che i chiamanti di APreviewMethod dovranno eseguire un esercizio simile.

• È anche possibile acconsentire esplicitamente alle funzionalità di anteprima a livello di assembly o modulo. Ciò indica all'analizzatore che l'utilizzo del tipo di anteprima nell'assembly è desiderato e, di conseguenza, non verrà generato alcun errore da questa regola. Questo è il modo preferito per utilizzare le dipendenze di anteprima. Per abilitare le funzionalità di anteprima all'interno dell'intero assembly, impostare la proprietà EnablePreviewFeatures in un .csproj file:

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

Quando eliminare gli avvisi

L'eliminazione degli avvisi da questa regola è consigliata solo per i casi d'uso avanzati in cui la diagnostica nelle API deve essere disabilitata in modo esplicito. In questo caso, è necessario essere disposti a assumersi la responsabilità di contrassegnare le API di anteprima in modo appropriato. Si consideri, ad esempio, un caso in cui un tipo esistente implementa una nuova interfaccia di anteprima. Poiché l'intero tipo non può essere contrassegnato come anteprima (per compatibilità con le versioni precedenti), la diagnostica relativa alla definizione del tipo può essere disabilitata localmente. Inoltre, è necessario contrassegnare le implementazioni dell'interfaccia di anteprima come anteprima. Ora, il tipo esistente può essere usato come in precedenza, ma le chiamate ai nuovi metodi di interfaccia otterranno la diagnostica. System.Private.CoreLib.csproj usa questa tecnica per esporre funzionalità matematiche generiche su tipi numerici come Int32, Doublee Decimal.

Le immagini seguenti illustrano come disabilitare l'analizzatore CA2252 in locale.

Nota

Se si applicano tutti gli avvisi seguenti, è possibile che vengano visualizzati avvisi falsi positivi da questa regola:

• Si usa Visual Studio 2022 versione 17.5 o successiva con una versione precedente di .NET SDK, ovvero .NET 6 o versioni precedenti.
• Si usano gli analizzatori di .NET 6 SDK o una versione precedente dei pacchetti analizzatori, ad esempio Microsoft.CodeAnalysis.FxCopAnalyzers.

In questo caso, è possibile eliminare un avviso falso positivo. I falsi positivi sono dovuti a una modifica che causa un'interruzione nel compilatore C#. Prendere in considerazione l'uso di un analizzatore più recente che contiene la correzione per gli avvisi falsi positivi. Eseguire l'aggiornamento a Microsoft.CodeAnalysis.NetAnalyzers versione 7.0.0-preview1.22464.1 o successiva o usare gli analizzatori di .NET 7 SDK.

Eliminare un avviso

Se si vuole eliminare una singola violazione, aggiungere direttive del preprocessore al file di origine per disabilitare e quindi riabilitare la regola.

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

Per disabilitare la regola per un file, una cartella o un progetto, impostarne la gravità none su nel file di configurazione.

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

Per disabilitare questa intera categoria di regole, impostare la gravità per la categoria su none nel file di configurazione.

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

Per altre informazioni, vedere Come eliminare gli avvisi di analisi del codice.

Vedi anche

• EnablePreviewFeatures e GenerateRequiresPreviewFeaturesAttribute
• Documento di progettazione delle funzionalità di anteprima