CA2252: Opte por visualizar recursos antes de usá-los

Artigo
12/16/2023

Property	valor
ID da regra	CA2252
Título	Opte por visualizar recursos antes de usá-los
Categoria	Utilização
A correção está quebrando ou não quebrando	Sem quebra
Habilitado por padrão no .NET 8	Como erro

Motivo

Um cliente usa APIs ou tipos de visualização em seu assembly sem optar explicitamente por participar localmente ou no nível de módulo ou assembly.

Descrição da regra

Quando uma API ou assembly decorado com o atributo é consumido, essa regra verifica se o RequiresPreviewFeaturesAttribute site de chamada optou por visualizar recursos. Um site de chamada optou por visualizar recursos se uma das seguintes situações se aplicar:

Está dentro do âmbito de uma RequiresPreviewFeaturesAttribute anotação.
Ele faz parte de um assembly ou módulo que já optou por visualizar recursos.

A imagem a seguir mostra um exemplo do diagnóstico CA2252.

Aqui, Lib é um tipo de visualização que é construído no Main método. Main em si não é anotado como um método de visualização, portanto, o diagnóstico é produzido nas duas chamadas de construtores dentro do Main.

Como corrigir violações

Há duas maneiras de corrigir violações:

Coloque um site de chamada no escopo de uma anotação anotando seu pai com RequiresPreviewFeaturesAttribute. No exemplo anterior, é anotado com o atributo, portanto, APreviewMethod o analisador ignora o RequiresPreviewFeatures uso do tipo de visualização dentro do APreviewMethod. Daqui resulta que os interlocutores terão de APreviewMethod realizar um exercício semelhante.
Você também pode optar por visualizar recursos em um nível de montagem ou módulo. Isso indica ao analisador que o uso do tipo de visualização no assembly é desejado e, como consequência, nenhum erro será produzido por essa regra. Essa é a maneira preferida de consumir dependências de visualização. Para habilitar os recursos de visualização dentro de todo o assembly, defina a propriedade EnablePreviewFeatures em um .csproj arquivo:

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

Quando suprimir avisos

A supressão de avisos dessa regra só é recomendada para casos de uso avançados em que o diagnóstico em APIs precisa ser explicitamente desabilitado. Nesse caso, você deve estar disposto a assumir a responsabilidade de marcar APIs de visualização adequadamente. Por exemplo, considere um caso em que um tipo existente implementa uma nova interface de visualização. Como todo o tipo não pode ser marcado como visualização (para compatibilidade com versões anteriores), o diagnóstico em torno da definição de tipo pode ser desativado localmente. Além disso, você precisa marcar as implementações da interface de visualização como visualização. Agora, o tipo existente pode ser usado como antes, mas as chamadas para os novos métodos de interface receberão diagnóstico. System.Private.CoreLib.csproj usa essa técnica para expor recursos matemáticos genéricos em tipos numéricos como Int32, Doublee Decimal.

As imagens a seguir mostram como desativar o analisador CA2252 localmente.

Nota

Poderá ver avisos falsos positivos desta regra se todas as seguintes situações se aplicarem:

Você está usando o Visual Studio 2022 versão 17.5 ou posterior com uma versão mais antiga do SDK do .NET, ou seja, .NET 6 ou anterior.
Você está usando os analisadores do SDK do .NET 6 ou uma versão mais antiga dos pacotes do analisador, como Microsoft.CodeAnalysis.FxCopAnalyzers.

Neste caso, é seguro suprimir um aviso falso positivo. Os falsos positivos são devidos a uma mudança de quebra no compilador C#. Considere o uso de um analisador mais recente que contenha a correção para os avisos de falsos positivos. Atualize para Microsoft.CodeAnalysis.NetAnalyzers versão 7.0.0-preview1.22464.1 ou mais recente ou use os analisadores do SDK do .NET 7.

Suprimir um aviso

Se você quiser apenas suprimir uma única violação, adicione diretivas de pré-processador ao seu arquivo de origem para desativar e, em seguida, reativar a regra.

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

Para desabilitar a regra para um arquivo, pasta ou projeto, defina sua severidade como none no arquivo de configuração.

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

Para desativar toda essa categoria de regras, defina a severidade da categoria como none no arquivo de configuração.

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

Para obter mais informações, consulte Como suprimir avisos de análise de código.

Partilhar via