CA2252: Aceitar versões prévias dos recursos antes de usá-los

Property	Valor
ID da regra	CA2252
Título	Aceitar versões prévias dos recursos antes de usá-los
Categoria	Usage
Correção interruptiva ou sem interrupção	Sem interrupção
Habilitado por padrão no .NET 8	Como erro

Causa

Um cliente usa APIs ou tipos de versão prévia em seu assembly sem aceitar de modo explícito localmente ou no nível do módulo ou do assembly.

Descrição da regra

Quando uma API ou um assembly decorado com o atributo RequiresPreviewFeaturesAttribute é consumido, essa regra verifica se o site de chamada aceitou versões prévias dos recursos. Um site de chamada terá aceitado versões prévias dos recursos se um dos seguintes se aplicar:

• Ele está dentro do escopo de uma anotação RequiresPreviewFeaturesAttribute.
• Ele faz parte de um assembly ou módulo que já aceitou versões prévias dos recursos.

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

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

Como corrigir violações

Há duas maneiras de corrigir violações:

• Traga um site de chamada dentro do escopo de uma anotação anotando seu pai com RequiresPreviewFeaturesAttribute. No exemplo anterior, APreviewMethod é anotado com o atributo RequiresPreviewFeatures, portanto, o analisador ignora o uso de tipo de versão prévia dentro de APreviewMethod. Os chamadores de APreviewMethod precisarão executar um exercício semelhante.

• Você também pode optar pelas versões prévias dos recursos em um nível de assembly ou módulo. Isso indica ao analisador que o uso de tipo de versão prévia no assembly é desejado e, como consequência, nenhum erro será produzido por essa regra. Essa é a maneira preferencial de consumir dependências de versão prévia. Para habilitar versões prévias dos recursos dentro de todo o assembly, defina a propriedade EnablePreviewFeatures em um arquivo .csproj:

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

Quando suprimir avisos

Suprimir avisos dessa regra só é recomendado para casos de uso avançados em que o diagnóstico em APIs precisa ser desabilitado explicitamente. Nesse caso, você deve estar disposto a assumir a responsabilidade por marcar as APIs de versão prévia adequadamente. Por exemplo, considere um caso em que um tipo existente implementa uma nova interface de versão prévia. Como o tipo inteiro não pode ser marcado como versão prévia (para compatibilidade com versões anteriores), o diagnóstico em torno da definição de tipo pode ser desabilitado localmente. Além disso, você precisa marcar as implementações da interface de versão prévia como versão prévia. 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, Double e Decimal.

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

Observação

Você pode ver avisos de falsos positivos desta regra se todos os itens a seguir 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.

Nesse caso, é seguro suprimir um aviso falso positivo. Os falsos positivos são devido a uma alteração interruptiva no compilador de C#. Considere usar 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

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar 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 em um arquivo, uma pasta ou um projeto, defina a severidade como none no arquivo de configuração.

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

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

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

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

Confira também

• EnablePreviewFeatures e GenerateRequiresPreviewFeaturesAttribute
• Documento de design de versão prévia do recurso